Skip to main content

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.

What’s new across the Theo API, @hitheo/sdk, @hitheo/mcp, @hitheo/telegram, and @hitheo/whatsapp. We publish here when we ship something developers can use.

​
Versioning Policy

  • Packages follow semver. Pre-1.0.0, the minor bump is the breaking-change signal (matches how npm’s ^ operator resolves 0.x.y) — ^0.1.6 does not auto-upgrade to 0.2.0.
  • Additive changes (new endpoints, optional fields, new SDK methods) ship as minor or patch and never break pinned callers.
  • The API surface at https://www.hitheo.ai/api/v1/* is dated, not path-versioned. The current version is 2026-03-28, returned in the Theo-Api-Version header.

​
[Unreleased]

​
Added

  • Gateway Guardrails — opt-in input/output policies enforced on every completion bound to an API key. Five built-in protections (PII redactor, prompt-injection deny, JSON repair, max-length truncate, profanity flag) with five verdicts (flag, redact, truncate, repair, deny). Enforcement is unified across /v1/completions (streaming and non-streaming), /v1/images, /v1/code, /v1/documents, the playground, and embed widgets. SDK adds theo.guardrails.policies, theo.guardrails.presets, theo.guardrails.executions, and theo.keys.{get,set}GuardrailPolicy(). New error code guardrail_violation (HTTP 422) on deny verdicts. See the Guardrails guide.
  • Routing Studio — per-customer routing preferences with a visual editor, preset gallery, keyword rules, few-shot examples, and per-mode confidence-floor overrides. API at /api/v1/routing-preferences with full CRUD plus a /test endpoint that replays a fixture prompt before and after the preference. Per-key binding at /api/v1/keys/{id}/routing-preference. Streaming meta and done events surface routing.customer_preference whenever a bound preference contributes. SDK adds theo.routingPreferences.* and theo.keys.{get,set}RoutingPreference. See the Routing Studio guide.
  • Playground routing receipt — every assistant turn renders an inline receipt below the model badge, surfacing the routing decision behind each response. Compact view shows requested → resolved mode and a Promoted chip when routing overrode the caller’s choice. Expand for classification confidence, skill overrides, locked family, and the four-stage pipeline visual. A green Studio chip lights up when a Routing Studio preference contributed.
  • SDK theo.verify() — first-run connectivity and auth diagnostic. Returns { healthy, authenticated, baseUrl, latencyMs } with actionable hints for common setup states.
  • CLI theo verify — machine-readable JSON output for the same diagnostic. Non-zero exit on failure so CI can gate on it.
  • SDK TheoStream — theo.stream(...) returns an async-iterable with a cancel() method for graceful mid-generation abort, plus final-metadata properties (conversationId, usage, model, requestId) populated from the meta and done events.
  • Discriminated StreamEvent union — switch (event.type) narrows event.data automatically. No as any needed.
  • Typed SDK list and get returns — conversations(), skills(), tools(), workflows(), submissions(), listWebhooks(), listHooks(), usage(), and their mutation pairs now return named interfaces (ConversationSummary, SkillSummary, WorkflowRecord, etc.) instead of unknown[].
  • CompletionRequest extensions — conversation (inline envelope), personality_config, response_style, theo_branding, brand_soul, attachments, image_model, image_quality, stealth_model, stealth_aspect, stealth_duration.
  • Idempotency-Key support — state-changing POSTs across /workflows, /skills, /webhooks, /hooks, /events, /evi/canvases, /iframes, /browser/sessions accept the Idempotency-Key header. Responses cached 24 hours per key.
  • request_id in JSON responses — /completions, /images, /video, /code, /research, /documents, /audio/stt surface the request id as a top-level field in addition to the existing response header.
  • conversation_id in stream events — the meta and done events on /completions include conversation_id so clients don’t have to read it separately.
  • Follow-ups documentation — concept page covering when follow_ups[] is generated and chat-UI integration patterns.
  • Full SSE schemas published — Streaming Completions reference now publishes TypeScript interfaces for every event (meta, token, tool, artifact, genui_meta, skills, done, error).
  • Cross-session memory — Theo now carries relevant context across conversations and channels automatically. New threads can open with a short, relevant recap of prior related work, and Theo tracks open loops so later follow-ups resume where you left off. Memory is scoped per owner and is never used to train models. See Conversations & Memory.
  • Embed widget operator tools — embedded chat widgets now support live human takeover, a full analytics view (sessions, leads, conversion, geo), and lead capture with CSV export. List sessions, read transcripts, take over or release a conversation, and post operator messages under /api/v1/iframes/{id}/conversations. See the Embed Widget guide.

​
Improved

  • SDK default baseUrl is now https://www.hitheo.ai. Pin baseUrl explicitly if you target a different host.
  • MCP server default THEO_BASE_URL is now https://www.hitheo.ai.
  • CompletionResponse.usage includes prompt_tokens, completion_tokens, total_tokens, and an optional cached flag. cached: true is present on responses served from the semantic cache.
  • theo status CLI probes both hitheo.ai and www.hitheo.ai and warns when the configured baseUrl is a redirect target.
  • SSE error event envelope matches the REST error envelope — { error: { message, type, code, request_id } }. One error-handling code path for REST and streaming.
  • Optional fields accept null across /completions, /chat/completions, /conversations, /playground/completions, /events, /images, /video, /code, /research, /documents, /audio/tts. Matches the industry norm of treating null as “field omitted.”
  • EviInstance.stream() returns a TheoStream. for await continues to work unchanged; .cancel() and final metadata are now available.

​
Migration

