Save Session
const url = 'https://example.com/api/v1/org/example/ws/example/sessions';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"agent":"example","id":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","labels":{"additionalProperty":["example"]},"message_count":0,"model":"example","origin":"user","project_id":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","runtime_id":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","title":"example","visibility":"private"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://example.com/api/v1/org/example/ws/example/sessions \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "agent": "example", "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "labels": { "additionalProperty": [ "example" ] }, "message_count": 0, "model": "example", "origin": "user", "project_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "runtime_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "title": "example", "visibility": "private" }'Save a chat session’s metadata.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”Organization slug
Organization slug
Workspace slug
Workspace slug
Request Body required
Section titled “Request Body required ”Request to create/save a session.
object
Session ID (UUID) generated by the client
Number of messages in the session
Model used for the session
Session origin (SES-ORG-001/003). Defaults to user. Worker-bound clients override to worker; the evaluation service calls the service layer directly with eval. Supplying a non-default value is the procedural responsibility of the registered writer (SES-ORG-004).
Visibility at creation (SES-DEF-003/004). Defaults to private; promote to workspace via PATCH after creation.
Responses
Section titled “ Responses ”Successful Response
Session response for list and detail views.
object
Small denormalized view of the session creator for list/detail render.
Included alongside user_id so UI can show an email chip without a
follow-up request. Pulled from the eager-loaded SessionORM.user.
Labels attached to this session as {key: [value, ...]}.
object
Session origin (SES-ORG-001). user for interactive sessions, eval for evaluation-worker sessions, worker for capability-worker sessions.
Aggregated token usage for a session.
All fields are derived at read time from per-message usage columns on
session_messages. Pre-migration sessions (no usage data) report
zeros; new sessions with no inference yet report zeros and
last_generation_input_tokens=None.
object
Non-compacted message count — the subset the transcript paginates. current means the current era (consistent with the other current_* usage fields), NOT a pagination page; it diverges from total_message_count once the session has been compacted.
Lifetime message count — every message, compacted included.
Example
{ "frozen_by": "evaluation", "origin": "user", "visibility": "private"}Invalid request
Canonical API error envelope returned by the API.
object
HTTP status code
Human-readable error message
object
Where the validation error occurred
Human-readable validation message
Machine-readable validation error type
Stable machine-readable error type
Example
{ "code": 401, "detail": "Authentication failed", "type": "authentication_error"}Authentication failed
Canonical API error envelope returned by the API.
object
HTTP status code
Human-readable error message
object
Where the validation error occurred
Human-readable validation message
Machine-readable validation error type
Stable machine-readable error type
Example
{ "code": 401, "detail": "Authentication failed", "type": "authentication_error"}Access forbidden
Canonical API error envelope returned by the API.
object
HTTP status code
Human-readable error message
object
Where the validation error occurred
Human-readable validation message
Machine-readable validation error type
Stable machine-readable error type
Example
{ "code": 401, "detail": "Authentication failed", "type": "authentication_error"}Not found
Canonical API error envelope returned by the API.
object
HTTP status code
Human-readable error message
object
Where the validation error occurred
Human-readable validation message
Machine-readable validation error type
Stable machine-readable error type
Example
{ "code": 401, "detail": "Authentication failed", "type": "authentication_error"}Already exists
Canonical API error envelope returned by the API.
object
HTTP status code
Human-readable error message
object
Where the validation error occurred
Human-readable validation message
Machine-readable validation error type
Stable machine-readable error type
Example
{ "code": 401, "detail": "Authentication failed", "type": "authentication_error"}Validation error
Canonical API error envelope returned by the API.
object
HTTP status code
Human-readable error message
object
Where the validation error occurred
Human-readable validation message
Machine-readable validation error type
Stable machine-readable error type
Example
{ "code": 401, "detail": "Authentication failed", "type": "authentication_error"}Upgrade required
Canonical API error envelope returned by the API.
object
HTTP status code
Human-readable error message
object
Where the validation error occurred
Human-readable validation message
Machine-readable validation error type
Stable machine-readable error type
Example
{ "code": 401, "detail": "Authentication failed", "type": "authentication_error"}Rate limited
Canonical API error envelope returned by the API.
object
HTTP status code
Human-readable error message
object
Where the validation error occurred
Human-readable validation message
Machine-readable validation error type
Stable machine-readable error type
Example
{ "code": 401, "detail": "Authentication failed", "type": "authentication_error"}Internal server error
Canonical API error envelope returned by the API.
object
HTTP status code
Human-readable error message
object
Where the validation error occurred
Human-readable validation message
Machine-readable validation error type
Stable machine-readable error type
Example
{ "code": 401, "detail": "Authentication failed", "type": "authentication_error"}Bad gateway
Canonical API error envelope returned by the API.
object
HTTP status code
Human-readable error message
object
Where the validation error occurred
Human-readable validation message
Machine-readable validation error type
Stable machine-readable error type
Example
{ "code": 401, "detail": "Authentication failed", "type": "authentication_error"}Gateway timeout
Canonical API error envelope returned by the API.
object
HTTP status code
Human-readable error message
object
Where the validation error occurred
Human-readable validation message
Machine-readable validation error type
Stable machine-readable error type
Example
{ "code": 401, "detail": "Authentication failed", "type": "authentication_error"}