Endpoints Reference
===================

Complete listing of all API endpoints organized by router.

.. contents:: Table of Contents
   :local:
   :depth: 2

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.