Substrate API

The substrate is a per-account knowledge graph. Every node has a stable id, a type, a body, and an audit trail. Edges express provenance and reference. The API lets you read, write, query, and stream changes.

Base URL

https://api.odahl.ai/v1

Authentication

All requests require a bearer token issued from /api/auth/token or an authenticated session cookie. See auth.

List nodes

GET /substrate/nodes?type=decision&limit=50
Authorization: Bearer <token>

Returns a paginated array of nodes filtered by type, tag, or updated_since.

Create a node

POST /substrate/nodes
Content-Type: application/json

{
  "type": "decision",
  "body": "Use Cardinal for retro summaries",
  "tags": ["workflow", "retro"]
}

Query

Semantic query joins vector and graph reach in a single call. Use k to limit results and depth to control graph expansion.

POST /substrate/query
{ "q": "retro decisions in May", "k": 8, "depth": 2 }

Stream changes

Open a server-sent events connection to /substrate/stream to receive node-mutation events as they happen.

Errors

401 — missing or invalid token
403 — token lacks the requested scope
429 — rate limit (default 600 req/min)

← Back to docs