Skip to main content

​
Installation

npm install @hitheo/sdk
Requirements: Node.js 18+ with native fetch support.

​
Initialize the Client

import { Theo } from "@hitheo/sdk";

const theo = new Theo({
  apiKey: process.env.THEO_API_KEY!,
  // Optional:
  // baseUrl: "https://www.hitheo.ai",   // default (canonical `www` host)
  // timeoutMs: 30_000,                  // default
  // maxRetries: 2,                      // default — retries on 429/5xx
});

​
Configuration Options

OptionTypeDefaultDescription
apiKeystringrequiredYour theo_sk_... API key
baseUrlstringhttps://www.hitheo.aiAPI base URL (always target www — the apex redirects and some HTTP clients strip the Authorization header on 3xx)
timeoutMsnumber30000Request timeout in milliseconds
maxRetriesnumber2Max retry attempts on 429/5xx errors

​
Retry Behavior

The SDK automatically retries on:
  • 429 Too Many Requests — respects the Retry-After header
  • 5xx Server Errors — exponential backoff (1s, 2s, 4s, max 8s)
Client errors (400, 401, 403, 404) are not retried.

​
Also Available

​
CLI

The SDK includes a CLI for terminal usage: 
npm install -g @hitheo/sdk
theo init        # Set up Theo in a project
theo status      # Check connection + health (probes both apex and www)
theo verify      # Machine-readable JSON diagnostic (CI-friendly)
theo complete "What is quantum computing?"
See the CLI Reference for all commands.

​
MCP Server — IDE Integration

Use Theo inside Cursor, Claude Code, Warp, Windsurf, and VS Code via MCP: First, set your API key as an environment variable: 
export THEO_API_KEY=theo_sk_...
Then pick your IDE:
Add to .cursor/mcp.json in your project root:
{
  "mcpServers": {
    "theo": {
      "command": "npx",
      "args": ["-y", "@hitheo/mcp"],
      "env": {
        "THEO_API_KEY": "${env:THEO_API_KEY}"
      }
    }
  }
}
Or run:
theo mcp install --ide cursor
Restart your IDE after adding the config.