API Reference
What this page covers
The Stigmem reference node exposes a REST API owned by
Spec-03-HTTP-API, with endpoint semantics split across the
component specs listed below. The interactive API reference is
auto-generated from the OpenAPI schema served at
http://localhost:8000/openapi.json.
Endpoint groups
/v1/facts/v1/federation/*/v1/conflicts/v1/gardens/*/v1/lint/v1/decay/sweep/v1/synthesis/v1/auth/keys/*/v1/auth/audit/v1/admin/billing/events/v1/jobs/:id/v1/me/.well-known/stigmem/healthz/v1/recall/v1/cards/*/v1/graph/*/v1/facts/:id/provenance/v1/agents/:id/instruction-manifestGraph and recall endpoints
GET /v1/recall · POST /v1/recall
Returns a token-budget-bounded, salience-ranked slice of the fact store relevant to a natural-language or structured query. Uses a three-stage hybrid pipeline: lexical (FTS5/BM25), dense vector (ANN via sqlite-vec), and graph expansion (BFS on entity_edges). Results are packed with Maximal Marginal Relevance (MMR).
POST is preferred when query exceeds 1000 characters.
Key parameters:
querytoken_budgetdepthweightsentityrelationscopelambda_mmrmin_confidenceforce_refreshinclude_contradictedExample — open-ended query:
curl -s -X POST http://localhost:8000/v1/recall \
-H 'Authorization: Bearer <api-key>' \
-H 'Content-Type: application/json' \
-d '{
"query": "what is the current project status for phase 9?",
"token_budget": 2000,
"depth": 1
}'
Example — entity-centric query (card-first):
curl -s "http://localhost:8000/v1/recall?entity=stigmem%3A%2F%2Fcompany.example%2Fagent%2Fcto&token_budget=1500" \
-H 'Authorization: Bearer <api-key>'
GET /v1/cards/{entity_uri}
Fetch (and optionally force-refresh) the synthesized memory card for a specific entity. Returns 404 when the entity has no live facts.
Memory cards are pre-aggregated summaries.
Marked stale on every assert_fact call and refreshed on the next
read. When a fresh card is available during POST /v1/recall, the
recall pipeline uses it as a single synthetic fact instead of
re-ranking all raw facts for that entity.
Path parameter: entity_uri — URL-encoded entity URI.
Query parameters:
scoperefreshAuth: read permission required.
# Fetch card (auto-refreshes if stale)
curl -s "http://localhost:8000/v1/cards/stigmem%3A%2F%2Fcompany.example%2Fuser%2Falice?scope=local" \
-H 'Authorization: Bearer <api-key>'
# Force refresh
curl -s "http://localhost:8000/v1/cards/stigmem%3A%2F%2Fcompany.example%2Fuser%2Falice?scope=local&refresh=true" \
-H 'Authorization: Bearer <api-key>'
Error responses:
scope value or malformed entity_uri.GET /v1/graph/neighbors
Returns the graph neighbors of one or more seed entities by traversing the materialized entity_edges adjacency index.
entitydepthrelationmin_confidencelimitcursorSTIGMEM_CURSOR_TTL_S, default 300s).POST /v1/subscriptions
Register a push subscription to receive events when facts matching a scope or entity change. Requires a capability token covering the subscribe verb on the target.
curl -s -X POST http://localhost:8000/v1/subscriptions \
-H 'Authorization: Bearer <api-key>' \
-H 'Content-Type: application/json' \
-d '{
"target": "stigmem://company.example/project/phase9",
"target_type": "entity",
"on_change": "webhook",
"webhook_url": "https://your-agent.example/hook",
"idempotency_key": "sub-phase9-agent-assistant"
}'
Events are delivered with subscription_id, event_type (fact_asserted | fact_retracted | conflict_opened | conflict_resolved), fact_id, and hlc.
Delivery security: garden ACL + capability revocation re-checked on every event.
Event content is not populated until the ACL check passes —
preventing cross-garden fact leakage via standing event streams. If
access has been revoked since subscription creation, delivery is
silently dropped and the subscription is cancelled with event type
subscription_cancelled_access_revoked.
GET /v1/facts/:id/provenance
Walks the derived_from DAG for a given fact and returns the full derivation graph.
Cross-scope inference protection.
Caller must have read access to the root fact's scope and
garden_id. Unauthorized root facts return HTTP 403. When resolving
derived_from references, facts in unauthorized scopes or gardens
are represented as {"hash": "...", "exists": false} — identical to
genuinely absent facts. The endpoint does not confirm or deny the
existence of facts the caller cannot access.
curl -s http://localhost:8000/v1/facts/abc123/provenance \
-H 'Authorization: Bearer <api-key>'
Lazy instruction discovery endpoints
PUT /v1/agents/{agent_id}/instruction-manifest
Publish or replace the instruction manifest for an agent. The manifest is written with a versioned identifier so old manifests are superseded rather than overwritten in place.
Auth: write scope required.
{
"version": "v1-1746393600",
"entries": [
{
"name": "deployment-checklist",
"description": "Deployment Checklist",
"fact_uri": "instruction:default/agent/{agent_id}/deployment-checklist/v1",
"load_triggers": {
"intents": ["deployment checklist"],
"keywords": ["deploy", "checklist", "release"],
"task_types": []
},
"token_estimate": 340
}
],
"skip_coverage_gate": false
}
POST /v1/agents/{agent_id}/recall-instruction
Retrieve the most relevant instruction units for a given agent intent.
Three-phase retrieval strategy:
- Hint resolution — explicit
manifest_hintnames are loaded first (highest priority). - Ranked retrieval — remaining slots filled by BM25 scoring of
intentagainst each unit'sdescription,load_triggers.intents, andkeywords. - Guaranteed units — units with
guarantee_load: trueare always appended regardless of score; at most 5 per manifest.
intentmax_chunkstoken_budgetmanifest_hintcurl -s -X POST \
http://localhost:8000/v1/agents/a1b2c3d4-0000-0000-0000-000000000001/recall-instruction \
-H 'Authorization: Bearer <api-key>' \
-H 'Content-Type: application/json' \
-d '{
"intent": "how do I handle a production incident?",
"max_chunks": 3,
"token_budget": 2000
}'
Response includes chunks, total_tokens, truncated, missed_hints, and an audit_token to submit to POST /v1/instruction/audit.
CLI reference — stigmem instruction migrate
The stigmem instruction migrate command is the primary tool for publishing instruction files to a node.
stigmem instruction migrate PATH --role ROLE --agent-id UUID [options]
stigmem instruction migrate PATH --skill SKILL --agent-id UUID [options]
PATH--role ROLE / --skill SKILL--agent-id UUID--deployment NAME--version VER--node-url URL--api-key KEY--dry-run-y / --yesAuthentication
All endpoints except /.well-known/stigmem and /healthz require an API key. Pass it as a Bearer token:
curl -H 'Authorization: Bearer <your-key>' http://localhost:8000/v1/facts
Set STIGMEM_AUTH_REQUIRED=false to disable auth in development.
OIDC / SSO
Human principals can obtain an API key via OIDC. Configure STIGMEM_OIDC_* env vars; the node validates the JWT and maps role claims to admin|writer|reader.
Multi-tenant requests
Default installs resolve all API keys into the single default tenant. To use non-default tenants, install and enable stigmem-plugin-multi-tenant, then provision API keys with the target tenant_id.
Multi-tenant scoping is experimental in v0.9.0a10. It does not yet provide shared-node readiness, per-tenant quota/resource controls, or tenant-aware non-default federation.
Federation peer tokens
Federation endpoints additionally require an Ed25519-signed JWT peer token exchanged during the federation handshake (Spec-05-Federation-Trust).
Generating interactive docs
# Terminal 1 — start the reference node
cd stigmem/node
uv run python -m stigmem_node
# Terminal 2 — regenerate and serve docs
cd stigmem/docs
npm run gen-api-docs
npm run start
The API reference sidebar is populated by npm run gen-api-docs. Until that command has run, only this overview page appears.