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.

POST /v1/projects/{project_ref}/responses Speaks the OpenAI Responses API shape. Auth: a session token or a kt_live_… key.

​
Request

​
input
string | array
required
The user input — a string, or an array of input items.
​
stream
boolean
default:"false"
true → SSE; false → a single response object.
​
previous_response_id
string
Continue from a prior response — the Responses-style way to keep context across turns. Maps to the underlying Karta session.
​
store
boolean
Whether to pin/persist the session.
​
model
string
Optional model override.

​
Unary response

curl https://api.karta.sh/v1/projects/my-app/responses \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"input": "What roasts do you have?"}'

{
  "id": "resp_4b2c…",
  "type": "response",
  "status": "completed",
  "output": { "type": "text", "text": "We've got Sunrise, Midnight, and Decaf Dusk. ☕" },
  "usage": { "input_tokens": 42, "output_tokens": 28, "total_tokens": 70 },
  "previous_response_id": null
}
Pass the returned id as previous_response_id on the next call to continue the conversation.

​
Streaming

curl -N https://api.karta.sh/v1/projects/my-app/responses \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"input": "What roasts do you have?", "stream": true}'

event: response.created
data: { "id": "resp_4b2c…", "status": "in_progress" }

event: response.output_text.delta
data: { "delta": "We've got " }

event: response.output_text.delta
data: { "delta": "Sunrise, Midnight, …" }

event: response.completed
data: { "id": "resp_4b2c…", "status": "completed", "usage": { … } }
A failure mid-stream arrives as response.failed.

​
Status codes

200 (unary or stream), 401, 402 (budget), 403 (token wrong project), 404, 409 (no active release), 422 (BYOK rejected). See Errors.