Installation & Setup - Theo API Docs

Install

npm install @hitheo/sdk

yarn add @hitheo/sdk

pnpm add @hitheo/sdk

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

Initialize

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

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 if you override baseUrl.

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 for the full list.

What’s new in 0.3.x – 0.4.0

@hitheo/sdk@0.4.0 adds programmatic per-key orchestration and account management — all additive, no breaking changes to existing completion/stream code:

theo.keys — create keys and configure their model plan, orchestrator graph, and skill allowlist from code.
theo.routingPreferences / theo.routingRules — author and bind keyword/regex routing.
theo.guardrails — manage Gateway Guardrails policies, presets, and per-key bindings.
theo.billingCheckout / theo.billingPortal — top up credits and open the billing portal.
The /v1/completions request gained a memory: false flag (skip long-term memory injection) and richer per-request fields — see Create Completion.

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.

​Install

​Initialize

​Configuration

​What’s Included

​What’s new in 0.3.x – 0.4.0

​Upgrading to 0.2.0

Install

Initialize

Configuration

What’s Included

What’s new in 0.3.x – 0.4.0

Upgrading to 0.2.0