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.

The Managed Agents adapter models a conversation as an event-sourced session: you create a session, post user events into it, and stream back an ordered agent.* event log. It maps Karta’s typed events onto the Anthropic managed-agent shape. Auth: a session token or a kt_live_… key.

​
Create a session

POST /v1/projects/{project_ref}/managed-agents/sessions 
curl -X POST https://api.karta.sh/v1/projects/my-app/managed-agents/sessions \
  -H "Authorization: Bearer $SESSION_TOKEN"
# → 201 { "id": "sess_9f3a…", "status": "idle" }

​
Post an event

POST /v1/projects/{project_ref}/managed-agents/sessions/{session_id}/events Posting a user event spawns the turn in the background and returns immediately; you observe the result on the event stream.
​
type
string
required
user.message, user.tool_confirmation, or user.interrupt.
​
text
string
The message text — required for user.message.
​
tool_use_id
string
Optional tool reference.
​
request_id
string
Required for user.tool_confirmation — the approval being answered.
​
result
string
allow or deny — required for user.tool_confirmation.
curl -X POST https://api.karta.sh/v1/projects/my-app/managed-agents/sessions/$SID/events \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type": "user.message", "text": "What roasts do you have?"}'
# → 202 { "accepted": true }
Approve a pending tool use: 
curl -X POST .../sessions/$SID/events \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type": "user.tool_confirmation", "request_id": "req_7c1…", "result": "allow"}'

​
Stream events

GET /v1/projects/{project_ref}/managed-agents/sessions/{session_id}/events/stream Streams agent.* events as the turn runs. Pass ?after=<seq> to resume from a known sequence number — the log is ordered and replayable. 
curl -N "https://api.karta.sh/v1/projects/my-app/managed-agents/sessions/$SID/events/stream?after=0" \
  -H "Authorization: Bearer $SESSION_TOKEN"

​
Fetch session state

GET /v1/projects/{project_ref}/managed-agents/sessions/{session_id} 
{
  "id": "sess_9f3a…",
  "status": "idle",
  "events": [
    { "seq": 1, "type": "agent.text", "data": { "text": "We've got Sunrise, …" } },
    { "seq": 2, "type": "agent.done", "data": { "usage": { … } } }
  ]
}
status is idle or running; events is the ordered log so far.

​
Why event-sourced

This shape suits clients that prefer post-and-observe over request/response: a UI posts a user message, then renders the agent’s agent.* events as they arrive — including tool-confirmation prompts it answers with a follow-up event. The ordered, replayable log makes reconnection and catch-up straightforward (after=<seq>).

​
Status codes

201 (create), 202 (event accepted), 400 (bad body), 401, 402, 403, 404, 409. See Errors.