theofor developers07 / integration notes

From “make this work”
to “I know how it works.”

Build with your coding assistant or take direct control of the API. One release assistant shows how a useful result becomes a workflow with your expertise, relevant context, and explicit boundaries.

choose how you build go straight to the contracts

THE SAME IDEA / TWO ENTRY POINTS

“Help me build a release assistant.”

A reviewable plan, a connected diagram, and a prompt for your coding assistant.

“Show me the request contract.”

A server-side call, explicit capabilities, and an inspectable response.

Start small. See the connections. Keep control.

01one assistant, built in layers

Choose your starting point. Keep the same goal.

Turn release notes into a draft. Add the team’s expertise, continue with supported memory, then inspect the result. Switching paths keeps your place.

One release assistant. Two ways in.

Authored example · local only

Describe the idea. See how the pieces connect.

Developer stage

Turn release notes into a useful draft.

Start with one small feature, not a collection of model integrations.

Build with AI

Proposed orchestration

Fictional release notesNotesRetry test pending · review open
theo · auto routetheoEligible capability + configured context
A draft for reviewDraftNo release approval or deployment

How the pieces connect

Your coding assistant can help propose the connections. This drawing does not create an orchestrator or apply account configuration.

Authored draft · not live

Draft: the retry test is pending and rollback review remains open.

Get the task prompt

A task for your coding assistant

Help me build a release assistant. It should turn approved notes into a draft, leave missing checks visible, and never approve or deploy a release. Show me the proposed route before changing any configuration.

Connect the documented MCP server in your own editor. Configuration-changing tools need the appropriate scope and your approval; nothing is connected here.

Only copies text. Does not run or configure anything.

Fictional example. No live requests or configuration changes. Switching paths keeps your place.

Connect your coding assistant

Start with MCP setup. Use E.V.I. Canvas to build a skill, not as another name for the orchestrator.

Read both paths without the interactive controls

Fictional inputs and authored outputs. No live inference, configuration changes, key collection, or persistent memory.

Build with AI · for vibe coders

Connect the MCP server using the documented setup, then ask your coding assistant to propose a workflow. Execution tools and configuration tools have different permissions. Review configuration changes before applying them.

First useful result: Help me build a release assistant. It should turn approved notes into a draft, leave missing checks visible, and never approve or deploy a release. Show me the proposed route before changing any configuration.

Illustrated result: Draft: the retry test is pending and rollback review remains open.

Add your expertise: Help me design a release-brief skill: concise summaries, approved release notes, and a read-only checklist lookup. Show the required tool handler and permissions. Do not install or change anything without my approval.

Illustrated result: Team brief: keep the known notes separate from open checks. Reviewer sign-off is still required.

Keep the context: Resume the release draft from last week. Use only the relevant context available to this owner, keep the open checks visible, and ask if a source is missing. Help me verify which memory features are enabled.

Illustrated result: Continued draft: the earlier review requirement still applies. Nothing records that the checks are complete.

Take control: Walk me through this release assistant’s routing, skill permissions, and bound policies. Show how to inspect the request ID and handle missing context or failed tools. Propose changes for review, but do not apply them.

Illustrated result: Before approval: confirm the retry test, rollback review, and reviewer sign-off.

Engineer the system · for advanced developers

Call the SDK or REST API from your server. Add a created, authorized skill through skills[]. Check supported memory paths; do not invent a memory flag. Inspect request_id, resolved_mode, and tool activity, then test failures before deployment.

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

// Server-side only. Supply the value through your secret store.
const apiKey = process.env.THEO_API_KEY;
if (!apiKey) {
  throw new Error("Set THEO_API_KEY in the server environment.");
}

const theo = new Theo({
  apiKey,
  timeoutMs: 30_000,
  maxRetries: 2,
});

const response = await theo.complete({
  prompt: "Prepare a release brief from these fictional notes: the retry test is pending and rollback review is still open.",
  mode: "auto",
});

console.log(response.content);

The same request over REST

curl https://www.hitheo.ai/api/v1/completions \
  -H "Authorization: Bearer $THEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "prompt": "Prepare a release brief from these fictional notes: the retry test is pending and rollback review is still open.",
  "mode": "auto"
}'

MCP setup documentation (opens in a new tab) · Completion API documentation (opens in a new tab)

02different tools, clear jobs

The toolkit should fit how you build.

Plan with your AI editor

MCP connects a coding assistant to documented execution and configuration tools. Propose the workflow first; verify scope and approve any account changes.

connect with MCP

Package the expertise

E.V.I. Canvas builds a skill from instructions, knowledge, and permitted tools. A skill graph is not the orchestrator that coordinates the larger workflow.

build a skill visually

Own the application

SDK and REST expose the request contract. Choose routes, attach authorized skills, inspect results, and keep identity and release approval in your system.

use the server SDK

03go deeper when you need to

Production control, one boundary at a time.

The useful details belong next to the decision they support. Open the contract you need; every example remains readable without JavaScript.

Server setup & first completion

In a Node.js application, install the documented SDK. Provide THEO_API_KEY through your server’s environment or secret store, save the example as first-completion.mjs, and run it with Node. Do not place the key in a browser bundle.

Install in your own applicationexample

npm install @hitheo/sdk

The SDK docs require Node.js 18 or later with native fetch. This marketing site does not install or execute the SDK.

first-completion.mjs · server-side JavaScriptexample

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

// Server-side only. Supply the value through your secret store.
const apiKey = process.env.THEO_API_KEY;
if (!apiKey) {
  throw new Error("Set THEO_API_KEY in the server environment.");
}

const theo = new Theo({
  apiKey,
  timeoutMs: 30_000,
  maxRetries: 2,
});

