api-routes.md

API routes

!!! note "Generated page" scripts/docs/gen_routes.py builds this page from the code. Text that needs a person lives in scripts/docs/descriptions.yml. Edit that file, not this page.

Paths are relative to the app. API_ROOT_PATH, default /api, sets the FastAPI root path.

The Auth column uses three values:

• API key routes pass through get_api_key, which compares the header named by CONSERVER_HEADER_NAME with the keys from CONSERVER_API_TOKEN and CONSERVER_API_TOKEN_FILE. With no keys configured, the check is skipped and the route is open.
• ingress API key routes call validate_ingress_api_key, which checks the same header against the ingress_auth section of the configuration for the named ingress list. With no match the API returns 403, including when ingress_auth is empty.
• none routes have no check.

api/api.py defines 20 routes.

Method	Path	Auth	Success status	Tag	Summary	Notes
GET	/config	API key	200	config	Get system config
POST	/config	API key	204	config	Update system config
GET	/dlq	API key	200	dlq	Get DLQ contents
POST	/dlq/reprocess	API key	200	dlq	Reprocess DLQ
GET	/dlq/storage	API key	200	dlq	Get storage DLQ contents
POST	/dlq/storage/reprocess	API key	200	dlq	Retry failed storage writes
GET	/health	none	200	system	Health check
GET	/index_vcons	API key	200	config	Rebuild search index
GET	/stats/queue	none	200	system	Get queue depth
GET	/vcon	API key	200	vcon	Gets a list of vCon UUIDs
POST	/vcon	API key	201	vcon	Create a new vCon
GET	/vcon/count	API key	200	chain	Count vCons in chain	Unreachable. GET /vcon/{vcon_uuid} captures the path and returns 422.
GET	/vcon/egress	API key	204	chain	Removes vCon UUIDs from a chain output	Declared 204. The handler returns a JSON array with 200.
POST	/vcon/external-ingress	ingress API key	204	external	Submit external vCon from 3rd party systems
POST	/vcon/ingress	API key	204	chain	Add vCons to a chain
DELETE	/vcon/{vcon_uuid}	API key	204	vcon	Delete a vCon
GET	/vcon/{vcon_uuid}	API key	200	vcon	Gets a vCon by UUID
GET	/vcons	API key	200	vcon	Gets multiple vCons by UUIDs
GET	/vcons/search	API key	200	vcon	Search vCons by metadata
GET	/version	none	200	system	Get server version

FastAPI is created without turning off its default pages, so /docs, /redoc and /openapi.json are served too, with no check.