Session API reference
Requests, responses, scopes, cursors, and failure handling.
Base URL: https://api.uno.engineering. Authenticate with Authorization: Bearer $UNO_API_KEY, using a key from the owning workspace. This reference describes the external Session API, not Uno's internal web endpoints.
Endpoints
| Method and path | Scope | Result |
|---|---|---|
POST /api/v1/workspaces/:workspaceId/sessions | sessions:write | 202, accepted session input |
GET /api/v1/sessions/:sessionId | sessions:read | Session and conversation state |
GET /api/v1/sessions/:sessionId/messages | sessions:read | Ordered transcript entries |
POST /api/v1/sessions/:sessionId/messages | sessions:write | 202, accepted follow-up input |
GET /api/v1/sessions/:sessionId/stream | sessions:read | Server-sent events |
Both POST requests require Content-Type: application/json, an Idempotency-Key of 8 to 200 characters, and a body containing a nonempty message string of at most 20,000 characters. Other web composer options are not part of these request bodies.
Acceptance response
The create and follow-up responses contain:
| Field | Meaning |
|---|---|
sessionId, conversationId | IDs for the accepted work |
status | Session state at response time |
state | Accepted-input state, defaulting to pending |
acceptedInput | Input ID, status, turn ID, errors, and acceptance/materialization times |
materializedTurn | Turn ID when a turn has been materialized; otherwise null |
session, primaryConversation | Compact references |
links | Links for following the work |
Keep the same key and body when retrying an uncertain request. Retrying with a new key can create duplicate work. An accepted input can fail later; inspect its execution outcome.
Status and transcript
Status returns sessionId, workspaceId, conversationId, status, conversationStatus, conversationLifecycle, conversationActivity, lastTurnOutcome, latestTurn, pendingInputCount, timestamps, and links.
latestTurn can be null. Otherwise it includes its ID, status, error code/message, and queued, started, and completed times. Nullable times are not proof that execution reached that milestone.
The messages endpoint returns an array of id, sequence, role, content, and createdAt. Use ?after=<message-sequence> to request messages after the last one consumed. Treat content according to its returned shape rather than assuming it is always a plain string.
Event stream
The stream returns text/event-stream. Each event has an id, event type, and JSON data envelope with sequence, session, conversation, turn, timestamp, type, and event data.
The projection includes input.accepted, input.failed, sandbox.waking, turn.started, turn.completed, turn.failed, turn.cancelled, and session.trace.v1 where recorded. Do not depend on private provider-specific events or assume assistant text is a token-delta stream. Read the transcript for durable messages.
Reconnect with ?after=<event-sequence> or Last-Event-ID. A positive query cursor takes precedence. SSE keepalive comments are not work events. Message and event sequences are different cursors.
Access and errors
Invalid, expired, or revoked keys fail authentication. A missing scope or workspace mismatch is forbidden. Invalid bodies and missing idempotency headers fail validation. Creating or sending work also requires successful workspace billing admission.
Inspect the HTTP error and current session state before retrying. Do not automatically repeat a permanent authorization failure. Close long-lived streams when rotating keys; authentication occurs when the stream connects.
Key management uses separate signed-in administrative endpoints and is covered in API keys. For a complete request sequence, use the workflow guide.