Sessions

A session is the handle a conversation runs on. Create one (or resume an existing one), then send messages to it.

Create a session

curl -X POST https://api.karta.sh/v1/sessions \
  -H "Authorization: Bearer $KARTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"metadata": {"customer_id": "abc123"}}'

curl -X POST https://agent.karta.sh/my-org/my-app/v1/sessions \
  -H "Authorization: Bearer $KARTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

POST /v1/sessions, POST /{org}/{agent}/v1/sessions

metadata

object

Arbitrary key/values to tag the session with - route and look it up by these later. Up to 50 keys.

metadata.end_user_id

string

The verified acting-user key. For per-user kartas, this also becomes the durable karta boundary (user_id is accepted as a legacy alias). On the consumer surface a verified session token’s subject is authoritative.

metadata.agent_instance_id

string

Optional technical field for naming the durable karta explicitly - for example a virtual employee that works with a team, one of several virtual employees, or a backend-job karta. Each acting user is still attributed per turn. Trusted only from your backend (an API key or a backend-minted token), never from public browser metadata.

session_id

string

If supplied and it exists, the session is resumed rather than created. A session_id belonging to another org returns 404.

Response `200`

{
  "id": "sess_9f3a...",
  "metadata": { "customer_id": "abc123" },
  "current_agent": "karta-default",
  "status": "active",
  "created_at": "2026-06-01T12:00:00+00:00",
  "updated_at": "2026-06-01T12:00:00+00:00",
  "parent_id": null,
  "pending_input": null,
  "permission_mode": null,
  "participants": []
}

The agent route additionally returns an agent block with ref, agent_id, and version (the release the session is pinned to).

Fetch a session

curl https://api.karta.sh/v1/sessions/sess_9f3a... \
  -H "Authorization: Bearer $KARTA_API_KEY"

GET /v1/sessions/{session_id}, GET /{org}/{agent}/v1/sessions/{session_id} Returns the session object above. 404 if it does not exist, belongs to another org, or (on the agent route) the session token is scoped to a different agent - all shaped identically, so the route is never a tenant oracle.

List agent sessions

GET /{org}/{agent}/v1/sessions Lists resident sessions for one deployed agent. This is an API-key route for server-side observability and CLI tooling; session tokens cannot enumerate sessions.

Query	Default	Meaning
`active`	`false`	When `true`, return only sessions active in the recent activity window.
`page`	`1`	1-based page number.
`per_page`	`50`	Page size, clamped to `1..200`.

{
  "agent": { "ref": "my-app", "agent_id": 123 },
  "page": 1,
  "per_page": 50,
  "total": 1,
  "sessions": [
    {
      "id": "sess_9f3a...",
      "status": "active",
      "message_count": 3,
      "last_message_at": "2026-06-01T12:05:00+00:00",
      "end_user_id": "u_42"
    }
  ]
}

Fetch a transcript

GET /{org}/{agent}/v1/sessions/{session_id}/messages Returns the captured transcript for an agent-route session:

{
  "session": { "id": "sess_9f3a...", "status": "active" },
  "messages": [
    { "role": "user", "text": "What roasts do you have?" },
    { "role": "assistant", "text": "We've got Sunrise, Midnight, and Decaf Dusk." }
  ]
}

This route requires an API key with sessions:read scope. Transcript content is also controlled by the organization’s support-access setting; if transcript access is disabled, the route returns 403.

Stop a session

DELETE /{org}/{agent}/v1/sessions/{session_id} Ends an agent-route session and returns 204. Use it when your backend knows a conversation is done and wants Karta to release the active runtime for that session. A later session using the same durable karta boundary can still resume the persisted workspace state.

Resume

Resume by creating with session_id, or by fetching the session and sending the next turn. Conversation history lives in the harness, so a resumed session continues where it left off. See Sessions & participants.

Agent pinning

When a session is created on an agent route, it is pinned to that agent’s active release version at creation time. Subsequent turns run against that pinned version even if a new release is activated mid-conversation - the zero-interruption cutover guarantee.

Send a message

Send and stream turns into a session.

Authentication

Which credential works on which route family.

Overview

Consumer adapters

Sessions

Create a session

Response `200`

Fetch a session

List agent sessions

Fetch a transcript

Stop a session

Resume

Agent pinning

Send a message

Authentication

​Create a session

​Response 200

​Fetch a session

​List agent sessions

​Fetch a transcript

​Stop a session

​Resume

​Agent pinning

Send a message

Authentication

Create a session

Response `200`

Fetch a session

List agent sessions

Fetch a transcript

Stop a session

Resume

Agent pinning