Optimal Engine API reference

The Engine has about 300 routes. This page covers the ones most apps and agents use. The complete list, with the grant each route needs, is generated from the router into docs/reference/api.md, and a test fails whenever the two disagree.

E=http://127.0.0.1:4200
K="Authorization: Bearer $OPTIMAL_ENGINE_API_KEY"

Keys and errors

When OPTIMAL_AUTH_REQUIRED=true, every route needs a key, including /api/health.

Rate limits

Each key has its own budget per minute, set by the size profile: 1,200 requests a minute on the default business profile. Requests without a valid key share their IP address’s budget. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. /api/health, /api/status, and /api/metrics/prometheus are not counted.

Paging

List routes take offset and limit (1 to 200, default 50) and answer with:

"pagination": {"offset": 0, "limit": 50, "total": 132, "has_more": true}

Engine

Workspaces and nodes

Create a workspace

POST /api/workspaces

curl -s -X POST $E/api/workspaces -H "$K" -H "Content-Type: application/json" 
  -d '{"slug": "sales", "name": "Sales"}'

201 returns the workspace: id (default:sales), tenant_id, slug, name, status, created_at. Errors: 400 for a missing or invalid slug or name, 409 slug_taken, 409 external_id_taken.

Create a node

POST /api/nodes with {"name", "kind", "slug", "workspace", "description"} answers {"ok": true, "id", "slug", "kind"}. kind is one of the node kinds in Concepts.

Ingest

POST /api/ingest stores text as a source. See Sources and ingestion for the fields, files, chat sessions, Notion, and connectors.

curl -s -X POST $E/api/ingest -H "$K" -H "Content-Type: application/json" 
  -d '{"workspace": "default:sales", "title": "Auth decision", "text": "Decided: refresh-token rotation ships in v2."}'

{"ok": true, "signal_id": "...", "genre": "...", "type": "...", "entities": [], "source_package_id": "..."}

Search

GET /api/search?q=&workspace=&limit=&offset=&mode=&type=&as_of=

curl -s "$E/api/search?q=refresh%20token&workspace=default:sales&limit=5" -H "$K"

{
  "query": "refresh token",
  "results": [
    {
      "id": "...",
      "title": "Auth decision",
      "uri": "optimal://...",
      "content": "Decided: refresh-token rotation ships in v2.",
      "l0_abstract": "...",
      "score": 0.82,
      "workspace_id": "default:sales",
      "inherited": false
    }
  ],
  "pagination": {"offset": 0, "limit": 5, "total": 1, "has_more": false}
}

mode=hybrid answers 503 hybrid_unavailable when no embedding model answers. A bad as_of answers 400.

Ask and assemble

POST /api/rag returns context for one question; GET /api/rag/stream streams it as server-sent events. POST /api/assemble returns a tiered context package for an agent. See Memory and retrieval for fields and responses.

curl -s -X POST $E/api/rag -H "$K" -H "Content-Type: application/json" 
  -d '{"query": "What did we decide about auth?", "workspace": "default:sales", "format": "markdown", "bandwidth": "small"}'

curl -N "$E/api/rag/stream?query=auth%20decision&workspace=default:sales" -H "$K"

Memory

Claims

Chat sessions

Operations

These need an admin key.