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.

Send a message to a session and get the agent’s turn back. Set stream to choose the response shape. POST /v1/sessions/{session_id}/messages · POST /v1/projects/{project_ref}/sessions/{session_id}/messages

​
Request

​
text
string
required
The message to send.
​
agent
string
Route this turn to a named agent. Defaults to the session’s current agent.
​
participant_name
string
The sending participant; messages are attributed to it.
​
participant_type
string
human or ai.
​
thinking
boolean
default:"false"
Surface extended-thinking / reasoning events.
​
stream
boolean
default:"false"
true → Server-Sent Events. false → a single accumulated JSON response.

​
Unary response (stream: false)

curl https://api.karta.sh/v1/sessions/$SID/messages \
  -H "Authorization: Bearer $KARTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "What roasts do you have?"}'

{
  "text": "We've got Sunrise, Midnight, and Decaf Dusk. ☕",
  "session_id": "sess_9f3a…",
  "agent": "default",
  "messages": [
    { "id": "msg_1", "role": "user",      "text": "What roasts do you have?", "parts": [/* … */] },
    { "id": "msg_2", "role": "assistant", "text": "We've got Sunrise, …",      "parts": [/* … */] }
  ],
  "usage": { "input_tokens": 42, "output_tokens": 28, "total_tokens": 70 }
}

​
Streaming response (stream: true)

curl -N https://api.karta.sh/v1/sessions/$SID/messages \
  -H "Authorization: Bearer $KARTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "What roasts do you have?", "stream": true}'

event: text
data: {"type":"text","session_id":"sess_9f3a…","data":{"part":{"type":"text","text":"We've got "}}}

event: text
data: {"type":"text","session_id":"sess_9f3a…","data":{"part":{"type":"text","text":"Sunrise, Midnight, …"}}}

event: done
data: {"type":"done","data":{"usage":{"input_tokens":42,"output_tokens":28,"total_tokens":70}}}
The stream is the typed event model: text, tool_use, reasoning, step_start, step_finish, input_required, error, done. A turn may pause with input_required to request approval — resolve it via Inputs.

​
Status codes

StatusWhen
200Success (unary or stream start).
401Missing/invalid credential.
402Budget exhausted — returned before the turn runs.
403Session token scoped to another project (project route).
404Session not found or another org’s.
409Project route: no active/materialized release.
422BYOK key rejected (unary). In streaming, this is an error event.
Want to drive a project with an existing OpenAI or Anthropic client instead of this native shape? Use a consumer adapter — same turn, re-framed into those wire formats.