API Reference Overview

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.

Authentication

All requests must include your API key in the Authorization header:

Authorization: Bearer theo_sk_...

See 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
Key orchestration	`GET/PUT /keys/{id}/models`, `/model-plan`, `/orchestrator-graph`, `/skills`, `/guardrails`, `/routing-preference`	Per-key model allowlist, model plan, executable graph, skills, guardrail + routing bindings
Custom Providers	`GET/POST /custom-providers`, `DELETE /custom-providers/{id}`	Bring-your-own OpenAI-compatible model endpoints
Health	`GET /health`	System status (public, no auth)

Response Format

All responses follow a consistent JSON structure:

{
  "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:

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:

{
  "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
422	Unprocessable — the request was rejected by a policy on the key
429	Rate limited — check `Retry-After` header
500	Internal server error
503	Service unavailable — check `Retry-After` header

Some errors carry a semantic code that reflects the key’s orchestration (both the native and OpenAI-compatible endpoints apply it):

Status	Code	Meaning
400	`context_length_exceeded`	Request is larger than any model on the key can hold
403	`model_not_allowed`	The resolved model is outside the key’s model allowlist
422	`guardrail_violation`	A Gateway Guardrails policy on the key denied the request
422	`orchestrator_no_path`	The key’s orchestrator graph couldn’t resolve a path

Overview

Completions

Media Generation

Audio

Skills API

E.V.I. Canvas

Workflows

Hooks

Settings

Embed Widgets

Guardrails

Routing Studio

Theo Browser

Benchmarks

Webhooks

Billing

Resources

Base URL

Authentication

OpenAPI Spec

Endpoints at a Glance

Response Format

Idempotency Keys

Errors

​Base URL

​Authentication

​OpenAPI Spec

​Endpoints at a Glance

​Response Format

​Idempotency Keys

​Errors

Base URL

Authentication

OpenAPI Spec

Endpoints at a Glance

Response Format

Idempotency Keys

Errors