Request reference
Fields, responses, and status codes for the session and chat endpoints.
Both endpoints are described narratively in Application endpoints; this page is the scannable reference for their exact fields and status codes.
Create a session
Request body
| Field | Type | Required | Description |
|---|---|---|---|
userId | string | Yes | Your own identifier for this session. Not looked up anywhere. |
Response — 201 Created
| Field | Type | Description |
|---|---|---|
sessionId | string | Identifies the session. Used in every subsequent chat call. |
userId | string | Echoes the userId you sent. |
sessionSecret | string | Required header value for every chat call on this session. |
createdAt | string | ISO 8601 timestamp. |
initialMessage | string | The application's configured Initial Message. |
Status codes
| Status | Meaning |
|---|---|
201 | Session created. |
400 | userId missing from the request body. |
401 | Neither Authorization nor X-Api-Key was sent, or the API key is unknown. |
404 | The API key is valid but doesn't belong to this application's account. |
Send a chat message
Request body
| Field | Type | Required | Description |
|---|---|---|---|
sessionId | string | Yes | From the session endpoint's response. |
message | string | Yes | The user's message. |
Headers
See Authentication for
Authorization/X-Api-Key, and Session endpoint
for x-session-secret.
Response — 200 OK, Content-Type: text/event-stream
A stream of typed events, see The response stream.
Status codes
| Status | Meaning |
|---|---|
200 | The stream has started. Errors that happen afterwards arrive as an error event inside the stream, not as an HTTP status. |
400 | sessionId or message missing from the request body. |
401 | Neither Authorization nor X-Api-Key was sent, or the API key is unknown. |
404 | x-session-secret is missing or doesn't match the session, or sessionId doesn't exist or has expired. The same status covers all three, deliberately, so a request can't be used to probe for valid session IDs. |
A 404 from the chat endpoint doesn't distinguish a wrong secret from an
expired session, by design. If you see one, the safe recovery is always
the same: call the session endpoint again and start a new session.
End a session early
Sessions expire on their own after 1 hour, but you can delete one before that:
Requires the same Authorization/X-Api-Key header as the other endpoints.
| Status | Meaning |
|---|---|
204 | Session deleted. |
401 | Neither Authorization nor X-Api-Key was sent, or the API key is unknown. |
404 | sessionId doesn't exist. |
Error response shape
Every error, whether it's an authentication failure, a validation error, or a session that couldn't be found, comes back with the same shape:
Use the HTTP status code to branch on the kind of error, and message for a
human-readable description.