Endpoints Reference#

Complete listing of all API endpoints organized by router.

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

UI-Focused Endpoints#

Transfer Router (/api/transfer)#

Read endpoints (anonymous overview, JWT for the rest):

  • GET /overview - Transfer statistics (uniform funnel + per-kind counts)

  • GET /raw-packages - List packages (paginated)

  • GET /transfer-packages - List transfer packages

  • WS /ws/overview - Real-time updates

  • GET /failure-history/{operation_type}/{operation_id} - Durable failure trail for an operation

Uniform reset (admin only) — keyed by the OperationKind model, operating on the Operation row (status→PENDING, retry_count++, history preserved):

  • POST /operation/{kind}/{id}/reset - Reset one operation of a kind ({kind} is an OperationKind value: transfer, unpack, long_term_archive, staging, raw_data_package, data_transfer_package; an unknown kind yields 422)

  • POST /operation/{kind}/reset-all-failed - Reset every FAILED operation of a kind

Reconcile (admin only) — recompute a RawDataPackage’s lifecycle state from its operation chain, draining the inconsistent set (ADR-0004):

  • POST /raw-data-package/{id}/reconcile - Recompute one package’s state

  • POST /raw-data-package/reconcile-inconsistent - Reconcile every package in the inconsistent set

Legacy reset shims (admin only) — the per-id paths are retained as #95-safe shims for callers not yet migrated to the operation-keyed endpoints. They resolve the Operation row(s) behind the legacy row by FK and reset those, never touching the soon-dropped status/counter columns:

  • POST /data-transfer/{id}/reset - Reset failed transfer (legacy shim)

  • POST /long-term-archive/{id}/reset - Reset failed archive transfer (legacy shim)

  • POST /data-transfer/reset-all-failed - Reset all failed transfers (legacy shim)

  • POST /long-term-archive/reset-all-failed - Reset all failed archive transfers (legacy shim)

Authentication: JWT (GitHub OAuth); reset/reconcile actions are admin-gated (ADR-0002)

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 Endpoint Categories for complete categorization and Routers Deep Dive for detailed implementation.