REST API | Spectron

Spectron exposes a REST API over HTTP from the api role. Every SDK and harness adapter maps to these endpoints, so you can integrate from any language that can make HTTP requests.

URL structure

One host (default port 9090) serves:

Path	Purpose
`/api/v1/{context_id}/...`	End-user operations — facts, documents, query, chat, sessions, traces
`/api/v1/contexts/...`	Management — Context lifecycle and key provisioning (management key)
`/api/v1/health`	Liveness
`/mcp`	MCP server (Streamable HTTP); same `API-KEY` auth

The {context_id} segment is the identifier you assigned at bootstrap (for example dev), not an opaque UUID unless you chose one.

Authentication

API-KEY: <api_key>

Do not use Authorization: Bearer. Management and end-user keys both use the same header name; the server infers capabilities from the key material.

Optional on writes:

Idempotency-Key: <stable-id>

The four verbs

Verb	Endpoint	When to use
Remember	`POST /api/v1/{ctx}/facts`, `POST .../facts/batch`	Conversations, single facts, harness batch capture
Upload	`POST /api/v1/{ctx}/documents`	PDFs, manuals, code, media
Recall	`POST /api/v1/{ctx}/query`	Ranked hits over the unified substrate
Chat	`POST /api/v1/{ctx}/chat`	Let Spectron run recall + synthesis

Formatted prompt text without raw hit lists: POST /api/v1/{ctx}/context.

Example: remember and recall

export SPECTRON_URL=http://localhost:9090
export SPECTRON_API_KEY=<context-key>
export SPECTRON_CONTEXT_ID=dev

curl -sS "$SPECTRON_URL/api/v1/$SPECTRON_CONTEXT_ID/facts" \
  -H "API-KEY: $SPECTRON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Alice was promoted to CTO.","infer":"full","scope":["org=acme","user=alice"]}'

curl -sS "$SPECTRON_URL/api/v1/$SPECTRON_CONTEXT_ID/query" \
  -H "API-KEY: $SPECTRON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"What is Alice'\''s role?","limit":10,"scope":["org=acme","user=alice"]}'

The spectron CLI wraps the same paths (spectron remember, spectron recall, spectron chat).

Full reference

Endpoint tables, session introspection routes, document APIs, traces, and scope/principal management are documented in REST API reference.