> ## 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.

# Changelog

> What's new in the Theo API, SDK, and channel adapters.

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](https://semver.org). 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

* **Build your own executable orchestrator.** The per-key Orchestrator canvas is now a real, runnable graph. Draw the flow — Entry → Router / Classifier → Model → Guardrail — wire a branch per mode, and every prompt to that key runs exactly the path you drew, with routing, skills, guardrails, and brand all applied. Fresh graphs seed strong default models per mode. A live **Test chat** runs the staged canvas (unsaved edits included) and lights up the path each prompt takes; attach images or documents (PDF / DOCX / XLSX / CSV / TXT) to try vision and document flows, and the preview never draws credits.
* **Bring your own models.** Register a custom model endpoint (any compatible chat-completions API) in Orchestrator settings, then pick it on any Model node or in the E.V.I. Canvas — that key runs on your own endpoint. Prompts to your own models are free and never draw credits.
* **Custom modes.** Create your own routing modes (for example `jokes` or `pets`) in Routing Studio and use them as routing-rule targets or as the mode a graph node handles, alongside the built-in modes.
* **Independent guardrails per checkpoint.** Each Guardrail node in a graph binds its own policy, so different points in the flow can enforce different rules — an injection check on the way in, a redactor on the way out.
* **Image and video in the orchestrator graph.** Add media branches and choose the generation engine per node, so one key can route text, image, and video prompts through a single graph.
* **Orchestrator goes fullscreen.** A new `⛶ Fullscreen` button on the Orchestrator toolbar promotes the entire surface — toolbar, test prompt, canvas, and the skills tray — into a viewport-spanning workspace. Esc or clicking the button again exits. Clicking any "↗ Open in Routing Studio / Guardrails / Skills" link inside a drawer drops fullscreen so you land cleanly on the linked page.
* **Test prompt lights up the whole path, not just the arrows.** Every node the prompt passes through (entry → rules or classifier → category → mode → model → guardrails) now glows cyan in lockstep with the animated edges, so the trail reads as one continuous signal you can follow at a glance.
* **Orchestrator — your own per-key control surface.** New dashboard page at `/dashboard/orchestrator` (and a sidebar entry under BUILD). Pick one of your API keys and shape its orchestration on a single canvas: add routing rules that route keywords to a specific Theo mode, attach the skills the key may call, bind a Guardrails policy, and overlay your brand identity. Saved changes show up on the canvas immediately — your rules render as arrows landing on the target mode pill, your skills appear as chips, your guardrails sit as a terminal node after the models. A **Test prompt** input above the canvas resolves any prompt against the current configuration (rules-only or full classifier) and highlights the path it would take. A **Quick start** banner offers three opinionated preset packs (Customer Support, Code Assistant, Research Assistant) to seed routing rules + brand identity in one click. Existing Routing Studio sets are pickable from the routing drawer, so a shared preference can drive multiple keys without copy/paste.
* **Embed widget voice mode is fully brand-aware.** Open voice in your widget and visitors see your logo and brand name in the header, an orb that glows in your primary color while it listens and speaks, transcripts that match your text-chat bubbles, and a clean controls bar in your theme — every surface a visitor touches in voice mode now matches the brand you set in the iframe builder. The previous shared playground UI has been retired from the embed surface.
* **Brand-scoped responses on embed widgets.** Turn on the new **Scope responses to this brand** toggle on any API key and Theo stays inside that brand's catalog — it recommends only your own products and content, never names or compares to competitors (not even as analogy or style reference), and politely redirects off-topic requests back to your support URL. The toggle flips on automatically when you use Fetch Brand in the iframe builder, so importing a brand is a single click to get an end-to-end brand-locked assistant.
* **Rich responses in embed widget chats.** Theo's replies inside iframe widgets now render formatting visually — inline brand-logo images, headings, lists, tables, code blocks, links — instead of leaking the underlying Markdown as raw text. Styling matches your widget theme (heading and link colors follow your primary color, code blocks pick up your bubble background).

### Improved

* **Engines that aren't live yet show as WIP.** In the Orchestrator graph and the per-key model pickers, an engine that's still being brought online (currently Theo Arca) appears with a `(WIP)` label and is disabled — so you always pick from engines that are ready to serve traffic. Keys already routing through it fall through to their configured fallback with no interruption.

* **Brand auto-fill in the iframe builder reaches more domains.** Paste a marketing subdomain like `os.example.com` and the importer retries against your root `example.com` if the precise subdomain has no indexed data, so the import succeeds where it used to silently return empty. The result card surfaces the canonical brand source so you can see exactly where the data came from.

* **Brand auto-fill tells you why an import didn't succeed.** When a fetch returns no brand data, an unconfigured provider, or an invalid URL, you see an inline message under the input with the specific reason. No more silent clicks.

* **Brand auto-fill shows your imported brand the moment it's ready** instead of waiting for the screenshot capture in parallel. A failed fetch surfaces its reason in under two seconds; a successful fetch populates the brand fields immediately and lets the screenshot land separately when it finishes.

* **Iframe builder Fetch Brand updates the API key's Brand Soul too.** A successful brand import now imports the brand identity onto the linked API key — name, tagline, logo, colors, ethos, industry, and support URL — so the visitor-facing assistant introduces itself as your brand from the very first message, not just the widget chrome.

* **Embed widget Brand Soul applies on every turn — including voice and pre-chat lead form flows.** The brand identity you configure on an API key (name, tagline, tone, ethos, CTA, support URL) drives how the widget greets visitors and answers "who are you?" on every channel, end to end.

* **Team API keys now work in the widget builder.** If your team shares an API key through an organization, you can now select it when creating a chat widget. Personal keys and team keys both appear in the same picker and both bind cleanly.

* **Clearer errors when a widget can't be created.** The Create Widget button now tells you why if the request fails — invalid key, validation issue, billing state — instead of a generic placeholder.

* **Embed chat input handles long content gracefully.** The chat textarea grows with the visitor's message, wraps very long URLs or unbroken text instead of pushing the send button off-screen, and never collapses to a single line on multi-line replies.

* **Ask Theo in the canvas editor** — small Theo icon next to every text field in the E.V.I. Canvas (Prompt, Tool, Vision, Output, Condition, Webhook, Web Knowledge nodes, plus the Publish dialog blurb). Click it and Theo reads your live canvas, then streams a context-aware suggestion into the field as you watch. The Prompt builder's Theo Assist menu now leads with **Write from Scratch** — generate a fresh, validator-compliant system prompt with the right role + constraints + runtime template variables, all inferred from your canvas. The five existing actions (Enhance, Rewrite, Simplify, Add Examples, Make Concise) follow underneath in the same menu so you have one Theo entry point per field.

* **Per-key skills picker** — new **Skills** pill on every API key in your dashboard. Click to choose exactly which of your installed skills that key may call. New skills you publish or install later won't auto-attach — you stay in control of every key's capability surface.

* **Per-skill keys picker** — inverse view inside any installed skill's detail panel (My Skills → click a skill). Tick which of your API keys can call this skill without leaving the skill view.

* **"Enable on which keys?" step at publish time** — the Publish dialog now ends with an explicit picker so you choose which keys see your new skill. Default is nothing checked — opt in per key, or skip entirely and add later from the Skills or Keys pages.

* **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](/guides/guardrails).

