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

# Theo Client

> The main Theo class and all available methods.

The `Theo` class is the entry point for all API interactions.

## Constructor

```typescript theme={null}
import { Theo } from "@hitheo/sdk";
const theo = new Theo({ apiKey: "theo_sk_..." });
```

The default `baseUrl` is `https://www.hitheo.ai` (the canonical `www` host). Timeout and retry behavior (`timeoutMs`, `streamIdleTimeoutMs`, `maxRetries`) is covered in [Timeouts & Retries](/sdk-reference/timeouts-and-retries); see [Installation & Setup](/sdk-reference/installation) 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`). |

<Note>
  `complete()` / `stream()` reject `mode: "research"` and `mode: "video"` with a `TheoUsageError` — those are asynchronous. Use `theo.research()` / `theo.video()` + `theo.waitForJob()`; see [Async Jobs](/guides/async-jobs).
</Note>

### 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`](/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`](/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        |