API Contract Summary

This section summarizes the primary integration surface for clients of the Agentic Vehicle Experience. Complete endpoint specifications are in docs/VSA_API_CONTRACT.md in the AVX repository.

POST /assistant/chat

The primary web and mobile client entry point. Sends a conversational turn to the AVX agent and receives a text response with optional citations and classification metadata.

Authentication: Cognito ID token in the Authorization: Bearer header. Persona is inferred server-side from the token’s Cognito group claims; no persona parameter is required from the client.

Request body:

{
  "prompt": "What does DTC P0420 mean for my vehicle?",
  "sessionId": "session_ms1719340_r8abc123xyz",
  "vin": "1AAAA00A0AA000123"
}

POST /assistant/chat request fields

Field	Required	Description
prompt	Yes	The conversational utterance from the user.
sessionId	Yes	Client-generated session identifier. Must be at least 33 characters to satisfy the AgentCore session-ID minimum length requirement. Recommended format: session_{timestamp}_{randomSuffix} where timestamp is an epoch-ms string.
vin	No	Vehicle Identification Number for context scoping. When present, the agent resolves vehicle identity, live state, and service history for this VIN. Use a synthetic value (1AAAA00A0AA000123) for integration testing.

Response body (200):

{
  "result": "DTC P0420 indicates catalyst system efficiency is below the threshold ...",
  "sessionId": "session_ms1719340_r8abc123xyz",
  "classification": "P2",
  "vin": "1AAAA00A0AA000123",
  "citations": ["dtc-P0420.md", "tsb-2024-en-0298.md"]
}

POST /assistant/chat response fields

Field	Description
result	The agent’s natural-language response to the prompt.
sessionId	Echoed from the request; use for multi-turn continuity.
classification	Triage severity assigned by the classifier: P0 (safety-critical), P1 (service-now), P2 (service-soon), P3 (monitor). Present when the conversation surfaces a diagnosable condition; null for general queries.
vin	Echoed from the request when present.
citations	Array of knowledge-base document references that grounded the response. Empty array when no KB retrieval occurred.

Error codes:

POST /assistant/chat error codes

HTTP Status	Meaning
400	Malformed request body or missing required fields.
401	Missing or invalid Cognito ID token.
403	Authenticated but not authorized for this tenant (token custom:tenantId mismatch).
429	Rate limit exceeded (API Gateway default throttle: 100 req/s steady, 50 burst).
500	Agent runtime error. Check CloudWatch logs for the api-assistant-chat Lambda log group.

REST Endpoints

All REST endpoints share the same Cognito JWT authentication and error model as /assistant/chat. The base URL is the prod stage of the AVX vsa-{stage}-api API Gateway, emitted as a CloudFormation output.

AVX REST API endpoints

Endpoint	Method	Purpose
/assistant/chat	POST	Conversational agent entry point (see above).
/triage	POST	Deterministic P0–P3 triage classifier. Request: {"vin": "1AAAA00A0AA000123", "sessionId": "…​"}. Response: {"classification": "P1", "decidedAt": "…​", "latencyMs": 642}.
/vehicles/{vehicleId}/live-state	GET	Returns the last-known state of a vehicle: odometer, fuel/charge level, active DTCs, and location. Backed by the CMS Redis live-key-state store.
/vehicles/{vehicleId}/service-history	GET	Returns the ordered list of service events for a vehicle from the CMS DynamoDB service-history table.
/vehicles/{vehicleId}/trips	GET	Returns recent trip records for a vehicle. Supports limit and startAfter pagination parameters.
/vehicles/{vehicleId}/safety-events	GET	Returns safety-event records (hard braking, collision signals, geofence violations) for a vehicle.
/drivers/me	GET	Returns the profile and linked vehicles for the authenticated driver, resolved from the Cognito token sub.
/escalate	POST	Initiates a human handoff. Starts an Amazon Connect chat (StartChatContact) on the tenant’s chat queue with the triage context in contact attributes and returns the participant credentials. On a verified P0 it can also write a roadside request to vsa-{stage}-rsa-dispatch and place a callback to the assigned driver.
/tenants/{tenantId}/config	GET	Returns the public subset of tenant configuration (branding, feature flags, voice settings). Internal fields such as ARNs, queue IDs, and triage-policy thresholds are not returned.

WebSocket API

The WebSocket API provides server-push messaging to connected clients.

Connect URL: wss://{wsApiId}.execute-api.{region}.amazonaws.com/prod?token={cognitoIdToken}

The Lambda authorizer validates the Cognito ID token on connect; the connection is rejected with HTTP 401 if validation fails. On successful connect, the connection ID is recorded in the vsa-{stage}-ws-connections DynamoDB table alongside the resolved tenantId.

Server-to-client messages: the deployed platform does not push server-initiated messages. To add streaming telemetry or reasoning events, implement a publisher Lambda that reads the CMS Redis live-key-state layer and posts to connected WebSocket clients via the API Gateway Management API @connections endpoint.

Client-to-server messages: any message sent by the client is acknowledged with {"ack": true} and otherwise ignored at present.

Authentication Summary

Authentication mechanisms by channel

Channel	Mechanism
REST API	Authorization: Bearer {cognitoIdToken} header. Validated by API Gateway custom Lambda authorizer.
WebSocket	?token={cognitoIdToken} query parameter on connect URL. Validated by the same Lambda authorizer.
Voice (Nova 2 Sonic / bidirectional)	SigV4-signed WebSocket upgrade to the AgentCore runtime endpoint. The Cognito ID token is forwarded in the request payload (payload.jwt) because the AgentCore HTTP layer does not forward custom headers to the handler.
AgentCore text runtime	HTTP POST to the AgentCore runtime endpoint, SigV4-signed. Cognito token forwarded in payload.