const response = await theo.complete({
  prompt: "Prepare a release brief from these fictional notes: the retry test is pending and rollback review is still open.",
  mode: "auto",
});

console.log(response.content);

Documented SDK initialization and complete() request shape. Run with node first-completion.mjs after configuring the environment. This sends a real request only when you run it in your own application.

Start without a custom route.

mode: "auto" asks theo to resolve the execution mode. The requested mode and resolved mode are separate fields, so inspect the response rather than assuming which capability ran.

The SDK supplies its documented canonical API base by default. Avoid casually overriding the host: authentication headers can be lost across redirects.

The request uses prompt, not a chat-message array. Keep the endpoint’s request and response format together when moving between integrations.

Response fields, routing & diagnostics

Illustrative response · selected fieldsexample

{
  "request_id": "req_release_demo",
  "mode": "auto",
  "resolved_mode": "fast",
  "model": {
    "id": "theo-1-flash",
    "label": "Theo Flash",
    "engine": "theo-core"
  },
  "tools_used": [],
  "artifacts": [],
  "conversation_id": null,
  "content": "The release is still a draft. Confirm the retry test, rollback review, and reviewer sign-off."
}

Authored response matching the documented completion shape. It is not a captured result. Timestamps, usage, and other fields are omitted; no cost, token count, or quality measurement is implied.

content: The generated text. Validate it for your application’s task instead of treating fluent wording as verification.
mode / resolved_mode: What the caller requested and what the request resolved to. The example shows auto becoming fast; that result is illustrative.
model: The Theo-branded capability and engine that handled the response. This specimen uses theo-1-flash and theo-core.
tools_used / artifacts: Reported tool activity and generated artifacts. Empty arrays mean this example has neither; tool definitions alone are not evidence of a successful call.
conversation_id: The documented top-level conversation identifier can be null. Associate a returned ID with the authorized caller before using it to continue a thread. This links one thread; it is not the cross-thread MCIR memory mechanism.
request_id: A correlation identifier for support and diagnostics. Keep it without casually logging full prompts, sensitive output, or API keys.

Memory, identity & thread continuity

Memory, without a second integration: No separate memory API is required for supported integrations. Ordinary recall is distinct from the full MCIR intent-and-context pipeline, which has activation and caller-eligibility requirements.
Applications and agents: Supported API paths and authenticated MCP adapters can use owner-scoped context. An adapter connects to theo; it does not create a separate memory backend or enable every gated memory feature.
Your orchestration: Choose models for each role and package behavior in skills. A model-independent context handoff can supply relevant history, not a guarantee of identical answers. Memory is built into supported theo request paths. The full MCIR intent pipeline and Memory Chain have separate activation requirements; confirm availability for your account.

Skills & tool contracts

A tool definition is not its implementation. Add capabilities deliberately and keep the runtime permissions explicit.

A tools[] entry · read-only operationexample

{
  "name": "lookup_release_checklist",
  "description": "Read the approved checklist for a release. This operation does not approve or deploy a release.",
  "input_schema": {
    "type": "object",
    "properties": {
      "release_id": {
        "type": "string",
        "description": "The release identifier visible to the authenticated caller."
      }
    },
    "required": [
      "release_id"
    ],
    "additionalProperties": false
  }
}

An illustrative tool definition using the documented name, description, and input_schema fields. Pass supported definitions in tools[] only after implementing and authorizing the corresponding operation.

The custom-tool guide documents the callable schema. The model uses the description to decide whether to request the tool. It does not create a secure backend handler from that description.

Validate arguments against the schema and the authenticated caller’s permissions.
Scope lookups to records the caller can access, even when an identifier looks valid.
Handle unavailable services, empty results, and malformed tool output.
Require application-level human review for consequential writes or external actions.

Skills can supply domain instructions and tools. Pass documented skill slugs in skills[]; review how per-request skills combine with installed skills instead of assuming a request starts with no other capabilities.

build and test your own skill package

Errors, retries, streaming & policy boundaries

400: validation_errorCorrect the request body, mode, or missing prompt. Repeating an invalid request does not repair it.
401 / 403: Authentication or scopeCheck the configured key, its current status, the canonical host, and required scopes. Do not expose the credential in diagnostics.
402: insufficient_creditsSurface an account funding issue separately from a model or application failure.
404: not_foundA referenced conversation may not be available. Do not substitute another user’s thread or silently bypass authorization.
422: guardrail_violationA bound input policy denied the request. Treat this as an explicit outcome, not a reason to retry with enforcement removed.
429 / 5xx: Rate limit or server failureThe SDK documents bounded retries for these responses and respects Retry-After on rate limits. Coordinate retry budgets with your own application.

Before production, test timeouts, aborted streams, empty results, policy denials, and tool failures. Keep request correlation separate from sensitive payload logging.

04a practical order of work

A first result is the beginning.

01
Establish server authentication
Make a synthetic completion with a scoped server-side key. Verify that no key or privileged request crosses into the browser.
02
Inspect state and routing
Read resolved_mode and request_id. Verify the caller’s memory scope and enabled features. Associate a conversation_id with that caller to continue a specific thread; cross-thread memory is a separate mechanism.
03
Add the smallest capability
Introduce one skill or a read-only tool, validate its input and failure behavior, and test the combined configuration.
04
Bind and verify policies
If Gateway Guardrails are required, create and test the policy, bind the key, then verify input and output behavior. Keep a separate application review step.

No live requests run on this page. The code is a documented integration starting point; the sample response and tool operation are illustrative, not evidence of a deployed customer integration.

your next experiment

Your idea. Your level of control.

Start with a coding assistant or the server SDK. Verify one bounded workflow with synthetic data before expanding its access or responsibility.

start with your coding assistant start with the SDK & API