Messages

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 /{org}/{agent}/v1/sessions/{session_id}/messages

Request

text

string

required

The message to send.

agent

string

Route this turn to a named sub-agent. Defaults to the session’s current sub-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

Status	When
`200`	Success (unary or stream start).
`401`	Missing/invalid credential.
`402`	Budget exhausted - returned before the turn runs.
`403`	A metadata end-user id that conflicts with the verified token (`identity_mismatch`).
`404`	Session not found, another org’s, or the agent has no active release.
`409`	Agent route: a release exists but is not materialized.
`422`	BYOK key rejected (unary). In streaming, this is an `error` event.

Want to drive an agent with an existing OpenAI or Anthropic client instead of this native shape? Use a consumer adapter

same turn, re-framed into those wire formats.

Overview

Sessions

Consumer adapters

Request

Unary response (`stream: false`)

Streaming response (`stream: true`)

Status codes

​Request

​Unary response (stream: false)

​Streaming response (stream: true)

​Status codes

Request

Unary response (`stream: false`)

Streaming response (`stream: true`)

Status codes