# Theo API Docs

## Docs

- [Speech to Text](https://docs.hitheo.ai/api-reference/audio/speech-to-text.md): Transcribe audio files to text.
- [Text to Speech](https://docs.hitheo.ai/api-reference/audio/text-to-speech.md): Convert text to spoken audio (returns MP3 binary).
- [List Audit Events](https://docs.hitheo.ai/api-reference/audit/list.md): Query the immutable audit trail.
- [Authentication](https://docs.hitheo.ai/api-reference/authentication.md): API key authentication for all Theo API endpoints.
- [Get Benchmarks](https://docs.hitheo.ai/api-reference/benchmarks/get.md): Retrieve aggregated platform performance benchmarks for a given time window.
- [Create a top-up checkout](https://docs.hitheo.ai/api-reference/billing/checkout.md): Generate a hosted checkout URL to add credits to your personal balance or your team's shared credit pool.
- [Open the billing portal](https://docs.hitheo.ai/api-reference/billing/portal.md): Generate a short-lived customer portal URL for a user's personal billing or an organization's team billing.
- [Embed the Theo Browser](https://docs.hitheo.ai/api-reference/browser/embed.md): Drop a live Theo Browser session into your own product with a single iframe.
- [Browser Sessions](https://docs.hitheo.ai/api-reference/browser/sessions.md): Create, inspect, refresh, and end Theo Browser sessions — headless browser automation with an iframe-embeddable live view.
- [Generate Code](https://docs.hitheo.ai/api-reference/code/generate.md): Generate production-quality code using the Theo Code engine.
- [Create Completion](https://docs.hitheo.ai/api-reference/completions/create.md): Send a prompt through the full orchestration pipeline — intent classification, skill loading, model routing, agent loop, and response.
- [OpenAI-Compatible Chat Completions](https://docs.hitheo.ai/api-reference/completions/openai-compat.md): Drop-in replacement for the OpenAI Chat Completions API. Point the OpenAI SDK at Theo and keep writing code the way you already do.
- [Streaming Completions](https://docs.hitheo.ai/api-reference/completions/streaming.md): Full SSE event schemas, wire format, and error semantics.
- [Get Conversation](https://docs.hitheo.ai/api-reference/conversations/get.md): Get a specific conversation with its messages.
- [List Conversations](https://docs.hitheo.ai/api-reference/conversations/list.md): List all conversations for the authenticated user.
- [Generate Document](https://docs.hitheo.ai/api-reference/documents/generate.md): Generate PDF, DOCX, PPTX, XLSX, or CSV documents from natural language.
- [Publish Event](https://docs.hitheo.ai/api-reference/events/publish.md): Publish a custom event to trigger workflows and integrations.
- [Canvases](https://docs.hitheo.ai/api-reference/evi/canvases.md): Create, list, update, and delete E.V.I. canvases.
- [Compile Canvas](https://docs.hitheo.ai/api-reference/evi/compile.md): Validate and compile an E.V.I. canvas into a SkillManifest and WorkflowSteps.
- [Publish Canvas](https://docs.hitheo.ai/api-reference/evi/publish.md): Compile and publish an E.V.I. canvas as a skill with configurable visibility.
- [Test Canvas](https://docs.hitheo.ai/api-reference/evi/test.md): Send a test message through a compiled E.V.I. canvas in sandbox mode.
- [Health Check](https://docs.hitheo.ai/api-reference/health/check.md): Check system health — no authentication required.
- [Create Hook](https://docs.hitheo.ai/api-reference/hooks/create.md): Install an autonomous hook that triggers skill execution when matching events occur.
- [List Hooks](https://docs.hitheo.ai/api-reference/hooks/list.md): List all installed hooks and available hook presets.
- [Create Iframe Widget](https://docs.hitheo.ai/api-reference/iframes/create.md): Create a new embeddable chat widget configuration linked to an API key.
- [List Iframe Widgets](https://docs.hitheo.ai/api-reference/iframes/list.md): List all embeddable widget configurations for the authenticated user.
- [Generate Images](https://docs.hitheo.ai/api-reference/images/generate.md): Generate images from text prompts using the Theo Create engine.
- [Get Job Status](https://docs.hitheo.ai/api-reference/jobs/get.md): Poll the status of an asynchronous job (video, research, etc.).
- [Create API Key](https://docs.hitheo.ai/api-reference/keys/create.md): Create a new API key for programmatic access.
- [List Models](https://docs.hitheo.ai/api-reference/models/list.md): List all available Theo engine models and their capabilities.
- [Create Organization](https://docs.hitheo.ai/api-reference/organizations/create.md): Create a new organization for team management.
- [API Reference Overview](https://docs.hitheo.ai/api-reference/overview.md): REST API for AI orchestration — completions, images, video, code, research, documents, skills, and more.
- [Create Research](https://docs.hitheo.ai/api-reference/research/create.md): Run deep web research with source synthesis (asynchronous).
- [Get Settings](https://docs.hitheo.ai/api-reference/settings/get.md): Read the current user's preferences.
- [Update Settings](https://docs.hitheo.ai/api-reference/settings/update.md): Update the current user's preferences. All fields are optional — only provided fields are changed.
- [Create Skill](https://docs.hitheo.ai/api-reference/skills/create.md): Author a new skill (private by default).
- [Get Skill](https://docs.hitheo.ai/api-reference/skills/get.md): Get details for a specific skill.
- [Install Skill](https://docs.hitheo.ai/api-reference/skills/install.md): Install a marketplace skill for the authenticated user.
- [List Skills](https://docs.hitheo.ai/api-reference/skills/list.md): List marketplace or installed skills.
- [Skill Reviews](https://docs.hitheo.ai/api-reference/skills/reviews.md): Get and submit user reviews for a marketplace skill.
- [Submit Skill](https://docs.hitheo.ai/api-reference/skills/submit.md): Submit a skill manifest for marketplace review and publishing.
- [Skill Versions](https://docs.hitheo.ai/api-reference/skills/versions.md): Get version history for a published skill.
- [List Tools](https://docs.hitheo.ai/api-reference/tools/list.md): List all available tool definitions (system + skill tools).
- [Get Usage](https://docs.hitheo.ai/api-reference/usage/get.md): Get API usage analytics and cost tracking.
- [Generate Video](https://docs.hitheo.ai/api-reference/video/generate.md): Generate video from text prompts (asynchronous).
- [Create Webhook](https://docs.hitheo.ai/api-reference/webhooks/create.md): Register a new webhook endpoint to receive real-time event notifications.
- [Delete Webhook](https://docs.hitheo.ai/api-reference/webhooks/delete.md): Permanently remove a webhook endpoint. This cannot be undone.
- [List Deliveries](https://docs.hitheo.ai/api-reference/webhooks/deliveries.md): View recent delivery attempts for a webhook, including successes and failures.
- [List Webhooks](https://docs.hitheo.ai/api-reference/webhooks/list.md): List all webhook endpoints registered for the caller's organization.
- [Retry Delivery](https://docs.hitheo.ai/api-reference/webhooks/retry.md): Re-dispatch a failed delivery's stored payload to the webhook endpoint.
- [Rotate Secret](https://docs.hitheo.ai/api-reference/webhooks/rotate-secret.md): Generate a new signing secret for a webhook. The old secret is invalidated immediately.
- [Webhook Stats](https://docs.hitheo.ai/api-reference/webhooks/stats.md): Get delivery metrics for a webhook: total deliveries, success/failure counts, and success rate.
- [Test Webhook](https://docs.hitheo.ai/api-reference/webhooks/test.md): Send a test event to verify your webhook endpoint is reachable and signature verification works.
- [Update Webhook](https://docs.hitheo.ai/api-reference/webhooks/update.md): Update the URL, event types, or enabled state of a webhook.
- [Create Workflow](https://docs.hitheo.ai/api-reference/workflows/create.md): Create a multi-step automation workflow.
- [List Workflows](https://docs.hitheo.ai/api-reference/workflows/list.md): List all workflows for the authenticated user.
- [Run Workflow](https://docs.hitheo.ai/api-reference/workflows/run.md): Trigger a manual workflow run.
- [Changelog](https://docs.hitheo.ai/changelog.md): Release notes for the Theo API, SDK, and channel adapters.
- [theo complete](https://docs.hitheo.ai/cli-reference/complete.md): Run a quick AI completion from the terminal.
- [Environment Variables](https://docs.hitheo.ai/cli-reference/environment-variables.md): Configuration via environment variables.
- [theo init](https://docs.hitheo.ai/cli-reference/init.md): Initialize Theo in a project — creates config, detects IDEs, writes MCP configs.
- [theo login](https://docs.hitheo.ai/cli-reference/login.md): Authenticate with the Theo API.
- [theo mcp install](https://docs.hitheo.ai/cli-reference/mcp-install.md): Configure MCP for specific IDEs.
- [CLI Overview](https://docs.hitheo.ai/cli-reference/overview.md): The Theo CLI — project setup, MCP configuration, diagnostics, and skill management.
- [Skill Commands](https://docs.hitheo.ai/cli-reference/skill-commands.md): Scaffold, validate, and publish skills from the CLI.
- [theo status / theo verify](https://docs.hitheo.ai/cli-reference/status.md): Check Theo API connection, auth, and system health.
- [Agent Loop & Tool Execution](https://docs.hitheo.ai/core-concepts/agent-loop.md): How Theo executes multi-step tool calls in an iterative loop.
- [Conversations & Memory](https://docs.hitheo.ai/core-concepts/conversations-memory.md): Multi-turn conversations with cross-session memory.
- [Follow-Ups](https://docs.hitheo.ai/core-concepts/follow-ups.md): How Theo generates suggested next prompts and how to render them in a chat UI.
- [Intent Classification & Modes](https://docs.hitheo.ai/core-concepts/intent-classification.md): How Theo determines the best execution mode for each request.
- [Engine Routing & Fallbacks](https://docs.hitheo.ai/core-concepts/model-routing.md): How Theo selects the best engine and handles failures.
- [Orchestration Pipeline](https://docs.hitheo.ai/core-concepts/orchestration-pipeline.md): How Theo processes every request through a 5-stage pipeline.
- [Personas & E.V.I.](https://docs.hitheo.ai/core-concepts/personas-evi.md): Replace Theo's personality with your own branded AI assistant.
- [Streaming](https://docs.hitheo.ai/core-concepts/streaming.md): How Theo streams responses over SSE, how to consume them, and how to cancel mid-generation.
- [API Keys](https://docs.hitheo.ai/dashboard/api-keys.md): Create and manage API keys from the dashboard.
- [Billing & Credits](https://docs.hitheo.ai/dashboard/billing-credits.md): Per-token billing, credit management, and spending caps.
- [Settings](https://docs.hitheo.ai/dashboard/settings.md): Account and organization settings.
- [Skill Management](https://docs.hitheo.ai/dashboard/skill-management.md): Install, configure, and manage skills from the dashboard.
- [Usage & Analytics](https://docs.hitheo.ai/dashboard/usage-analytics.md): Monitor API usage, costs, and model distribution.
- [Build an E.V.I.](https://docs.hitheo.ai/guides/build-an-evi.md): Embed Theo into your product with a custom persona, skills, and tools.
- [Cost Optimization](https://docs.hitheo.ai/guides/cost-optimization.md): Tips for reducing API costs while maintaining quality.
- [Custom Tool Execution](https://docs.hitheo.ai/guides/custom-tool-execution.md): Connect Theo to your product's actions via inline tools.
- [Embed a Chat Widget](https://docs.hitheo.ai/guides/embed-widget.md): Add a white-label Theo chat widget to your website with a single script tag.
- [Build with the E.V.I. Canvas](https://docs.hitheo.ai/guides/evi-canvas.md): Design AI skills visually with the drag-and-drop canvas editor.
- [IDE Integration](https://docs.hitheo.ai/guides/ide-integration.md): Use Theo in Cursor, Claude Code, Warp, Windsurf, and VS Code via MCP.
- [Semantic Caching](https://docs.hitheo.ai/guides/semantic-caching.md): How Theo caches responses to reduce cost and latency.
- [Activating Skills via API](https://docs.hitheo.ai/guides/skills-api.md): How to find skill slugs, pass them in API calls, and use them from the SDK.
- [Telegram Bot Setup](https://docs.hitheo.ai/guides/telegram-bot.md): Connect Theo to Telegram using the @hitheo/telegram adapter.
- [Voice Integration](https://docs.hitheo.ai/guides/voice-integration.md): Add real-time voice conversations to your app using Theo's voice API.
- [Webhooks & Hook Events](https://docs.hitheo.ai/guides/webhooks-and-hooks.md): Receive real-time notifications and trigger autonomous skill execution via webhooks and hooks.
- [WhatsApp Integration](https://docs.hitheo.ai/guides/whatsapp-integration.md): Connect Theo to WhatsApp using the @hitheo/whatsapp adapter.
- [Workflow Automation](https://docs.hitheo.ai/guides/workflow-automation.md): Build multi-step automated workflows with schedules and event triggers.
- [Theo Documentation](https://docs.hitheo.ai/index.md): AI orchestration API — one call, every model, full pipeline.
- [How Theo Thinks](https://docs.hitheo.ai/introduction/how-theo-thinks.md): The multi-stage orchestration pipeline behind every API call.
- [Theo vs. Alternatives](https://docs.hitheo.ai/introduction/theo-vs-alternatives.md): How Theo compares to model proxies, LangChain, and direct model APIs.
- [What is Theo?](https://docs.hitheo.ai/introduction/what-is-theo.md): AI orchestration API — one call, every model, full pipeline.
- [Install MCP](https://docs.hitheo.ai/mcp/install.md): Set up @hitheo/mcp in Cursor, Claude Code, Warp, Windsurf, VS Code, or any other MCP-compatible IDE.
- [MCP Server Overview](https://docs.hitheo.ai/mcp/overview.md): How Theo plugs into Cursor, Claude Code, Warp, Windsurf, VS Code, and any other MCP-compatible IDE via @hitheo/mcp.
- [Project Config](https://docs.hitheo.ai/mcp/project-config.md): Use theo.config.json to pin a persona, default skills, and inline tools for every MCP call in a repo.
- [Resources](https://docs.hitheo.ai/mcp/resources.md): The three read-only theo:// URIs your IDE agent can fetch via @hitheo/mcp.
- [Security](https://docs.hitheo.ai/mcp/security.md): Threat model for @hitheo/mcp — what runs where, how the JSON-only sandbox protects you, and how to verify the supply chain.
- [Tools](https://docs.hitheo.ai/mcp/tools.md): Every MCP tool @hitheo/mcp exposes — schemas, examples, and the SDK/REST endpoint behind each one.
- [Troubleshooting](https://docs.hitheo.ai/mcp/troubleshooting.md): Common failures when running @hitheo/mcp inside an IDE, with log signatures and fixes.
- [Mode Selector](https://docs.hitheo.ai/playground/mode-selector.md): Choose execution modes in the Playground.
- [Playground Overview](https://docs.hitheo.ai/playground/overview.md): Interactive testing environment for the Theo API.
- [Skill Activation](https://docs.hitheo.ai/playground/skill-activation.md): Enable skills in the Playground.
- [Streaming & Artifacts](https://docs.hitheo.ai/playground/streaming-artifacts.md): Real-time streaming and artifact preview in the Playground.
- [Cross browser](https://docs.hitheo.ai/qa/cross-browser.md)
- [First Completion](https://docs.hitheo.ai/quickstart/first-completion.md): Make your first API call with curl and see the full response.
- [Get Your API Key](https://docs.hitheo.ai/quickstart/get-api-key.md): Create a Theo API key to start making requests.
- [Hello World](https://docs.hitheo.ai/quickstart/hello-world.md): Build a working example in under 5 minutes.
- [Install the SDK](https://docs.hitheo.ai/quickstart/install-sdk.md): Set up @hitheo/sdk for TypeScript and Node.js projects.
- [Audio (TTS / STT)](https://docs.hitheo.ai/sdk-reference/audio.md): Text-to-speech and speech-to-text via the SDK.
- [Theo Browser](https://docs.hitheo.ai/sdk-reference/browser.md): Managed headless browser sessions from the @hitheo/sdk. Create, inspect, refresh, embed, and end sessions with fully typed responses.
- [E.V.I. Canvas](https://docs.hitheo.ai/sdk-reference/canvases.md): Manage E.V.I. canvases programmatically — create, compile, test, and publish.
- [Theo Client](https://docs.hitheo.ai/sdk-reference/client.md): The main Theo class and all available methods.
- [Completions & Streaming](https://docs.hitheo.ai/sdk-reference/completions.md): Create completions and stream responses token-by-token.
- [Error Handling](https://docs.hitheo.ai/sdk-reference/error-handling.md): Handle API errors with TheoApiError.
- [E.V.I. (Embedded Virtual Intelligence)](https://docs.hitheo.ai/sdk-reference/evi.md): Create branded AI assistants with pre-configured persona, skills, and tools.
- [Installation & Setup](https://docs.hitheo.ai/sdk-reference/installation.md): Install @hitheo/sdk and configure the Theo client.
- [Images, Video, Code, Research, Documents](https://docs.hitheo.ai/sdk-reference/media.md): SDK methods for media generation and content creation.
- [Project Config (defineConfig)](https://docs.hitheo.ai/sdk-reference/project-config.md): Configure Theo for a project with typed settings.
- [Skills (defineSkill)](https://docs.hitheo.ai/sdk-reference/skills.md): Type-safe builder for creating Theo skill manifests.
- [TypeScript Types Reference](https://docs.hitheo.ai/sdk-reference/types.md): All exported types from @hitheo/sdk.
- [Workflows](https://docs.hitheo.ai/sdk-reference/workflows-channels.md): Schedule and trigger multi-step automations.
- [Audit Trail](https://docs.hitheo.ai/security/audit-trail.md): Immutable logging of all API activity.
- [Authentication](https://docs.hitheo.ai/security/authentication.md): API key security, dashboard auth, and best practices.
- [Data Privacy](https://docs.hitheo.ai/security/data-privacy.md): How Theo handles, stores, and protects your data.
- [Disclosure Policy](https://docs.hitheo.ai/security/disclosure-policy.md): How to report a security vulnerability and what happens next. All reports go to security@opencharts.com.
- [Rate Limiting](https://docs.hitheo.ai/security/rate-limiting.md): Request rate limits, tiers, spending caps, and how to handle 429 responses.
- [Building a Skill](https://docs.hitheo.ai/skills/building-a-skill.md): Step-by-step guide to creating a Theo skill with defineSkill().
- [Skill Manifest Reference](https://docs.hitheo.ai/skills/manifest-reference.md): Complete reference for theo-skill.json fields.
- [What Are Skills?](https://docs.hitheo.ai/skills/overview.md): Installable packages of domain knowledge and capabilities — like apps for AI.
- [Permissions](https://docs.hitheo.ai/skills/permissions.md): What skills can access and how permissions are enforced.
- [Publishing to the Marketplace](https://docs.hitheo.ai/skills/publishing.md): Submit skills for review and distribution.
- [Revenue Sharing](https://docs.hitheo.ai/skills/revenue-sharing.md): Earn credits when other developers use your skills.
- [Review Pipeline & Risk Tiers](https://docs.hitheo.ai/skills/review-pipeline.md): Automated and manual review for marketplace skills.
- [Skill Sandbox & Testing](https://docs.hitheo.ai/skills/sandbox-testing.md): Test skills in isolation before publishing.
- [Tool Definitions](https://docs.hitheo.ai/skills/tool-definitions.md): Define callable actions within a skill.
- [Triggers & Autonomous Execution](https://docs.hitheo.ai/skills/triggers-autonomous.md): How skills activate automatically.
- [401 Unauthorized](https://docs.hitheo.ai/troubleshooting/401-errors.md): Common causes of first-time 401 errors on the Theo API and how to fix them.