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}/chat/completions Speaks the OpenAI Chat Completions shape — the widely-supported messages-array format. Auth: a session token or a kt_live_… key.

​
Request

​
messages
array
required
The conversation so far, as { "role": "...", "content": "..." } items.
​
model
string
Optional model override.
​
stream
boolean
default:"false"
true → SSE chunks; false → a single completion object.

​
Unary response

curl https://api.karta.sh/v1/projects/my-app/chat/completions \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"messages": [{"role": "user", "content": "What roasts do you have?"}]}'

{
  "id": "chatcmpl_8a1d…",
  "object": "text_completion",
  "created": 1717250400,
  "model": "default",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "We've got Sunrise, Midnight, and Decaf Dusk. ☕" },
      "finish_reason": "stop"
    }
  ],
  "usage": { "input_tokens": 42, "output_tokens": 28, "total_tokens": 70 }
}

​
Streaming

curl -N https://api.karta.sh/v1/projects/my-app/chat/completions \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"What roasts do you have?"}],"stream":true}'

event: chunk
data: { "choices": [ { "delta": { "content": "We've got " } } ] }

event: chunk
data: { "choices": [ { "delta": { "content": "Sunrise, Midnight, …" } } ] }

event: [DONE]
data: [DONE]

​
Using the OpenAI SDK

Point an OpenAI client’s base URL at your project and pass the session token as the API key: 
from openai import OpenAI

client = OpenAI(
    base_url="https://api.karta.sh/v1/projects/my-app",
    api_key=session_token,
)
resp = client.chat.completions.create(
    model="default",
    messages=[{"role": "user", "content": "What roasts do you have?"}],
)
print(resp.choices[0].message.content)

​
Status codes

200 (unary or stream), 401, 402 (budget), 403, 404, 409, 422. See Errors.