Chat API

Overview

The SDAC Chat API provides a streaming Server-Sent Events (SSE) interface for report review. Clients use it for targeted questions, multi-turn conversations, and agent-driven validation workflows.

Two customer-facing agent profiles are supported through the same endpoint:

Agent ID	Use Case
`sdac-coordinator-release`	Default. Fast position-first review, fringe analysis, quarter comparison, and replacement cross-reference
`sdac-review-coordinator`	Full-category review, sendback preparation, and broader validation coverage

Authentication

Widget clients call the same-origin proxy. Direct APIM callers must use an environment-published runtime route and send:

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

See Authentication for the full header contract and Response Formats for the broader response-style guide.

Endpoint

Attribute	Value
Endpoint	`POST /api/ingestion/sdac/chat`
Method	`POST`
Content-Type	`application/json`
Response	SSE stream

Request

{
  "reportId": "8201EDC2-2EDE-4CA1-AF44-D0F5AA185CDB",
  "message": "What is the fringe variance for this report?",
  "userId": "auditor@state.gov",
  "sessionId": "browser-session-abc123",
  "conversationId": "browser-session-abc123",
  "agentId": "sdac-coordinator-release"
}

Field	Type	Required	Description
`message`	string	Yes	User question or instruction
`userId`	string	Yes	Authenticated user identifier
`sessionId`	string	Yes	Browser or client session identifier
`reportId`	UUID string	No	Uploaded report identifier. Recommended when available
`conversationId`	string	No	Existing conversation to continue
`districtId`	string	No	District identifier used when no `reportId` is loaded
`districtName`	string	No	Display name for district context
`quarter`	string	No	Requested quarter, such as `Q1`
`year`	string	No	Requested year, such as `2025`
`agentId`	string	No	Agent profile to use. Defaults to `SDAC_DEFAULT_AGENT_ID`, then `sdac-coordinator-release`

Context Rules

If reportId is provided, chat is bound to that uploaded report.
If reportId is omitted, provide districtId and optionally quarter and year so the agent can fetch the latest available report context.
If neither reportId nor district context is provided, the assistant can only give generic guidance.

Response

The response is an SSE stream. Events arrive in this order:

metadata
Zero or more tool-start, tool-result, warning, and delta events
usage
done

SSE Event Types

Event	Description
`metadata`	Sent first. Conversation context for the current request
`tool-start`	A tool execution started
`tool-result`	A tool execution finished
`warning`	Structured runtime warning, such as quarter fallback when district data is unavailable for the requested period
`delta`	Incremental assistant text
`usage`	Prompt and completion token counts
`done`	Stream completed successfully
`error`	Stream failed

Event Payloads

metadata

{
  "conversationId": "browser-session-abc123",
  "turnNumber": 1,
  "isNewConversation": true,
  "conversationExpired": false
}

Field	Type	Description
`conversationId`	string	Persist this value for follow-up requests
`turnNumber`	number	Turn number for the current user message
`isNewConversation`	boolean	`true` if the request started a new conversation
`conversationExpired`	boolean	`true` if a prior conversation was expired and replaced

tool-start

{
  "toolCallId": "call-uuid",
  "toolName": "sdac-validate-fringe",
  "displayName": "Analyzing fringe rates"
}

tool-result

{
  "toolCallId": "call-uuid",
  "toolName": "sdac-validate-fringe",
  "success": true,
  "summary": "Found 2 errors, 1 warning"
}

warning

{
  "type": "quarter-fallback",
  "message": "No data found for Q1 2026. The last known good data from TherapyLog is Q3 2025 (21 records).",
  "requested_quarter": "Q1",
  "requested_year": "2026",
  "actual_quarter": "Q3",
  "actual_year": "2025"
}

delta

{ "content": "Fringe is 8.7% above threshold." }

usage

{
  "promptTokens": 1200,
  "completionTokens": 85
}

done

{
  "success": true,
  "conversationId": "browser-session-abc123",
  "conversationSk": 12345,
  "turnNumber": 2
}

Use conversationSk and the assistant turnNumber from the done event when submitting feedback.

error

{ "message": "Chat request failed" }

Session and Feedback Handling

Store conversationId from the metadata event and send it on the next request.
Store conversationSk and assistant turnNumber from the done event for feedback submission.
The first assistant response in a new conversation typically returns metadata.turnNumber = 1 and done.turnNumber = 2.

Side Effects

Each request can create or resume a persisted conversation thread.
The service records assistant-turn metadata so the completed turn can be rated later.
Runtime warnings such as quarter fallback are emitted into the stream as first-class warning events rather than being buried in prose.

Error Responses

Status	Description
400	Invalid request body or unknown `agentId`
401	Missing or expired bearer token
403	Invalid subscription key or insufficient API scope
500	Chat execution failed

Examples

Start a Conversation for an Uploaded Report

curl -N -X POST "$WIDGET_BASE_URL/api/ingestion/sdac/chat" \
  -H "Content-Type: application/json" \
  -d '{
    "reportId": "8201EDC2-2EDE-4CA1-AF44-D0F5AA185CDB",
    "message": "What is the fringe variance for this report?",
    "userId": "auditor@state.gov",
    "sessionId": "browser-session-abc123",
    "agentId": "sdac-coordinator-release"
  }'

Start a Conversation from District Context

curl -N -X POST "$WIDGET_BASE_URL/api/ingestion/sdac/chat" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Compare this quarter with the prior year and flag the largest changes.",
    "userId": "auditor@state.gov",
    "sessionId": "browser-session-abc123",
    "districtId": "12345",
    "districtName": "Maplewood Richmond Heights",
    "quarter": "Q1",
    "year": "2026",
    "agentId": "sdac-review-coordinator"
  }'

Continue an Existing Conversation

curl -N -X POST "$WIDGET_BASE_URL/api/ingestion/sdac/chat" \
  -H "Content-Type: application/json" \
  -d '{
    "reportId": "8201EDC2-2EDE-4CA1-AF44-D0F5AA185CDB",
    "message": "Which positions need district follow-up first?",
    "userId": "auditor@state.gov",
    "sessionId": "browser-session-abc123",
    "conversationId": "browser-session-abc123",
    "agentId": "sdac-coordinator-release"
  }'

Operational Notes

This endpoint is streaming-only. Clients must parse SSE events.
Quarter fallback is explicit. If a warning event says the requested period is unavailable, do not present fallback data as if it were the requested quarter.
Tool IDs in tool-start and tool-result match the SDAC tool catalog documented in Validation Tools.
For a dedicated description of the comprehensive reviewer, see Full Review Coordinator.

Overview​

Authentication​

Endpoint​

Request​

Context Rules​

Response​

SSE Event Types​

Event Payloads​

Session and Feedback Handling​

Side Effects​

Error Responses​

Examples​

Start a Conversation for an Uploaded Report​

Start a Conversation from District Context​

Continue an Existing Conversation​

Operational Notes​