# Endpoints Reference

Complete listing of all API endpoints organized by router.

```{contents} Table of Contents
:depth: 2
:local: true
```

For interactive exploration, visit `http://localhost:8000/docs` (Swagger UI).

## UI-Focused Endpoints

### Transfer Router (`/api/transfer`)

- `GET /overview` - Transfer statistics
- `GET /raw-packages` - List packages (paginated)
- `GET /transfer-packages` - List transfer packages
- `WS /ws/overview` - Real-time updates
- `POST /data-transfer/{id}/reset` - Reset failed transfer

**Authentication**: JWT (GitHub OAuth)

### Observing Program Router (`/observing_program`)

- `GET /` - List programs
- `POST /` - Create program
- `GET /{id}` - Get program
- `PUT /{id}` - Update program
- `DELETE /{id}` - Delete program

### Sources Router (`/sources`)

- `GET /` - List/search sources
- `GET /{id}/chip` - Card view
- `GET /{id}/details` - Detailed view
- `POST /resolve` - Name resolution

### Visibility Router (`/visibility`)

- `GET /{source_id}` - Source visibility
- `GET /heatmap` - Visibility heatmap
- `POST /precalculate` - Trigger precalculation (admin)

## Operations Endpoints

### Executed Obs Units (`/executed_obs_units`)

- `POST /start` - Start observation (buffered)
- `PUT /{id}/finish` - Finish observation (buffered)
- `GET /{obs_unit_id}` - Query observations (smart query)

**Authentication**: API Token

**Buffering**: Enabled (`@critical_operation`)

### Raw Data Files (`/raw_data_files`)

- `POST /` - Register file (buffered)
- `POST /bulk` - Register multiple files (buffered)
- `GET /{id}` - Get file metadata

### Raw Data Package (`/raw_data_package`)

- `POST /` - Create package (buffered)
- `GET /{id}` - Get package
- `PUT /{id}/finalize` - Mark complete

## Shared Endpoints

### Authentication (`/auth`, `/github`, `/api/tokens`)

- `GET /github/login` - OAuth initiation
- `GET /github/callback` - OAuth callback
- `GET /auth/me` - Current user
- `GET /api/tokens/scopes` - Get available scopes
- `POST /api/tokens/` - Create token (one-time display)
- `GET /api/tokens/` - List tokens
- `GET /api/tokens/{id}` - Get token details
- `PUT /api/tokens/{id}` - Update token
- `GET /api/tokens/{id}/usage` - Get usage statistics
- `POST /api/tokens/{id}/regenerate` - Regenerate token
- `DELETE /api/tokens/{id}` - Revoke token
- `POST /api/tokens/bulk-revoke` - Bulk revoke
- `GET /api/tokens/export` - Export token list
- `POST /api/tokens/service` - Create service token (admin only)

### Site Information (`/api/site`, `/health`)

- `GET /api/site/info` - Site configuration
- `GET /health` - Health check
- `GET /buffer-stats` - Buffer statistics

**Authentication**: None (public monitoring)

See {doc}`../architecture/endpoint-categories` for complete categorization and {doc}`../deep-dive/routers/index` for detailed implementation.