Most callers need only npm update @hitheo/sdk. See the upgrade guide bundled with the SDK README.

​
[0.3.0] — 2026-06-01

​
Added

  • SDK streamIdleTimeoutMs config (default 120s) — streaming responses use an idle (between-chunks) timeout instead of a total-duration cap, so a long but actively-producing stream is never severed mid-flight.
  • New SDK error types — TheoTimeoutError (carries timeoutMs) and TheoCancelledError, plus a kind discriminator ("http" | "timeout" | "cancelled" | "network") on TheoApiError. TheoUsageError is thrown synchronously for SDK misuse. All subclasses remain instanceof TheoApiError.
  • Typed async job results — JobStatus<T> is generic with ResearchJobResult, VideoJobResult, ImageJobResult, DocumentJobResult; job<T>() and waitForJob<T>() are generic.
  • waitForJob options object — { intervalMs, maxWaitMs, signal, onProgress } adds a progress callback and AbortSignal cancellation. The legacy positional (id, intervalMs?, maxWaitMs?) signature still works.
  • SSE parser tolerance — event: / data: lines are accepted with or without the trailing space.
  • New docs — Timeouts & Retries and Async Jobs.

​
Improved

  • GET /api/v1/jobs/{id} result is sanitized — completed video/image jobs expose Theo-branded model / engine instead of raw upstream providerId / modelId.
  • OpenAI-compatible base URL is documented consistently as https://www.hitheo.ai/api/v1.
  • Timeouts are no longer retried on non-idempotent POSTs (complete, research, video) — eliminates the double-run / double-bill risk on slow generations. A timeout now throws TheoTimeoutError instead of a generic TheoApiError(0).
  • Async modes fail fast — passing mode: "research" | "video" to complete() / stream() throws TheoUsageError immediately instead of hanging until the request timeout.

​
Migration

  • If you matched the waitForJob polling timeout via err.status === 408, switch to err instanceof TheoTimeoutError (status is now 0, kind: "timeout").
  • If you ran research / video through complete() / stream(), move to theo.research() / theo.video() + theo.waitForJob(). See Async Jobs.

​
[0.1.6] — 2026-04-17

​
Added

  • Theo Browser SDK — @hitheo/sdk exposes theo.browser.* wrapping the managed headless-browser API (POST /api/v1/browser/sessions, live-view refresh, snapshot, end). See Theo Browser (API) and Theo Browser (SDK).
  • Embed-ready Theo Browser iframe — every new session includes an embed_url third-party apps can drop into an iframe without building UI. Short-lived signed token; auto-refresh on disconnect.
  • Branded TTS voice identifiers — POST /api/v1/audio/tts now accepts theo-voice-classic, theo-voice-bright, theo-voice-storyteller, theo-voice-deep, theo-voice-warm, theo-voice-soft.

​
Improved

  • GET /api/v1/benchmarks is now an authenticated endpoint. Responses include Cache-Control: private.

​
[0.1.5] — 2026-04-17

​
Improved

  • Published READMEs across every @hitheo package on npm refreshed to reflect the current runtime surface, with upgrade guidance for older releases.

​
[0.1.4] — 2026-04-17

​
Added

  • Signed GitHub provenance attestations on every published npm tarball. Verify with npm audit signatures @hitheo/sdk @hitheo/mcp @hitheo/telegram @hitheo/whatsapp.

​
[0.1.3] — 2026-04-16

​
Improved

  • Consistent Theo-branded surface across documentation, SDK, and channel adapters.

​
[0.1.2] — 2026-04-15

​
Added

​
Improved

  • @hitheo/mcp, @hitheo/telegram, @hitheo/whatsapp now ship with full READMEs on npm.
  • @hitheo/sdk README security guidance refreshed — points readers at per-key allowed_origins and the Security docs.

​
[0.1.1] — 2026-04-15

​
Added

  • E.V.I. Canvas SDK methods — canvases, canvas, createCanvas, updateCanvas, deleteCanvas, compileCanvas, testCanvas, publishCanvas.
  • Webhooks SDK methods — listWebhooks, createWebhook, updateWebhook, deleteWebhook, testWebhook, webhookDeliveries.
  • Hooks SDK methods — listHooks, createHook, updateHook, deleteHook, hookExecutions.
  • Events SDK — publishEvent.
  • @hitheo/telegram — attachment support (photo, voice, audio, document), pluggable conversation store, X-Telegram-Bot-Api-Secret-Token verification, chunked replies.
  • @hitheo/whatsapp — media handling, HMAC X-Hub-Signature-256 verification (verifySignature, verifyWebhook helpers), conversation store, chunked replies.
  • @hitheo/mcp — tool catalog refresh, project-config loader (theo.config.json|js|ts).

​
[0.1.0] — 2026-04-15

​
Added

​
Documentation

  • Published comprehensive docs at docs.hitheo.ai.
  • Full API reference with OpenAPI 3.1 spec.
  • SDK, CLI, and MCP reference guides.
  • Skills deep dive with marketplace authoring guide.
  • 10+ guides covering E.V.I., IDE integration, workflows.

​
[API v1] — 2026-03-28

​
Added

  • Core completions API with multi-model routing.
  • Skill marketplace with automated review pipeline.
  • E.V.I. (Embedded Virtual Intelligence) support.
  • SDK (@hitheo/sdk), CLI, and MCP server (@hitheo/mcp).
  • Channel adapters for Telegram and WhatsApp.
  • Workflow automation with schedules and event triggers.
  • Image, video, code, research, and document generation.
  • Audio TTS and STT.
  • Per-token billing with credit system.