SDAC API

Overview

SDAC exposes a small external API surface for validation, report metadata, streaming chat, and response feedback. Embedded widget clients call same-origin proxy routes under /api/ingestion/sdac/* and /api/mastra/sdac/*; direct gateway integrations use APIM-published runtime routes when those paths are enabled for the environment.

The source-backed runtime routes are documented in the generated OpenAPI files under docs/openapi/. APIM may add an /ai prefix in testing, but browser widget code should not call APIM directly.

If you are embedding the SDAC widget rather than calling the gateway directly, see Widget Integration for the browser-to-widget and widget-to-ingestion flow.

Authentication

Direct APIM callers authenticate through APIM with:

Authorization: Bearer {access_token}
Ocp-Apim-Subscription-Key: {subscription_key}

Widget browser clients do not send those headers to /api/ingestion/... or /api/mastra/...; they use the same-origin widget proxy instead. See Authentication for the full gateway and widget access model.

Foundation Pages

Use these pages before integrating a specific endpoint:

Authentication

Direct gateway auth headers and widget access boundaries

Environments

Base URLs, scopes, and health endpoints

Quick Start

Minimal gateway and widget-first examples

Response Formats

JSON, SSE, passthrough, and HTML response patterns

File Uploads

Workbook upload surfaces and duplicate handling

Documentation Boundary

This external documentation set covers the supported gateway APIs, the widget-facing same-origin proxy routes, and the tool IDs that can surface in chat progress events.

Raw /sdac/tools/* and /sdac/registry/* proxy routes are not documented here as public integration endpoints. They are implementation surfaces behind the customer-facing chat, validation, and workflow experiences.

Available Endpoints

Endpoint	Method	Description
`/api/ingestion/sdac/chat`	`POST`	Widget-safe streaming chat for report review, session continuation, and agent selection
`/api/ingestion/sdac/validate`	`POST`	Widget-safe issue list and summary for a report
`/api/ingestion/sdac/report/{reportId}`	`GET`	Widget-safe lightweight report header metadata
`/api/ingestion/sdac/feedback`	`POST`	Widget-safe rating submission for a persisted assistant response
`/sdac/feedback/stats/{agentId}`	`GET`	Runtime feedback metrics for an agent; use through APIM only when the environment publishes it

Core Integration Flow

Upload a workbook with the Upload API, or start from district context in chat if your integration already knows the district and quarter.
Use the Report Info API to populate header metadata and the Validation API to generate a baseline issue list.
Use the Chat API for targeted questions, position-level review, or full-review coordination.
Persist the conversationId from the chat metadata event and the conversationSk plus assistant turnNumber from the chat done event.
Submit user ratings with the Feedback API.

Standard Error Responses

Exact status codes vary by endpoint, but these are the standard cases:

Status	Description
400	Bad Request: missing fields, invalid identifiers, or unsupported request format
401	Unauthorized: missing or expired bearer token
403	Forbidden: invalid subscription key or insufficient API scope
404	Not Found: report or route does not exist
500	Internal Server Error: unexpected processing failure