Skip to Content
Baseera Docs

Sessions

Start a session and read it back to resume a conversation.

A session is one conversation for one user of one tenant. It records the agent, the agent's config version, and the user id, tenant id and locale from the token.

A session needs no model or provider key. An agent without one can start sessions, run immersive checks and drafts, and record a finish. Only turns need a model.

Start a session

POST /v0/sessions

Browser request with a publishable key, an allowed origin and a user token. See Authentication.

Prop

Type

The body must be a JSON object of at most 2 KB.

curl -X POST "$BASEERA_URL/v0/sessions" \
  -H "Origin: https://app.example.com" \
  -H "x-baseera-key: $BASEERA_PUBLISHABLE_KEY" \
  -H "x-baseera-user-token: $USER_TOKEN" \
  -H "content-type: application/json" \
  -d '{ "locale": "ar" }'

Response, 201 Created:

{
  "sessionId": "ses_01JC9X4M2K8Q",
  "agent": { "name": "Billing assistant", "modes": ["chat", "immersive"] },
  "createdAt": "2026-11-08T20:30:00.000Z"
}

Session ids are ses_ plus 32 hex characters (128 random bits). The locale is the request's, then the token's.

Errors: invalid_key, origin_not_allowed, invalid_user_token, user_token_expired, invalid_request (body is not a JSON object, or is over 2 KB).

Read a session

GET /v0/sessions/{sessionId}

Returns the messages so far, so a page reload can pick up where the user left off.

curl "$BASEERA_URL/v0/sessions/ses_01JC9X4M2K8Q" \
  -H "Origin: https://app.example.com" \
  -H "x-baseera-key: $BASEERA_PUBLISHABLE_KEY" \
  -H "x-baseera-user-token: $USER_TOKEN"

200 OK:

{
  "sessionId": "ses_01JC9X4M2K8Q",
  "agent": { "name": "Billing assistant", "modes": ["chat", "immersive"] },
  "messages": [
    { "id": "msg_u1", "role": "user", "text": "Mark invoice 1042 as paid", "createdAt": "2026-11-08T20:30:05.000Z" },
    {
      "id": "msg_a1",
      "role": "assistant",
      "text": "I'll mark invoice 1042 as paid.",
      "toolCalls": [
        { "callId": "call_1", "name": "invoices.markPaid", "kind": "write", "input": { "invoiceId": "inv_1042" }, "status": "pending" }
      ],
      "sources": [],
      "createdAt": "2026-11-08T20:30:06.000Z"
    }
  ],
  "pendingTurn": { "turnId": "trn_7", "callIds": ["call_1"], "expiresAt": "2026-11-08T20:35:06.000Z" }
}

pendingTurn is set when the last turn is waiting for tool results. See Tools and approvals.

If a turn was waiting for tool results and the wait has expired, the runtime closes it as tool_timeout before answering. Its pending calls come back with status timed_out and pendingTurn is null.

Stored tool data

When the agent's "Don't store tool data" setting is on, tool data is removed once a turn ends. For calls of finished turns, output is omitted and input is null. Names, kinds and status are always kept. A turn that is still waiting for results keeps its data until it ends. Sources on assistant messages are always kept, because they are what the user saw.

Errors

session_not_found (404) when the session does not exist, belongs to a different user or tenant, or belongs to a different agent than the publishable key's. All three look the same on purpose.

Manage sessions

There is no endpoint to list, rename or delete sessions in the runtime API. Members of your organization browse sessions in the console. The runtime runs one turn per session at a time.

Next steps

On this page