Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.karta.sh/llms.txt

Use this file to discover all available pages before exploring further.

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"}}'
POST /v1/sessions · POST /v1/projects/{project_ref}/sessions
​
metadata
object
Arbitrary key/values to tag the session with — route and look it up by these later. Up to 50 keys.
​
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 201

{
  "id": "sess_9f3a…",
  "metadata": { "customer_id": "abc123" },
  "current_agent": "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 project route additionally returns a project block with ref, project_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 /v1/projects/{project_ref}/sessions/{session_id} Returns the session object above. 404 if it doesn’t exist or belongs to another org; 403 on the project route if a session token is scoped to a different project.

​
Resume

Resumption is just create-with-session_id, or fetch-then-send. Conversation history lives in the harness, so a resumed session continues exactly where it left off — Karta keeps no second copy. See Sessions & participants.

​
Project pinning

When a session is created on a project route, it’s pinned to that project’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.