Ingestion Server API

Overview

The ingestion server is a FastAPI service used for file ingestion, SDAC worker operations, session bootstrap, and ingestion operator tooling. The generated OpenAPI artifact is source-backed by create_app().openapi():

docs/openapi/ingestion-server-api.json

Regenerate and check it with:

python -m pip install -r apps/ingestion-server/requirements-web.txt
npm run contracts:ingestion:generate
npm run contracts:ingestion:check

When using a virtualenv, set INGESTION_OPENAPI_PYTHON=/path/to/python.

Replit Boundary

Replit should not call the direct ingestion host by default. UI work should use the Admin UI and widget same-origin routes:

UI need	Replit/default route	Direct ingestion route
Widget session bootstrap	/widget/api/ingestion/sdac/sessions	/sdac/sessions
Widget chat	/widget/api/ingestion/sdac/chat	/sdac/chat
Workbook upload	/widget/api/mastra/sdac/upload	/sdac/upload
Upload status	/widget/api/mastra/sdac/uploads/{jobId}/status	/sdac/uploads/{job_id}/status
Report analysis status	/widget/api/mastra/sdac/report-analysis/{reportId}/status	/sdac/reports/{report_id}/analysis-status

Direct ingestion routes are worker/operator surfaces protected by deployment, APIM, Easy Auth, bearer, or service-secret controls depending on the environment. Use them for backend validation and operator smoke, not browser UI prototyping.

Do not treat the two report-analysis paths as interchangeable. Worker /sdac/reports/{report_id}/analysis-status reports ingestion-side state; widget polling uses Mastra /sdac/report-analysis/{reportId}/status through /widget/api/mastra/sdac/report-analysis/{reportId}/status.

Route Families

Family	Routes	Notes
Health	GET /health, GET /ready	Operational probes.
Generic ingestion UI	GET /, GET /ingestion, POST /ingestion/submit, GET /jobs/{job_id}	Web/operator upload flow.
SDAC upload worker	POST /sdac/upload, GET /sdac/uploads/{job_id}/status	Direct worker upload and polling. Browser clients should use widget /api/mastra/sdac/*.
SDAC sessions and chat	POST /sdac/sessions, GET /sdac/sessions/{session_id}, POST /sdac/chat	Widget-facing flow through same-origin proxy. Chat streams SSE.
SDAC data operations	/sdac/sync, /sdac/costs, /sdac/validate, /sdac/feedback, /sdac/report/{report_id}, /sdac/reports/{report_id}	Testing-safe through widget/Admin UI flows; direct worker access is not the default Replit path.
SDAC registry/tools	/sdac/registry/agents, /sdac/registry/tools, /sdac/registry/workflows, /sdac/tools/{tool_name}	Ingestion-side compatibility/discovery routes.
Operator dashboard	/api/dashboard/*	Internal/operator dashboard data.
API ingestors	/api/ingestors/*	Internal/operator API ingestion source management and runs.

Source And Tests

Area	Source	Tests
FastAPI app/routes	apps/ingestion-server/src/ingestion_server/web/app.py	apps/ingestion-server/tests/unit/web/**
API ingestors	apps/ingestion-server/src/ingestion_server/web/api_ingestor_routes.py	apps/ingestion-server/tests/unit/api_ingestors/test_routes.py
Dashboard API	apps/ingestion-server/src/ingestion_server/web/dashboard_api.py	Web route tests and operator smoke
Widget proxy	apps/widget/server/ingestion-proxy.ts, apps/widget/server/mastra-proxy.ts	apps/widget/server/__tests__/**
Runtime upload proxy	packages/domain-sdac/src/routes/sdac-upload.routes.ts	packages/domain-sdac/tests/routes/sdac-upload-routes.test.ts

Contract Ownership

• docs/openapi/ingestion-server-api.json owns direct FastAPI route schemas.
• docs/openapi/runtime-routes-api.json owns Mastra/runtime SDAC upload proxy route schemas.
• docs/openapi/widget-api.json owns the widget same-origin browser proxy route families.
• apps/admin-ui/api-spec/openapi.yaml owns Admin UI BFF routes.
• docs/internal/documentation-revival/endpoint-catalog.md and .yaml own Replit safety classification, APIM/browser route selection, and direct-service boundary notes.