> ## Documentation Index > Fetch the complete documentation index at: https://docs.hitheo.ai/llms.txt > Use this file to discover all available pages before exploring further. # API Reference Overview > REST API for AI orchestration — completions, images, video, code, research, documents, skills, and more. The Theo API is a RESTful JSON API served at `https://www.hitheo.ai/api/v1/`. All endpoints require authentication via Bearer token except `/health`. ## Base URL ``` https://www.hitheo.ai/api/v1/ ``` Always call the `www` host directly. The apex `hitheo.ai` 307-redirects to `www.hitheo.ai`, and most HTTP clients strip the `Authorization` header on 3xx responses — the redirected request arrives unauthenticated and the server returns `401`. The SDK defaults to `https://www.hitheo.ai` as of `@hitheo/sdk@0.2.0`. If you hit an unexpected 401, see [401 Troubleshooting](/troubleshooting/401-errors). ## Authentication All requests must include your API key in the `Authorization` header: ``` Authorization: Bearer theo_sk_... ``` See [Authentication](/api-reference/authentication) for details. ## OpenAPI Spec The full OpenAPI 3.1 specification is available at: ``` https://www.hitheo.ai/api/v1/openapi.json ``` You can import this into Postman, Insomnia, or any OpenAPI-compatible tool. ## Endpoints at a Glance | Category | Endpoints | Description | | -------------------- | ---------------------------------------------------------------- | --------------------------------------------------------- | | **Completions** | `POST /completions` | Core AI completions with the orchestration pipeline | | **Chat Completions** | `POST /chat/completions` | Drop-in chat-completions wire format for existing tooling | | **Images** | `POST /images` | Image generation (Theo Create) | | **Video** | `POST /video` | Video generation (async) | | **Code** | `POST /code` | Code generation (Theo Code) | | **Research** | `POST /research` | Deep web research (async) | | **Documents** | `POST /documents` | PDF, DOCX, PPTX, XLSX, CSV generation | | **Audio** | `POST /audio/tts`, `POST /audio/stt` | Text-to-speech and speech-to-text | | **Skills** | `GET/POST /skills`, `POST /skills/create`, `POST /skills/submit` | Marketplace and skill management | | **E.V.I. Canvas** | `GET/POST /evi/canvases` | Build, compile, and publish E.V.I. personas | | **Workflows** | `GET/POST /workflows`, `POST /workflows/{id}/run` | Automation workflows | | **Hooks** | `GET/POST /hooks` | Autonomous event-triggered skill execution | | **Events** | `POST /events` | Publish domain events | | **Guardrails** | `GET/POST /guardrail-policies` | Input/output policy enforcement | | **Routing Studio** | `GET/POST /routing-preferences` | Per-customer routing preferences | | **Embed Widgets** | `GET/POST /iframes` | White-label chat widgets, analytics, and leads | | **Theo Browser** | `POST /browser/sessions` | Managed headless browser sessions | | **Webhooks** | `GET/POST /webhooks` | Outbound event delivery | | **Conversations** | `GET /conversations` | Conversation history | | **Models** | `GET /models` | Available engine registry | | **Tools** | `GET /tools` | Available tool definitions | | **Jobs** | `GET /jobs/{id}` | Async job status polling | | **Usage** | `GET /usage`, `GET /usage/export` | Usage analytics and CSV export | | **Billing** | `POST /billing/checkout`, `POST /billing/portal` | Credit top-ups and billing portal | | **Settings** | `GET/PATCH /settings` | Account preferences | | **Benchmarks** | `GET /benchmarks` | Aggregated latency and routing telemetry | | **Organizations** | `GET/POST /orgs` | Team and membership management | | **Audit** | `GET /audit`, `GET /audit/export` | Audit log listing and CSV export | | **Keys** | `POST /keys` | API key management | | **Health** | `GET /health` | System status (public, no auth) | ## Response Format All responses follow a consistent JSON structure: ```json theme={null} { "id": "resource_id", "object": "resource_type", "created": "2026-04-10T12:00:00Z", "request_id": "req_9f2e1a", ...resource-specific fields } ``` Every response also carries an `X-Request-Id` header; successful JSON responses surface the same value as a top-level `request_id` field. Include it in support tickets so the request can be looked up in logs. ## Idempotency Keys POST requests to state-changing endpoints (create canvas, create workflow, run workflow, submit skill, create webhook, install hook, publish event, create iframe, duplicate iframe, start browser session, install skill) accept an `Idempotency-Key` header: ```bash theme={null} curl -X POST https://www.hitheo.ai/api/v1/workflows \ -H "Authorization: Bearer $THEO_API_KEY" \ -H "Idempotency-Key: c0ff33-2026-04-21-deploy-123" \ -H "Content-Type: application/json" \ -d '{...}' ``` * Responses are cached for 24 hours per (user, key). Retried requests with the same key return the original response body with `X-Idempotent-Replay: true`. * The key is at most 256 characters and must match `[A-Za-z0-9\-_.:]+`. Use a UUID, ULID, or your own deterministic request id. * Two concurrent requests with the same key resolve to `409 idempotency_conflict` on the second caller — retry shortly. * Idempotency is scoped per user, so keys can't collide across tenants. ## Errors Errors return a structured JSON body: ```json theme={null} { "error": { "message": "Invalid API key", "type": "authentication_error", "code": "invalid_api_key", "request_id": "req_abc123" } } ``` | Status | Meaning | | ------ | ------------------------------------------------ | | 400 | Bad request — invalid parameters | | 401 | Unauthorized — missing or invalid API key | | 403 | Forbidden — insufficient permissions | | 404 | Not found | | 429 | Rate limited — check `Retry-After` header | | 500 | Internal server error | | 503 | Service unavailable — check `Retry-After` header |