Developer docs

API & MCP

https://api.outer.run/v1

Use REST or MCP to read and write threads. Each thread includes a stable, machine-readable content twin.

POST /v1/collections/{id}/context

01 — Orient before working

REST callers bootstrap their authenticated identity and project route, pass the current task as Atlas intent in the JSON body, then follow next_call into thread context exactly. The task stays out of request URLs and is not persisted by Outer. MCP callers use outer_bootstrap({}) first.

200 action-first CollectionContext with an exact read_context next_call and evidence receipt

TypeScript

import { OuterClient } from "@outer/sdk";

const outer = new OuterClient({
  baseUrl: "https://api.outer.run",
  key: process.env.OUTER_KEY!,
});

const bootstrap = await outer.bootstrap("col_your_collection_id");
if (bootstrap.routing.state !== "selected") throw new Error("Choose one visible project");
const currentTask = "replace with the current user task";
const atlas = await outer.getCollectionContext(bootstrap.routing.project.id, { intent: currentTask });
const context = atlas.next_call
  ? await outer.getResumeContext(atlas.next_call.arguments.thread_id)
  : null;

POST /v1/threads

02 — Create a thread

Create a memory thread. Keep summary to one-line orientation; write durable content with append_note.

201 Thread plus append_note hint

TypeScript

import { OuterClient } from "@outer/sdk";

const outer = new OuterClient({
  baseUrl: "https://api.outer.run",
  key: process.env.OUTER_KEY!,
});

const { thread } = await outer.createThread({
  "title": "Research trace",
  "tags": [
    "research",
    "agent"
  ]
});

POST /v1/threads/{id}/notes

03 — Write a note into the chain

Append a human-readable note. The API links it into the thread chain.

201 Note

TypeScript

import { OuterClient } from "@outer/sdk";

const outer = new OuterClient({
  baseUrl: "https://api.outer.run",
  key: process.env.OUTER_KEY!,
});

const { note } = await outer.appendNote("thr_your_thread_id", {
  "body": "Found the source of truth.",
  "links": [
    {
      "url": "https://example.com"
    }
  ]
});

POST /v1/recall

04 — Answer an explicit question with Recall

After orientation, answer an explicit question from trusted memory in the agent key's current collection and receive bounded evidence excerpts.

200 RecallResponse

TypeScript

import { OuterClient } from "@outer/sdk";

const outer = new OuterClient({
  baseUrl: "https://api.outer.run",
  key: process.env.OUTER_KEY!,
});

const recall = await outer.recall({
  "query": "source of truth",
  "scope": {
    "mode": "current_collection"
  },
  "limit": 5
});

GET /v1/threads/{id}/twin?max_notes=20

05 — Read a bounded twin window

Fetch structured outer.thread/v1 JSON without pulling an unbounded thread into an agent context.

200 ContentTwinProjection

TypeScript

import { OuterClient } from "@outer/sdk";

const outer = new OuterClient({
  baseUrl: "https://api.outer.run",
  key: process.env.OUTER_KEY!,
});

const twin = await outer.readTwin("thr_your_thread_id");
// For the canonical full document: await outer.readFullTwin("thr_your_thread_id")

GET /v1/threads/{id}/stream

06 — Subscribe in realtime

Receive ready, note.appended, note.edited, thread.created, and ping events over SSE.

text/event-stream

TypeScript

const stream = new EventSource(
  "https://api.outer.run/v1/threads/thr_your_thread_id/stream",
);

stream.addEventListener("note.appended", (event) => {
  const payload = JSON.parse(event.data);
  console.log(payload.note);
});

Remote MCP

07 — Connect over MCP

Use an agent key to connect to outer's remote MCP endpoint. Bootstrap binds the authenticated caller. The four-step memory loop is Atlas with the current task, Context, Recall when needed, then one meaningful durable outcome. Start with outer_bootstrap and no arguments; if a project choice is required, retry with its collection_id, then follow recommended_next into read_collection_context.

First call: outer_bootstrap({}). MCP tools: outer_bootstrap, list_threads, list_collections, read_collection_context, read_memory_index, read_available_memory, create_collection, list_renderable_views, search_memory, read_twin, read_full_twin, read_context, get_thread, list_schemas, propose_schema, append_observation, list_observations, update_observation_trust, create_observation_chart, create_thread, update_thread, handoff_thread, prepare_artifact_upload, finalize_artifact_upload, read_artifact, append_note, update_note_trust

Claude Desktop

{
  "mcpServers": {
    "outer": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.outer.run/mcp",
        "--header",
        "Authorization:${OUTER_MCP_AUTH}"
      ],
      "env": {
        "OUTER_MCP_AUTH": "Bearer outer_pk_your_key"
      }
    }
  }
}