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.

All notable changes to the Theo API, @hitheo/sdk, @hitheo/mcp, @hitheo/telegram, and @hitheo/whatsapp are tracked here. The format is based on Keep a Changelog.

​
Versioning Policy

  • Packages follow semver. While we’re pre-1.0.0, the minor bump is the breaking-change signal (not major), which matches how npm’s ^ operator resolves 0.x.y — ^0.1.6 will NOT auto-upgrade to 0.2.0.
  • A breaking change is any behavior that existing callers can reasonably depend on: default values, response shapes, error envelopes, public SDK types, CLI flag names, HTTP status codes for the same input.
  • Additive changes (new endpoints, new optional fields, new SDK methods) are minor or patch and never break pinned callers.
  • The API surface at https://www.hitheo.ai/api/v1/* itself is not versioned by path — breaking changes there are surfaced via the Theo-Api-Version request header and a Theo-Deprecation response header. Current version: 2026-03-28.

​
[Unreleased]

​
Added

  • SDK theo.verify() — first-run connectivity and auth diagnostic. Calls /health then /models and returns { healthy, authenticated, baseUrl, latencyMs, error?, hint? } with actionable remediation hints (redirect 401, invalid key, wrong scope, network down).
  • CLI theo verify — machine-readable JSON output for the same diagnostic. Exits non-zero on failure so CI pipelines can gate on it.
  • SDK TheoStream — theo.stream(...) now returns an async-iterable handle with a cancel() method (graceful mid-generation abort) and final-metadata properties (conversationId, usage, model, requestId) populated from the meta and done events.
  • Discriminated StreamEvent union — switch (event.type) now narrows event.data automatically. No more (event.data as any).
  • Typed SDK list/get returns — conversations(), conversation(id), skills(filter?), tools(), workflows(), submissions(), skillVersions(), listWebhooks(), webhookDeliveries(), listHooks(), hookExecutions(), usage(), publishEvent(), and their mutation pairs now return named interfaces (ConversationSummary, SkillSummary, SdkToolDefinition, WorkflowRecord, WebhookRecord, HookRecord, UsageReport, etc.) instead of Promise<unknown[]>.
  • CompletionRequest extensions — added conversation (inline envelope), personality_config, response_style, theo_branding, brand_soul, attachments, image_model, image_quality, stealth_model, stealth_aspect, stealth_duration to match every field the v1 schema already accepted.
  • Idempotency-Key on state-changing POSTs — POST /api/v1/workflows, /workflows/{id}/run, /skills (install), /skills/submit, /skills/create, /webhooks, /hooks, /events, /evi/canvases, /evi/canvases/{id}/publish, /iframes, /iframes/{id}/duplicate, /browser/sessions now accept the Idempotency-Key header. Responses cached 24h per (user, key); replays return X-Idempotent-Replay: true.
  • request_id in JSON responses — POST /api/v1/completions (including the stream meta + done events), /images, /video, /code, /research, /documents, /audio/stt now surface the server-assigned request id as a top-level field in addition to the existing X-Request-Id header.
  • conversation_id in stream events — The meta and done events on /api/v1/completions now include conversation_id (null for stateless callers) so clients don’t have to read it from a separate header or endpoint.
  • Follow-ups docs — new concept page covering when follow_ups[] is generated, the { label, prompt } shape, and chat-UI integration patterns.
  • 401 Troubleshooting — new page covering the apex→www redirect (the #1 cause of first-time 401s) and other common auth failure modes.
  • Full SSE payload schemas — Streaming Completions (API reference) now publishes TypeScript interfaces for every event (meta, token, tool, artifact, genui_meta, skills, done, error) plus a mid-stream 429 example.

​
Changed

  • SDK default baseUrl is now https://www.hitheo.ai (was https://hitheo.ai). The apex 307-redirects to www and most HTTP clients strip the Authorization header on 3xx responses, which caused a confusing first-time 401. Pin baseUrl explicitly if you’re on a staging host.
  • MCP server default THEO_BASE_URL is now https://www.hitheo.ai for the same reason.
  • CompletionResponse.usage now includes prompt_tokens, completion_tokens, total_tokens, and an optional cached flag — previously the SDK type only exposed cost_cents, even though the server had been returning all four fields. cached: true is present on responses served from the semantic cache.
  • theo status CLI probes both hitheo.ai and www.hitheo.ai and warns if your configured baseUrl is a redirect target that drops the Authorization header.
  • SSE error event envelope now matches the REST error envelope — was { message }, is now { error: { message, type, code, request_id } }. Clients can now reuse a single error-handling code path for REST and streaming.
  • Zod schemas accept null for optional fields on /completions, /chat/completions, /conversations, /playground/completions, /events, /images, /video, /code, /research, /documents, /audio/tts. Matches the industry norm (OpenAI, Anthropic, Stripe) of treating null as equivalent to the field being omitted.
  • EviInstance.stream() now returns a TheoStream (was an AsyncGenerator<StreamEvent>). for await still works unchanged; you also get .cancel() and final metadata.

​
Fixed

  • SDK complete() now surfaces the server’s X-Request-Id as response.request_id even when the body doesn’t already carry it.

​
Migration

​
See the 0.2.0 migration guide below for each of the breaking changes. Most callers need only npm update @hitheo/sdk.

​
[0.1.6] — 2026-04-17

​
Added

  • @hitheo/sdk exposes a new theo.browser.* client 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.

​
Changed

  • Breaking: GET /api/v1/benchmarks now requires authentication. The endpoint previously allowed anonymous reads and responds with Cache-Control: private. Any client that scraped it without auth must pass a key.
  • TTS upstream voice identifiers are no longer accepted or echoed back — use the Theo-branded aliases above.

​
[0.1.5] — 2026-04-17

​
Changed

  • Doc-only patch: synchronizes every package’s README on npm with the 0.1.4 runtime behavior and adds upgrade guidance for anyone still on ≤0.1.3. No runtime changes.

​
[0.1.4] — 2026-04-17

​
Security

  • Coordinated security release across @hitheo/sdk, @hitheo/mcp, @hitheo/telegram, and @hitheo/whatsapp. Upgrading is strongly recommended for all users. Rotate any long-lived tokens used with @hitheo/telegram@≤0.1.3.
  • Published npm tarballs now carry signed GitHub provenance attestations. Verify with npm audit signatures @hitheo/sdk @hitheo/mcp @hitheo/telegram @hitheo/whatsapp.

​
Changed

  • Minor CI hardening and internal dependency cleanup.

​
[0.1.3] — 2026-04-16

​
Changed

  • Documentation, SDK, and channel adapters updated to present a consistent Theo-branded surface throughout. Internal runbooks and architecture references now live outside the public docs repository.

​
[0.1.2] — 2026-04-15

​
Added

​
Changed

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

​
Fixed

  • CI publish pipeline now builds @hitheo/sdk before downstream matrix jobs, so telegram/whatsapp/mcp compile against a built SDK.

​
[0.1.1] — 2026-04-15

​
Added

  • SDK methods for E.V.I. Canvas (canvases, canvas, createCanvas, updateCanvas, deleteCanvas, compileCanvas, testCanvas, publishCanvas), Webhooks (listWebhooks, createWebhook, updateWebhook, deleteWebhook, testWebhook, webhookDeliveries), Hooks (listHooks, createHook, updateHook, deleteHook, hookExecutions), and Events (publishEvent).
  • @hitheo/telegram attachments (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, document generation.
  • Audio TTS/STT.
  • Per-token billing with credit system.