Start and follow a session through the API
Create work once, inspect acceptance, and follow execution to its outcome.
Use the Session API from a trusted server with a workspace API key. The hosted base URL is https://api.uno.engineering. The examples use environment variables so the key does not appear in source.
Read the visual explanation
The same mutation retried with the same idempotency key resolves to the accepted request. Acceptance is followed by turn execution and a completion event.
1. Create the session
Set UNO_API_KEY and UNO_WORKSPACE_ID in your environment, then send:
curl --fail-with-body "https://api.uno.engineering/api/v1/workspaces/$UNO_WORKSPACE_ID/sessions" -H "Authorization: Bearer $UNO_API_KEY" -H "Idempotency-Key: search-fix-create-001" -H "Content-Type: application/json" -d '{"message":"Fix empty-query search results. Preserve category filters, add a regression test, and open a PR."}'Creation uses the workspace's active repositories at their current default-branch heads. This API accepts a message; it does not expose the web composer's full repository, ref, attachment, and model configuration.
A successful request returns 202 Accepted with sessionId, conversationId, acceptedInput, and links. Save the session ID. acceptedInput.status can be materialized when a turn was created or pending while earlier work is active. Acceptance is not completion.
If a request times out, retry the same logical operation with the same key and message. Use a new key for a new operation. Keys must be 8 to 200 characters. Do not reuse a key for a different request.
2. Follow progress
Set UNO_SESSION_ID from the returned sessionId. Read status:
curl --fail-with-body "https://api.uno.engineering/api/v1/sessions/$UNO_SESSION_ID" -H "Authorization: Bearer $UNO_API_KEY"Read latestTurn, conversation activity, pending inputs, and any error. Follow the web link when human review is useful.
For events, open the stream:
curl --no-buffer --fail-with-body "https://api.uno.engineering/api/v1/sessions/$UNO_SESSION_ID/stream?after=0" -H "Authorization: Bearer $UNO_API_KEY"Persist the last SSE event ID and reconnect with Last-Event-ID or after. This is an event cursor. The transcript endpoint's after parameter is a separate message-sequence cursor.
3. Send a follow-up
curl --fail-with-body "https://api.uno.engineering/api/v1/sessions/$UNO_SESSION_ID/messages" -H "Authorization: Bearer $UNO_API_KEY" -H "Idempotency-Key: search-fix-followup-001" -H "Content-Type: application/json" -d '{"message":"Keep the public API unchanged and report any checks that could not run."}'External inputs use the durable turn queue. A follow-up accepted while a turn is live can remain pending until it can be materialized. Inspect acceptance and subsequent status instead of assuming it interrupted the running model immediately.
Read the API reference for fields and access failures. Review the result before treating a completed turn as shipped work.