# Theo · REST API

> The Theo REST API powers every Theo Worker, channel adapter, and SDK. Auth via API keys, streaming SSE responses, an idempotency contract, a versioned envelope, and a drop-in compatibility format for clients that expect the standard chat-completion shape.

Source of truth: https://hitheo.ai/for-developers and https://docs.hitheo.ai. Last updated: 2026-05-24.

## Auth
- API keys with the prefix `theo_sk_*`. Pass via `Authorization: Bearer theo_sk_...` header.
- Keys have scopes (completions, connectors, browser, memory, …). Tokens are validated by the middleware and rate-limited per token.

## Primary endpoints
- POST /api/v1/completions — main entry point. Accepts a prompt, mode, optional streaming flag, optional skills, optional tools, optional metadata. Returns either streaming SSE or a final JSON envelope.
- POST /api/v1/images — synchronous image-generation endpoint. Returns an artifacts[] array.
- GET /api/v1/models — list available branded engines (theo-1-auto, theo-1-flash, theo-1-reason, theo-1-code, theo-1-create, theo-1-motion, theo-1-research, theo-1-edge, theo-1-genui, theo-1-analyze, theo-1-extract, theo-1-stealth, theo-1-stealth-create, theo-1-stealth-motion).
- GET /api/v1/health — public health + provider status.
- GET /api/v1/audit — paginated audit log for the calling key or organization.
- GET / POST / DELETE /api/v1/keys — manage API keys.
- GET / POST / PATCH / DELETE /api/v1/webhooks — manage webhook endpoints.
- GET / POST / DELETE /api/v1/hooks — manage autonomous triggers.
- GET / POST / DELETE /api/v1/skills — install and author skills.
- GET / POST / DELETE /api/v1/orgs — manage organizations.
- GET /api/v1/openapi.json — machine-readable OpenAPI 3.1 spec.
- POST /api/v1/voice/token — mint a voice session token. See https://hitheo.ai/llms/voice.txt.
- POST / DELETE /api/v1/browser/sessions — manage Theo Browser sessions. See https://hitheo.ai/llms/browser.txt.

## Streaming protocol (Server-Sent Events)
`text/event-stream` over HTTP. Events:
1. `thinking` — immediate heartbeat before orchestration runs.
2. `meta` — completion id, resolved mode, branded model info, tools, artifacts.
3. `tool` — one per tool used (classifier, memory, research, code, document, browser).
4. `artifact` — one per artifact produced (image, video, document, code).
5. `token` — streamed text tokens.
6. `done` — final payload with full content, follow-ups, usage, billing.

Also supports a drop-in industry-standard `chat.completion` compatibility envelope. Activated by passing a `format` field on the request body; see https://docs.hitheo.ai or the OpenAPI spec for the accepted values.

## Idempotency
POST endpoints accept an `Idempotency-Key` header. Per-user namespace. 30-second execution lock prevents duplicate execution. 24-hour replay window. Cached responses replay with `X-Idempotent-Replay: true` header. Keys are bounded to 256 characters, alphanumeric + `-_.:`.

## Versioning
- Client sends `Theo-Api-Version: 2026-03-28` (date-based version header).
- Response includes `Theo-Version: 2026-03-28`.
- `Theo-Deprecation` header is set when the client version is older than current. Date-based versioning means we can ship non-breaking improvements without coordinating SDK bumps.

## Billing
- Per-token pricing with a transparent passthrough margin. See https://hitheo.ai/llms/pricing.txt.
- `credits.low` webhook fires when balance drops below the configured threshold (default $5.00).

## CORS
- Default allowed origins: hitheo.ai, api.hitheo.ai, docs.hitheo.ai.
- Per-key `allowedOrigins` takes priority over defaults.
- Server-to-server requests (no Origin header) get a wildcard ACAO.

## Audit
Every completion lands in the audit ledger as a SHA-256 hashed entry with action, model, cost, and provenance. See https://hitheo.ai/llms/privacy.txt.

## Related machine-readable files
- https://hitheo.ai/llms.txt — full index of every Theo machine-readable file.
- https://hitheo.ai/llms-full.txt — long-form knowledge bundle (single fetch).
- https://hitheo.ai/humans.txt — team and open-source credits.
- https://hitheo.ai/lawyers.txt — trademark notice and legal contact.
- https://hitheo.ai/.well-known/security.txt — security disclosure contact.