Skip to main content

​
Install

npm install @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

OptionTypeDefaultDescription
apiKeystringrequiredYour theo_sk_... API key
baseUrlstring"https://www.hitheo.ai"API base URL (www host — see note below)
timeoutMsnumber30000Unary request timeout (ms); also the stream connect/first-byte budget. See Timeouts & Retries.
streamIdleTimeoutMsnumber120000Stream idle (between-chunks) timeout (ms). Not a total cap.
maxRetriesnumber2Retries 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:
ExportTypeDescription
TheoclassMain client with all API methods
TheoStreamclassReturned by theo.stream() — async-iterable with cancel() and final metadata
EviInstanceclassE.V.I. wrapper (created via theo.evi())
TheoApiErrorclassBase typed error with status, body, url, kind, and parsed details
TheoTimeoutError / TheoCancelledErrorclassTheoApiError subclasses for timeouts (carries timeoutMs) and caller cancellation
TheoUsageErrorclassThrown synchronously for SDK misuse (e.g. an async mode sent to complete()/stream())
defineSkillfunctionType-safe skill manifest builder
defineConfigfunctionType-safe project config builder
All typesinterfacesCompletionRequest, CompletionResponse, StreamEvent, TheoStream, VerifyResult, ConversationSummary, SkillSummary, SdkToolDefinition, WorkflowRecord, WebhookRecord, HookRecord, UsageReport, etc. See 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.