Widget API

Overview

The SDAC widget browser calls its own origin. It does not call the ingestion worker or Mastra runtime directly. The widget server exposes health/config routes and two same-origin proxy families:

• /api/ingestion/* forwards to ingestion-compatible SDAC routes.
• /api/mastra/* forwards to Mastra/runtime SDAC routes.

The generated OpenAPI artifact is:

docs/openapi/widget-api.json

Regenerate and check it with:

npm run contracts:widget:generate
npm run contracts:widget:check

Replit Boundary

In Replit, run the widget locally and point it at testing APIs through APIM. Browser code should use the same-origin widget routes, usually under the hosted /widget base path:

UI need	Widget/Replit route	Upstream owner
Runtime config	GET /widget/api/config	Widget server
Session bootstrap	POST /widget/api/ingestion/sdac/sessions	Ingestion/runtime compatibility
Chat stream	POST /widget/api/ingestion/sdac/chat	Ingestion/runtime compatibility
Feedback	POST /widget/api/ingestion/sdac/feedback	Ingestion/runtime compatibility
Validation	POST /widget/api/ingestion/sdac/validate	Ingestion/runtime compatibility
Cost lookup	GET /widget/api/ingestion/sdac/costs	Ingestion/runtime compatibility
Workbook upload	POST /widget/api/mastra/sdac/upload	Mastra runtime
Upload polling	GET /widget/api/mastra/sdac/uploads/{jobId}/status	Mastra runtime
Analysis polling	GET /widget/api/mastra/sdac/report-analysis/{reportId}/status	Mastra runtime

The widget server attaches upstream credentials server-side. Do not put APIM subscription keys, ingestion worker secrets, or Mastra service credentials in browser code.

Contract Ownership

• docs/openapi/widget-api.json owns the browser/Replit same-origin route families and auth/proxy boundary.
• docs/openapi/ingestion-server-api.json owns direct ingestion worker/web schemas.
• docs/openapi/runtime-routes-api.json owns direct Mastra SDAC runtime route schemas.
• docs/internal/documentation-revival/endpoint-catalog.md and .yaml own APIM route safety, mutation class, and Replit handoff notes.

Source And Tests

Area	Source	Tests
Route registration	apps/widget/server/routes.ts	apps/widget/server/__tests__/routes.test.ts
Ingestion proxy	apps/widget/server/ingestion-proxy.ts	apps/widget/server/__tests__/routes.test.ts
Mastra proxy	apps/widget/server/mastra-proxy.ts	apps/widget/server/__tests__/routes.test.ts, apps/widget/server/__tests__/mastra.integration.test.ts
Client upload/session calls	apps/widget/client/src/lib/ingestion-api.ts, apps/widget/client/src/lib/session-api.ts, apps/widget/client/src/lib/costs-api.ts	apps/widget/client/src/lib/__tests__/**, apps/widget/tests/e2e/widget.spec.ts