> ## 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.

# API reference

> The Karta HTTP API - sessions, streaming, gateway, and OpenAI- and Anthropic-shaped consumer adapters.

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](/sdks/widget/quickstart)                                    | Prebuilt UI; no backend required for anonymous visitors.                  |
| Your own backend and UI        | [Sessions](/api-reference/sessions) + [Messages](/api-reference/messages) | Direct control over session creation, metadata, streaming, and approvals. |
| Existing OpenAI client         | [OpenAI adapters](/api-reference/adapters/overview)                       | Keep the SDK shape your app already uses.                                 |
| Managed-agent event log client | [Managed Agents adapter](/api-reference/adapters/managed-agents)          | Post user events and stream an event-sourced agent log.                   |
| Multi-participant routing      | [Gateway](/api-reference/gateway)                                         | Deliver events across human and AI participants.                          |

For browser credentials and auth boundaries, read
[Authentication](/api-reference/authentication) and
[Session tokens](/security/session-tokens) before shipping.

## Base URL

```text theme={null}
https://api.karta.sh
```

The **agent** route family (and the [consumer
adapters](/api-reference/adapters/overview)) is served on the consumer host,
`https://agent.karta.sh`. Locally, [`karta dev`](/cli/overview) hosts the
same surface and prints its local URL.

## What's here

<CardGroup cols={2}>
  <Card title="Sessions" icon="comments" href="/api-reference/sessions">
    Create, fetch, and resume sessions.
  </Card>

  <Card title="Messages" icon="paper-plane" href="/api-reference/messages">
    Send and stream turns, unary or SSE.
  </Card>

  <Card title="Inputs" icon="circle-check" href="/api-reference/inputs">
    Resolve approval prompts mid-turn.
  </Card>

  <Card title="Gateway" icon="diagram-project" href="/api-reference/gateway">
    Submit and deliver events across participants.
  </Card>

  <Card title="Consumer adapters" icon="plug" href="/api-reference/adapters/overview">
    Talk to an agent with OpenAI- or Anthropic-shaped client code.
  </Card>

  <Card title="Authentication" icon="key" href="/api-reference/authentication">
    API keys, session tokens, and how each is scoped.
  </Card>
</CardGroup>

## Conventions

* **Versioned paths.** Public endpoints live under `/v1`.
* **Streaming everywhere.** Message endpoints take `"stream": true` and respond
  with [Server-Sent Events](/concepts/streaming-events#on-the-wire-sse);
  `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](/security/session-tokens) is accepted on the [consumer
adapters](/api-reference/adapters/overview) - 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](/api-reference/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`](https://karta.sh/openapi.json) (public; excludes internal
endpoints). Point your codegen or API explorer at it.