Keys - Theo API Docs

The theo.keys namespace creates API keys and shapes their per-key orchestration programmatically: the model plan, the orchestrator graph, the skill allowlist, the routing preference, and the guardrail policy. It’s the SDK surface behind the dashboard’s Orchestrator and behind the MCP configuration tools.

Every method here requires the calling key to hold the billing scope (key creation and per-key configuration are account-management operations). Whatever you configure applies to that key on both the native /v1/completions and the OpenAI-compatible /v1/chat/completions endpoints.

Engine ids used below are the real upstream ids (this is a configuration surface): arca-velox-5.1 (fast), arca-magnus-5.1 (deep reasoning), anthropic/claude-sonnet-4.6, anthropic/claude-opus-4.8, anthropic/claude-haiku-4.5, google/gemini-2.5-pro, openai/gpt-4.1, plus your own custom:<providerId>:<model>.

`keys.create`

Create a new API key. The raw secret is returned once — store it immediately.

const created = await theo.keys.create({
  name: "coding backend",
  scopes: ["completions", "skills", "tools"], // optional; defaults applied server-side
  scope: "personal",                           // or "org" (+ org_id) for a team key
});
console.log(created.key);   // theo_sk_… (shown once)
console.log(created.id);    // the key UUID — use it for the calls below

Field	Type	Notes
`name`	`string`	Optional label.
`scopes`	`("completions" \| "skills" \| "tools" \| "connectors" \| "billing")[]`	Optional scope set.
`scope`	`"personal" \| "org"`	`org` creates a team key (requires `org_id`).
`org_id`	`string`	Target org for a team key.

Returns CreatedApiKey ({ id, key, name, scopes, … }).

`keys.getModelPlan` / `keys.setModelPlan`

The model plan is the simplest way to control which engine a key runs. single_model pins one engine for every text turn — a deterministic passthrough that skips the classifier (ideal for coding / IDE backends, including a custom: BYO model). bindings instead remap individual modes.

// Pin one engine for everything (deterministic passthrough):
await theo.keys.setModelPlan(created.id, {
  single_model: { upstream_id: "anthropic/claude-opus-4.8" },
});

// Or remap per mode (classifier still routes; each mode's engine is pinned):
await theo.keys.setModelPlan(created.id, {
  bindings: [
    { mode: "fast",  upstream_id: "arca-velox-5.1" },
    { mode: "think", upstream_id: "arca-magnus-5.1" },
  ],
});

// Clear the single-model pin:
await theo.keys.setModelPlan(created.id, { single_model: null });

const plan = await theo.keys.getModelPlan(created.id); // KeyModelPlan

Each binding accepts an optional fallback_upstream_id used if the primary engine is unavailable.

`keys.getOrchestratorGraph` / `keys.setOrchestratorGraph`

For full control, set a runnable orchestrator graph — Entry → Classifier / Router → Model → Guardrail. An enabled graph must have an entry node and at least one model node with an engine.

await theo.keys.setOrchestratorGraph(created.id, {
  enabled: true,
  nodes: [
    { id: "entry", type: "entry", position: { x: 0, y: 0 }, config: { label: "User Prompt" } },
    { id: "classifier", type: "classifier", position: { x: 300, y: 0 }, config: { label: "Classifier" } },
    { id: "m_fast", type: "model", position: { x: 640, y: -80 }, config: { upstreamId: "arca-velox-5.1", label: "fast" } },
    { id: "m_think", type: "model", position: { x: 640, y: 80 }, config: { upstreamId: "arca-magnus-5.1", label: "think" } },
  ],
  edges: [
    { id: "e_in", source: "entry", target: "classifier" },
    { id: "e_fast", source: "classifier", target: "m_fast", modes: ["fast"] },
    { id: "e_think", source: "classifier", target: "m_think", modes: ["think"] },
  ],
});

const { graph } = await theo.keys.getOrchestratorGraph(created.id); // graph is null when none is set

Guardrail nodes (type: "guardrail", config.guardrailPolicyId) placed before the model screen the prompt (input); placed after it, they screen the reply (output). Router nodes apply the key’s bound routing preference.

`keys.getSkills` / `keys.setSkills`

Set the key’s skill allowlist. Each binding grants one skill; an optional mode scopes it to a single mode (omit / null = all modes).

await theo.keys.setSkills(created.id, [
  { skill_id: "sk_deep_research", mode: "think" },
  { skill_id: "sk_content_writer" },
]);

const { bindings } = await theo.keys.getSkills(created.id);

An empty allowlist means inherit-all (the key can call any skill the owner has installed).

Routing & guardrails

Two more binders live on keys and are documented alongside their feature pages:

keys.getRoutingPreference / keys.setRoutingPreference — bind a Routing Studio preference (keyword/regex → mode). See Routing Studio.
keys.getGuardrailPolicy / keys.setGuardrailPolicy — bind a Gateway Guardrails policy. See Guardrails.

Bring your own models

Register your own OpenAI-compatible endpoint, then reference it by its custom:<providerId>:<model> id in setModelPlan (single_model) or on a graph Model node. You can declare each model’s context window so oversize requests are caught before they reach your endpoint. See the changelog and the custom providers REST endpoint. Prompts to your own models are free and never draw credits.

Billing helpers

Top up credits or open the billing portal from code (top-level, not under keys):

const { checkout_url } = await theo.billingCheckout({ amount_cents: 2000, scope: "personal" });
const { portal_url } = await theo.billingPortal();

scope: "org" funds / manages the team credit pool.

​keys.create

​keys.getModelPlan / keys.setModelPlan

​keys.getOrchestratorGraph / keys.setOrchestratorGraph

​keys.getSkills / keys.setSkills

​Routing & guardrails

​Bring your own models

​Billing helpers

`keys.create`

`keys.getModelPlan` / `keys.setModelPlan`

`keys.getOrchestratorGraph` / `keys.setOrchestratorGraph`

`keys.getSkills` / `keys.setSkills`

Routing & guardrails

Bring your own models

Billing helpers