Theo class is the entry point for all API interactions.
Constructor
import { Theo } from "@hitheo/sdk";
const theo = new Theo({ apiKey: "theo_sk_..." });
baseUrl is https://www.hitheo.ai (the canonical www host). Timeout and retry behavior (timeoutMs, streamIdleTimeoutMs, maxRetries) is covered in Timeouts & Retries; see Installation & Setup for every config option.
Methods
Completions
| Method | Returns | Description |
|---|---|---|
theo.complete(request) | Promise<CompletionResponse> | Run a completion (non-streaming). Response includes usage with full token counts, request_id, and conversation_id. |
theo.stream(request) | TheoStream | Stream a completion via SSE. Async-iterable handle with cancel() plus final metadata (conversationId, usage, model, requestId). |
complete() / stream() reject mode: "research" and mode: "video" with a TheoUsageError — those are asynchronous. Use theo.research() / theo.video() + theo.waitForJob(); see Async Jobs.First-Run Diagnostic
| Method | Returns | Description |
|---|---|---|
theo.verify() | Promise<VerifyResult> | Probes /health + /models and returns { healthy, authenticated, baseUrl, latencyMs, modelCount?, version?, error?, hint? }. Use this as the first line of debugging. |
Media & Content
| Method | Returns | Description |
|---|---|---|
theo.images(request) | Promise<ImageResponse> | Generate images |
theo.video(request) | Promise<AsyncJobResponse> | Generate video (async — poll with waitForJob) |
theo.code(request) | Promise<CodeResponse> | Generate code |
theo.research(request) | Promise<AsyncJobResponse> | Run research (async — poll with waitForJob) |
theo.documents(request) | Promise<DocumentResponse> | Generate documents (PDF, DOCX, etc.) |
Audio
| Method | Returns | Description |
|---|---|---|
theo.tts(request) | Promise<ArrayBuffer> | Text-to-speech (returns audio bytes) |
theo.stt(file, language?) | Promise<SttResponse> | Speech-to-text (accepts Blob/File) |
Skills
| Method | Returns | Description |
|---|---|---|
theo.skills(filter?) | Promise<SkillSummary[]> | List skills ("installed" or "marketplace") |
theo.installSkill(id) | Promise<void> | Install a marketplace skill |
theo.uninstallSkill(id) | Promise<void> | Uninstall a skill |
theo.createSkill(input) | Promise<SkillSummary> | Create a custom skill |
theo.submitSkill(manifest) | Promise<SubmissionRecord> | Submit for marketplace review |
theo.submissions(status?) | Promise<SubmissionRecord[]> | List your submissions |
theo.skillVersions(id) | Promise<SkillVersion[]> | Get version history |
Workflows
| Method | Returns | Description |
|---|---|---|
theo.workflows() | Promise<WorkflowRecord[]> | List workflows |
theo.createWorkflow(input) | Promise<WorkflowRecord> | Create a workflow |
theo.triggerWorkflow(id, data?) | Promise<WorkflowRunRecord> | Trigger a workflow run |
Resources
| Method | Returns | Description |
|---|---|---|
theo.models() | Promise<ModelInfo[]> | List available models |
theo.tools() | Promise<SdkToolDefinition[]> | List available tools |
theo.conversations() | Promise<ConversationSummary[]> | List conversations |
theo.conversation(id) | Promise<ConversationDetail> | Get a specific conversation |
theo.usage(params?) | Promise<UsageReport> | Get usage data |
theo.health() | Promise<HealthResponse> | Check system health |
Jobs
| Method | Returns | Description |
|---|---|---|
theo.job<T>(jobId) | Promise<JobStatus<T>> | Get job status (typed result via T) |
theo.waitForJob<T>(jobId, options?) | Promise<JobStatus<T>> | Poll until complete/failed. Options: { intervalMs, maxWaitMs, signal, onProgress }. Legacy positional (id, interval?, maxWait?) still works. |
E.V.I.
| Method | Returns | Description |
|---|---|---|
theo.evi(config) | EviInstance | Create an E.V.I. instance |
E.V.I. Canvas
Full reference:sdk-reference/canvases.
| Method | Returns | Description |
|---|---|---|
theo.canvases() | Promise<CanvasRecord[]> | List the authenticated user’s canvases |
theo.canvas(id) | Promise<CanvasRecord> | Get a single canvas |
theo.createCanvas(input) | Promise<CanvasRecord> | Create a canvas |
theo.updateCanvas(id, input) | Promise<CanvasRecord> | Update a canvas |
theo.deleteCanvas(id) | Promise<void> | Delete a canvas |
theo.compileCanvas(id) | Promise<CanvasCompileResult> | Compile into SkillManifest + WorkflowSteps |
theo.testCanvas(id, message, history?) | Promise<CanvasTestResult> | Sandbox test message |
theo.publishCanvas(id, opts) | Promise<CanvasPublishResult> | Publish (private/org/public) |
Webhooks
| Method | Returns | Description |
|---|---|---|
theo.listWebhooks() | Promise<WebhookRecord[]> | List org webhooks |
theo.createWebhook(input) | Promise<WebhookRecord> | Create a webhook (returns signing_secret once) |
theo.updateWebhook(id, input) | Promise<void> | Update URL / events / enabled / description |
theo.deleteWebhook(id) | Promise<void> | Delete a webhook |
theo.testWebhook(id) | Promise<void> | Send a test event |
theo.webhookDeliveries(id) | Promise<WebhookDelivery[]> | Recent delivery attempts |
Hooks
| Method | Returns | Description |
|---|---|---|
theo.listHooks() | Promise<HookRecord[]> | List installed hooks |
theo.createHook(input) | Promise<HookRecord> | Install a hook (preset or custom event_pattern) |
theo.updateHook(id, input) | Promise<void> | Update config / enabled / cooldown |
theo.deleteHook(id) | Promise<void> | Delete a hook |
theo.hookExecutions(id) | Promise<HookExecution[]> | Execution history for a hook |
Events
| Method | Returns | Description |
|---|---|---|
theo.publishEvent(input) | Promise<EventAck> | Publish a domain event (triggers matching hooks + webhooks) |
Theo Browser
Full reference:sdk-reference/browser.
| Method | Returns | Description |
|---|---|---|
theo.browser.create(req?) | Promise<BrowserSessionHandle> | Start a managed browser session |
theo.browser.list() | Promise<BrowserSessionSnapshot[]> | List active sessions |
theo.browser.get(id) | Promise<BrowserSessionSnapshot> | Get a session snapshot |
theo.browser.live(id, opts?) | Promise<BrowserLiveView> | Refresh the live-view URL |
theo.browser.end(id) | Promise<BrowserEndResult> | End the session and bill |