* **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](/guides/routing-studio).

* **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](/core-concepts/follow-ups)** — concept page covering when `follow_ups[]` is generated and chat-UI integration patterns.

* **Full SSE schemas published** — [Streaming Completions reference](/api-reference/completions/streaming) 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](/core-concepts/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](/guides/embed-widget).

### Improved

* **API key skill bindings are explicit-only.** When you create a new API key, it starts with zero skills callable. You decide which skills it can use, when you want them on it. Existing keys' current capability sets are preserved during the migration — your apps keep working without any change on your side.
* **Prompt Builder writes validator-compliant prompts on the first try.** The new **Write from Scratch** action knows the canvas validator's requirements (role definition, explicit constraints) and the available runtime template variables (`{{user_name}}`, `{{user_input}}`, `{{current_date}}`, `{{language}}`, `{{skill_name}}`) so the generated prompt passes validation immediately, without a second round of editing.
* **Auto-resizing description fields on Tool and Output nodes.** Descriptions grow vertically as you type — or as Ask Theo streams in — so long capability summaries stay fully visible instead of clipping at one line.
* **Document generation reliability and chrome.** PDF / DOCX / CSV / PPTX / XLSX generation produces a properly rendered file in the playground, with a clean download card under the assistant reply (format badge, file size, click to download). Error messages on the rare retry path stay vendor-neutral and on-brand.
* **Toolbar tightened on the canvas editor.** The **▶ FULL** shortcut (open the published version in the main Playground) now only renders once the canvas has actually been published, so the toolbar reads as a clean `TEST → COMPILE → PUBLISH` pipeline until it has a destination to open.
* **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.

### Fixed

* **Theo Reason and Theo Flash no longer pivot to PDF generation on text requests.** Calls to `/api/v1/chat/completions` and `/api/v1/completions` always return reasoning text now, even when your prompt happens to mention words like "report", "memo", "brief", "PDF", "docx", or "presentation". The previous behavior silently hijacked your request into document generation, then either timed out or returned a "couldn't generate your PDF" message — breaking OpenAI-SDK consumers that expect `choices[].message.content`. Document generation through the chat API is no longer inferred from prompt phrasing — if you want a document, use the dedicated `/api/v1/documents` endpoint.
* **Document generation produces real downloads again.** PDFs, DOCX files, PowerPoint decks, Excel sheets, and CSVs from `/api/v1/documents` and the playground now reliably render and surface a working `download_url`. The previous failure modes (a canned "Theo couldn't generate your PDF document" reply or a 504 timeout after \~90 seconds) are gone, and a slow upstream now falls through to a placeholder artifact instead of timing out the request.

### 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](/sdk-reference/timeouts-and-retries) and [Async Jobs](/guides/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](/guides/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)](/api-reference/browser/sessions) and [Theo Browser (SDK)](/sdk-reference/browser).
* **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

* **API reference expansion** — new sections for Webhooks (create, list, update, delete, test, deliveries, retry, rotate-secret, stats), Hooks (create, list), Iframes (create, list), Settings (get, update), Benchmarks (get), and E.V.I. Canvas.
* **New guides** — [E.V.I. Canvas](/guides/evi-canvas), [Voice Integration](/guides/voice-integration), [Embed Widget](/guides/embed-widget), [Webhooks & Hooks](/guides/webhooks-and-hooks), [Skills API](/guides/skills-api).
* **SDK reference** — new [`sdk-reference/canvases`](/sdk-reference/canvases) page.

### 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](/security/authentication).

***

## \[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

* **First npm release** under the `@hitheo` scope: [`@hitheo/sdk`](https://www.npmjs.com/package/@hitheo/sdk), [`@hitheo/mcp`](https://www.npmjs.com/package/@hitheo/mcp), [`@hitheo/telegram`](https://www.npmjs.com/package/@hitheo/telegram), [`@hitheo/whatsapp`](https://www.npmjs.com/package/@hitheo/whatsapp).
* All packages are pure ESM with TypeScript declarations.
* CLI available globally via `npm install -g @hitheo/sdk` → `theo init`.

### Documentation

* Published comprehensive docs at [docs.hitheo.ai](https://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.