API reference

Karta exposes a uniform HTTP API. Every agent speaks the same session protocol - create a session, send a message, stream the response - so one client can talk to any agent. If you are not sure which surface to use, choose by client:

Client you are building	Use	Why
Hosted customer chat	Chat widget	Prebuilt UI; no backend required for anonymous visitors.
Your own backend and UI	Sessions + Messages	Direct control over session creation, metadata, streaming, and approvals.
Existing OpenAI client	OpenAI adapters	Keep the SDK shape your app already uses.
Managed-agent event log client	Managed Agents adapter	Post user events and stream an event-sourced agent log.
Multi-participant routing	Gateway	Deliver events across human and AI participants.

For browser credentials and auth boundaries, read Authentication and Session tokens before shipping.

Base URL

https://api.karta.sh

The agent route family (and the consumer adapters) is served on the consumer host, https://agent.karta.sh. Locally, karta dev hosts the same surface and prints its local URL.

What’s here

Sessions

Create, fetch, and resume sessions.

Messages

Send and stream turns, unary or SSE.

Inputs

Resolve approval prompts mid-turn.

Gateway

Submit and deliver events across participants.

Consumer adapters

Talk to an agent with OpenAI- or Anthropic-shaped client code.

Authentication

API keys, session tokens, and how each is scoped.

Conventions

Versioned paths. Public endpoints live under /v1.
Streaming everywhere. Message endpoints take "stream": true and respond with Server-Sent Events; false (the default) returns an accumulated JSON response.
JSON in, JSON (or SSE) out. Send Content-Type: application/json.
Org-scoped by default. A key for one org cannot touch another org’s sessions - cross-org access is default-deny and returns 404.

Two route families

Family	Path shape	Auth	Use
Flat	`/v1/sessions/...` on `api.karta.sh`	`kt_live_...` API key	Server-side integrations holding an org key.
Agent	`/{org}/{agent}/v1/...` on `agent.karta.sh`	API key, or a session token on the consumer adapters	A backend, frontend, or widget driving a specific deployed agent.

Within the agent family, a browser-minted session token is accepted on the consumer adapters - the Managed Agents API and the OpenAI-compatible routes. The native /{org}/{agent}/v1/sessions routes require an API key, like the flat family.

Reserved browser action routes

The /v1/account/proposals family is reserved for Karta-hosted account-action agents:

GET /v1/account/proposals
POST /v1/account/proposals
POST /v1/account/proposals/{proposal_id}/approve
POST /v1/account/proposals/{proposal_id}/cancel

Customer integrations should not build custom clients against those routes. For agent tool approvals, use Inputs or a Managed Agents user.tool_confirmation event. For sensitive account actions in your product, use your own authenticated handoff and step-up flow.

Machine-readable spec

An OpenAPI document is published at /openapi.json (public; excludes internal endpoints). Point your codegen or API explorer at it.

​Base URL

​What’s here