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

# Installation & Setup

> Install @hitheo/sdk and configure the Theo client.

## Install

<CodeGroup>
  ```bash npm theme={null}
  npm install @hitheo/sdk
  ```

  ```bash yarn theme={null}
  yarn add @hitheo/sdk
  ```

  ```bash pnpm theme={null}
  pnpm add @hitheo/sdk
  ```
</CodeGroup>

**Requirements:** Node.js 18+ (native `fetch` required). Works in Node.js, Deno, Bun, and edge runtimes.

## Initialize

```typescript theme={null}
import { Theo } from "@hitheo/sdk";

const theo = new Theo({
  apiKey: process.env.THEO_API_KEY!,
});

// Sanity-check connectivity + auth in one call
const diagnostic = await theo.verify();
if (!diagnostic.authenticated) console.error(diagnostic.hint);
```

## Configuration

| Option                | Type     | Default                   | Description                                                                                                                           |
| --------------------- | -------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `apiKey`              | `string` | **required**              | Your `theo_sk_...` API key                                                                                                            |
| `baseUrl`             | `string` | `"https://www.hitheo.ai"` | API base URL (`www` host — see note below)                                                                                            |
| `timeoutMs`           | `number` | `30000`                   | Unary request timeout (ms); also the stream connect/first-byte budget. See [Timeouts & Retries](/sdk-reference/timeouts-and-retries). |
| `streamIdleTimeoutMs` | `number` | `120000`                  | Stream idle (between-chunks) timeout (ms). Not a total cap.                                                                           |
| `maxRetries`          | `number` | `2`                       | Retries on 429/5xx (exponential backoff). Timeouts are not retried on POSTs.                                                          |

<Warning>
  Always target the `www` host. The apex `https://hitheo.ai` 307-redirects to `https://www.hitheo.ai`, and most HTTP clients (including Node 18's built-in `fetch`) strip the `Authorization` header on 3xx responses — the redirected request arrives unauthenticated and returns `401`. The SDK defaults to `https://www.hitheo.ai` as of `@hitheo/sdk@0.2.0`. See [401 Troubleshooting](/troubleshooting/401-errors) if you override `baseUrl`.
</Warning>

## What's Included

The SDK exports:

| Export                                    | Type       | Description                                                                                                                                                                                                                                                                   |
| ----------------------------------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Theo`                                    | class      | Main client with all API methods                                                                                                                                                                                                                                              |
| `TheoStream`                              | class      | Returned by `theo.stream()` — async-iterable with `cancel()` and final metadata                                                                                                                                                                                               |
| `EviInstance`                             | class      | E.V.I. wrapper (created via `theo.evi()`)                                                                                                                                                                                                                                     |
| `TheoApiError`                            | class      | Base typed error with `status`, `body`, `url`, `kind`, and parsed `details`                                                                                                                                                                                                   |
| `TheoTimeoutError` / `TheoCancelledError` | class      | `TheoApiError` subclasses for timeouts (carries `timeoutMs`) and caller cancellation                                                                                                                                                                                          |
| `TheoUsageError`                          | class      | Thrown synchronously for SDK misuse (e.g. an async mode sent to `complete()`/`stream()`)                                                                                                                                                                                      |
| `defineSkill`                             | function   | Type-safe skill manifest builder                                                                                                                                                                                                                                              |
| `defineConfig`                            | function   | Type-safe project config builder                                                                                                                                                                                                                                              |
| All types                                 | interfaces | `CompletionRequest`, `CompletionResponse`, `StreamEvent`, `TheoStream`, `VerifyResult`, `ConversationSummary`, `SkillSummary`, `SdkToolDefinition`, `WorkflowRecord`, `WebhookRecord`, `HookRecord`, `UsageReport`, etc. See [Types](/sdk-reference/types) for the full list. |

## Upgrading to 0.2.0

If you're upgrading from `0.1.x`:

* **No code changes required** for typical `theo.complete()` / `theo.stream()` usage.
* If you pinned `baseUrl: "https://hitheo.ai"` explicitly, drop it (or switch to `"https://www.hitheo.ai"`) to pick up the new default and avoid header-stripping redirects.
* `theo.stream()` now returns a `TheoStream`. `for await` still works; you additionally gain `.cancel()` and post-completion metadata (`conversationId`, `usage`, `requestId`).
* `CompletionResponse.usage` now includes `prompt_tokens`, `completion_tokens`, `total_tokens`, and an optional `cached` boolean. Existing `res.usage.cost_cents` usage keeps working.
* List methods that used to return `Promise<unknown[]>` (`conversations`, `skills`, `tools`, `workflows`, `submissions`, etc.) now return typed records — remove any `as any` casts.
  Full release notes: [Changelog](/changelog).