Skip to main content
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

CategoryEndpointsDescription
CompletionsPOST /completionsCore AI completions with the orchestration pipeline
Chat CompletionsPOST /chat/completionsDrop-in chat-completions wire format for existing tooling
ImagesPOST /imagesImage generation (Theo Create)
VideoPOST /videoVideo generation (async)
CodePOST /codeCode generation (Theo Code)
ResearchPOST /researchDeep web research (async)
DocumentsPOST /documentsPDF, DOCX, PPTX, XLSX, CSV generation
AudioPOST /audio/tts, POST /audio/sttText-to-speech and speech-to-text
SkillsGET/POST /skills, POST /skills/create, POST /skills/submitMarketplace and skill management
E.V.I. CanvasGET/POST /evi/canvasesBuild, compile, and publish E.V.I. personas
WorkflowsGET/POST /workflows, POST /workflows/{id}/runAutomation workflows
HooksGET/POST /hooksAutonomous event-triggered skill execution
EventsPOST /eventsPublish domain events
GuardrailsGET/POST /guardrail-policiesInput/output policy enforcement
Routing StudioGET/POST /routing-preferencesPer-customer routing preferences
Embed WidgetsGET/POST /iframesWhite-label chat widgets, analytics, and leads
Theo BrowserPOST /browser/sessionsManaged headless browser sessions
WebhooksGET/POST /webhooksOutbound event delivery
ConversationsGET /conversationsConversation history
ModelsGET /modelsAvailable engine registry
ToolsGET /toolsAvailable tool definitions
JobsGET /jobs/{id}Async job status polling
UsageGET /usage, GET /usage/exportUsage analytics and CSV export
BillingPOST /billing/checkout, POST /billing/portalCredit top-ups and billing portal
SettingsGET/PATCH /settingsAccount preferences
BenchmarksGET /benchmarksAggregated latency and routing telemetry
OrganizationsGET/POST /orgsTeam and membership management
AuditGET /audit, GET /audit/exportAudit log listing and CSV export
KeysPOST /keysAPI key management
HealthGET /healthSystem 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"
  }
}
StatusMeaning
400Bad request — invalid parameters
401Unauthorized — missing or invalid API key
403Forbidden — insufficient permissions
404Not found
429Rate limited — check Retry-After header
500Internal server error
503Service unavailable — check Retry-After header