API Reference
Complete protocol specification for the Sulcus API (https://api.sulcus.ca, Docker Private VPC appliances, and the local 127.0.0.1:4203 sidecar) plus Streamable HTTP and Stdio Model Context Protocol.
Authentication And Quotas
All /api/v1/* tenant endpoints accept SHA-256 hashed API keys (sk-...), Enterprise OIDC RS256 JWTs, or Air-Gap HS256 session tokens.
Bearer Token
Authorization: Bearer <token> (or X-API-Key) with an sk-... API key or session JWT.Machine Fingerprint
X-Sulcus-Machine-Id passes the deterministic UUIDv5 hardware fingerprint sent automatically by sulcus CLI and IDE plugins.Namespace Header
X-Namespace overrides the default workspace namespace for MCP and REST calls, validated against Two-Gate Namespace ACL.Request Quotas
300 req/min per tenant (public routes allow 30 req/min per IP) with a 2 MB JSON body limit.# Standard authenticated REST call with workstation seat binding and namespace override
curl -X POST https://api.sulcus.ca/api/v1/agent/search \
-H "Authorization: Bearer $SULCUS_API_KEY" \
-H "X-Sulcus-Machine-Id: 8b4d0e9c-21f4-5a9c-9d12-40f91a82c311" \
-H "X-Namespace: payments-rails" \
-H "Content-Type: application/json" \
-d '{
"query": "Stripe webhook HMAC verification and timestamp drift",
"limit": 8
}'License Continuity Guarantee
expired_readonly), all GET, hybrid search, recall, and graph read endpoints remain 100% operational so engineers never lose access to institutional memory, while mutating writes return 402 or 403 until renewed. Cross-namespace reads denied by ACL always return 404 Not Found to prevent namespace enumeration.REST Route Catalog
Filter by subsystem below. Every route listed here is mounted directly in the production Sulcus router.
Health And Discovery
Unauthenticated liveness probes, deployment auth mode discovery, Bearer verification, and machine-readable OpenAPI 3.1 schemas.
| Method | Endpoint | Purpose |
|---|---|---|
| GET | /health | Unauthenticated service liveness and engine readiness probe. |
| GET | /api/v1/health | Versioned v1 engine liveness, subsystem readiness, and build provenance probe. |
| GET | /openapi.json | Machine-readable OpenAPI 3.1 specification (also served at /openapi.yaml). |
| GET | /api/v1/auth/mode | Public discovery of deployment auth mode (cloud | connected_onprem | airgapped) and license state. |
| GET | /api/v1/auth/verify | Verify current Bearer token or sk-... key and return resolved tenant and namespace scope. |
Memories And Sync
Golden Index CRUD, single-pass turn ingestion, core memory blocks, PII scanning, and local-first CRDT delta sync.
| Method | Endpoint | Purpose |
|---|---|---|
| POST | /api/v1/agent/nodes | Store a memory node (aliases: POST /api/v1/agent/memory, POST /api/v1/agent/store). |
| GET | /api/v1/agent/nodes | List memories with ?namespace, ?memory_type, ?is_pinned, ?limit, ?offset (alias: GET /api/v1/agent/memory). |
| GET | /api/v1/agent/nodes/:id | Fetch full memory Territory and metadata by UUID (alias: GET /api/v1/agent/memory/:id). |
| PATCH | /api/v1/agent/nodes/:id | Update content (Territory), pointer_summary, memory_type, current_heat, decay_class, min_heat, or is_pinned. |
| DELETE | /api/v1/agent/nodes/:id | Soft-archive a memory node out of active working recall by UUID (restorable via POST /api/v1/agent/restore). |
| POST | /api/v1/agent/nodes/batch | Store a batch of memory nodes in one request. |
| POST | /api/v1/agent/nodes/bulk | Bulk delete memory nodes by UUID array. |
| POST | /api/v1/agent/nodes/bulk-patch | Bulk update pin state, namespace, or archetype across multiple nodes. |
| GET | /api/v1/agent/hot_nodes | Retrieve highest-salience active working memory nodes. |
| GET | /api/v1/agent/core-memory | Read structured core memory blocks (identity, preferences, current_focus). |
| PATCH | /api/v1/agent/core-memory | Update structured core memory blocks for an agent namespace. |
| POST | /api/v1/agent/ingest | Unified turn ingestion: single-pass embedding, MemPalace prep, System 1 VCR gating, entity linking, conflict checks, and trigger evaluation. |
| POST | /api/v1/agent/sync | CRDT WAL delta synchronization for local-first sulcus sidecars. |
| POST | /api/v1/agent/scan-pii | Scan candidate text for PII patterns prior to storage. |
| GET | /api/v1/agent/storage | Inspect node counts, storage utilization, and quota limits. |
| GET | /api/v1/agent/memory/status | Summarize active memory index health and counts. |
Hybrid Search
Hybrid cosine + BM25 + graph spreading activation search, token-budgeted hot-context assembly, and recall analytics.
| Method | Endpoint | Purpose |
|---|---|---|
| POST | /api/v1/agent/search | Hybrid cosine + BM25 + graph resonance + recency search across primary, global, and linked namespaces. |
| POST | /api/v1/agent/hot-context | Assemble token-budgeted working context for PreInvocation prompt injection. |
| POST | /api/v1/agent/entity-context | Retrieve entity-anchored memories and 1-hop knowledge graph context. |
| POST | /api/v1/agent/evaluate-output | Score generated agent output against stored constraints and surface contradictions. |
| POST | /api/v1/agent/boost-batch | Reinforce heat and stability across an array of recalled node UUIDs. |
| POST | /api/v1/agent/recall-log | Record recall telemetry for System 1 VCR adaptive retrieval weight scoring. |
| POST | /api/v1/recall/test | Diagnostic recall trace returning per-candidate vector, heat, recency, and graph score breakdowns. |
| POST | /api/v1/feedback | Submit explicit recall relevance feedback (relevant | irrelevant | outdated) to tune salience. |
| GET | /api/v1/analytics/recall | Retrieve recall hit rates, average similarity, and namespace retrieval analytics. |
Knowledge Graph
Knowledge graph neighbor traversal, semantic edge creation, point-in-time temporal validity queries, and contradiction resolution.
| Method | Endpoint | Purpose |
|---|---|---|
| GET | /api/v1/agent/graph/status | Inspect knowledge graph vertex and edge counts and Apache AGE sulcus_graph sync status. |
| GET | /api/v1/agent/graph/neighbors/:id | Traverse outbound and inbound edges around a memory UUID. |
| POST | /api/v1/agent/graph/relate | Create a weighted semantic edge via relation (related_to, depends_on, contradicts, supersedes, consolidated_from; alias: relation_type). |
| POST | /api/v1/agent/graph/temporal | Query facts and graph edges for topic valid at ISO-8601 at_time (aliases: query, as_of). |
| GET | /api/v1/agent/graph/verify/:id | Verify graph parity between PostgreSQL golden_index and graph edges. |
| GET | /api/v1/agent/graph/snapshot | Export visual graph topology for Memory Constellation rendering. |
| GET | /api/v1/agent/conflicts | List detected semantic contradictions from the conflicts table across stored memories. |
| PATCH | /api/v1/agent/conflicts/:id | Resolve a memory contradiction (keep_new, keep_old, keep_both, dismiss). |
Synapse Curation
Unified System 1 VCR gating and routing (legacy curation paths remain mounted as backward-compatible aliases), swappable open-weight cartridges, Dynamic Skills VMMU, folder ingestion, and episode synthesis.
| Method | Endpoint | Purpose |
|---|---|---|
| POST | /api/v1/vcr/classify | Evaluate candidate text through System 1 VCR returning quality ("store" | "reject") and memory_type. |
| POST | /api/v1/vcr/label | Submit an operator or agent ground-truth quality and archetype label for System 1 VCR. |
| POST | /api/v1/vcr/signal | Record an operator or agent labeling signal (quality: "store" | "reject" or memory_type correction). |
| GET | /api/v1/vcr/signals | List accumulated System 1 VCR training signals for the tenant or namespace. |
| GET | /api/v1/vcr/status | Inspect active System 1 VCR model metadata, accuracy scores, retrieval weights, and signal counts. |
| POST | /api/v1/vcr/retrain | Retrain System 1 VCR weights behind the validation promotion gate. |
| PUT | /api/v1/vcr/models | Sync or reset (DELETE) tenant or namespace System 1 VCR model weights. |
| POST | /api/v1/decision | Full System 1 VCR evaluation returning store/reject decision and calibrated class probabilities. |
| GET | /api/v1/models/cartridges | List built-in and imported open-weight embedder, classifier, and Needle Edge SLM cartridges. |
| POST | /api/v1/models/cartridges | Activate, import, or reset open-weight model cartridges. |
| POST | /api/v1/train/classifierLocal Engine | Train or auto-scaffold a custom System 1 VCR classifier on a local document folder. |
| GET | /api/v1/skills | List Dynamic Skills VMMU Map pointers indexed in skills_index. |
| POST | /api/v1/skills | Ingest a Markdown skill playbook into compact Map pointers and on-demand Territory sections. |
| POST | /api/v1/skills/fault | Page in a specific skill section Territory on demand and reinforce skill heat. |
| POST | /api/v1/ingest/folderLocal Engine | Ingest PDF, Markdown, HTML, code, and text documents into document_chunks and memory nodes. |
| GET | /api/v1/ingest/chunksLocal Engine | Query indexed verbatim document chunks for a namespace. |
| POST | /api/v1/agent/fold | Fold related memories into a named context cluster. |
| GET | /api/v1/agent/consolidation-candidates | Preview cold or redundant episodic clusters eligible for synthesis. |
| POST | /api/v1/agent/consolidate | Distill candidate episodic clusters into high-salience synthesis nodes. |
| GET | /api/v1/agent/archive | List cold-archived memories eligible for restoration. |
| POST | /api/v1/agent/restore | Restore archived memory UUIDs back into active working memory. |
Namespace Governance
Persistent cross-repo namespace links, per-namespace compression profiles, and Two-Gate Namespace ACL policies.
| Method | Endpoint | Purpose |
|---|---|---|
| GET | /api/v1/agent/namespaces | List ACL-readable namespaces and node counts. |
| GET | /api/v1/namespaces/links | List persistent linked namespaces (?namespace=<primary>). |
| POST | /api/v1/namespaces/links | Upsert a persistent namespace link (mode: auto_search | on_match). |
| DELETE | /api/v1/namespaces/links/:primary/:linked | Delete a persistent namespace link (use _all_ or * for tenant-wide primary). |
| GET | /api/v1/namespaces/profiles | Inspect per-namespace Caveman compression intensity, AST rules, and cartridge bindings. |
| PUT | /api/v1/namespaces/profiles | Upsert a custom compression and indexing profile for a namespace. |
| GET | /api/v1/namespaces/acl | Fetch default_policy, explicit ACL rules, and namespace inventory. |
| POST | /api/v1/namespaces/acl | Upsert an (agent_label, namespace, policy) rule supporting prefix* wildcards. |
| DELETE | /api/v1/namespaces/acl/:id | Remove an explicit ACL rule by numeric ID. |
| PUT | /api/v1/namespaces/default | Update tenant-wide default cross-namespace policy (allow | read | deny). |
Agent Event Bus
Live multi-agent presence, collision/overlap alerts, fan-out broadcasts, and SSE event replay.
| Method | Endpoint | Purpose |
|---|---|---|
| GET | /api/v1/agent/bus/status | Snapshot active_agents, active_peers, territory_conflicts, intent_overlaps, and recent_events. |
| POST | /api/v1/agent/bus/heartbeat | Upsert session presence (working | idle | compacting | offline), current_intent, and files_touched. |
| POST | /api/v1/agent/bus/broadcast | Publish a coordination event to source namespace, comma-separated target_namespace, or "all". |
| GET | /api/v1/agent/bus/stream | SSE stream with Last-Event-ID / ?since_id cursor replay and 15s keepalive. |
| GET | /api/v1/agent/bus/subscriptions | List active namespace subscriptions and discover ACL-readable workspaces. |
| POST | /api/v1/agent/bus/subscriptions | Subscribe, unsubscribe, or set watched namespaces (up to 25 per session). |
Reactive Triggers
Deterministic event-driven automation across 10 memory, graph, and bus events.
| Method | Endpoint | Purpose |
|---|---|---|
| GET | /api/v1/triggers | List configured reactive triggers. |
| POST | /api/v1/triggers | Create a reactive trigger on any of the 10 supported events. |
| PATCH | /api/v1/triggers/:id | Toggle enabled or update trigger filters, cooldowns, and action_config. |
| DELETE | /api/v1/triggers/:id | Delete a trigger by UUID. |
| GET | /api/v1/triggers/history | Fetch recent trigger execution history. |
| POST | /api/v1/triggers/evaluate | Evaluate triggers manually against a test event payload. |
| POST | /api/v1/triggers/feedback | Record trigger helpfulness or noise precision telemetry. |
Activity Ledger
1,000-turn SHA-256 mutation ring buffer and out-of-order surgical rollback.
| Method | Endpoint | Purpose |
|---|---|---|
| GET | /api/v1/agent/ledger | List Activity Ledger turns and active retention config. |
| POST | /api/v1/agent/ledger/record | Record a file, CLI, or MCP mutation with SHA-256 pre/post snapshots. |
| POST | /api/v1/agent/ledger/config | Update namespace ledger capacity and snapshot settings. |
| POST | /api/v1/agent/ledger/undo | Execute LIFO batch rewind or out-of-order surgical hunk undo. |
Settings And Keys
Thermodynamic retention tuning, System 1 VCR configuration, and scoped API key lifecycle.
| Method | Endpoint | Purpose |
|---|---|---|
| GET | /api/v1/settings/thermo | Inspect tenant ThermoConfig and defaults (alias: GET /api/v1/settings/lifecycle). |
| PATCH | /api/v1/settings/thermo | Update per-type half_life_secs, half_life_interactions, floors, and resonance. |
| GET | /api/v1/settings/vcr | Inspect tenant-wide System 1 VCR gating thresholds, auto-retrain cadence, and keyword overrides. |
| PATCH | /api/v1/settings/vcr | Update tenant-wide System 1 VCR configuration and keyword overrides. |
| GET | /api/v1/settings/vcr/:namespace | Inspect per-namespace System 1 VCR override configuration and inheritance state. |
| PATCH | /api/v1/settings/vcr/:namespace | Upsert or clear per-namespace System 1 VCR overrides (DELETE resets to workspace defaults). |
| GET | /api/v1/system1/settingsLocal Engine | Read workstation System 1 VCR training defaults and active cartridge bindings. |
| PUT | /api/v1/system1/settingsLocal Engine | Update workstation System 1 VCR training hyperparameters and thresholds. |
| GET | /api/v1/keys | List active API key prefixes, labels, and optional scoped namespaces (raw secrets never stored). |
| POST | /api/v1/keys | Mint a new sk-... API key (returned once on creation; stored as SHA-256 digest). |
| PATCH | /api/v1/keys/:id | Rename or rescope an existing API key. |
| DELETE | /api/v1/keys/:id | Immediately revoke an API key. |
Organization Admin
Organization seats, workstation leases, agent namespace administration, and Enterprise Appliance sign-in.
| Method | Endpoint | Purpose |
|---|---|---|
| GET | /api/v1/org | Inspect organization profile, plan tier, named seats, and active workstation leases. |
| PATCH | /api/v1/org | Update organization display name. |
| POST | /api/v1/org/invite | Invite a named seat member (or generate an intranet seat invite on appliances). |
| DELETE | /api/v1/org/members/:user_id | Remove a seat member and revoke bound workstation leases. |
| GET | /api/v1/admin/agents | List agent namespaces with memory, heat, and activity summaries. |
| GET | /api/v1/admin/agents/:namespace | Detailed profile and telemetry for a specific agent namespace. |
| PATCH | /api/v1/admin/agents/:namespace/status | Pause or resume an agent namespace. |
| POST | /api/v1/admin/agents/merge | Merge memories and edges from a source namespace into a destination namespace. |
| DELETE | /api/v1/admin/agents/:namespace | Purge an agent namespace and its scoped memories. |
| POST | /api/v1/onprem/login | Connected Private VPC seat sign-in (accepts federated OIDC JWT or seat credentials). |
| POST | /api/v1/airgap/login | Air-gapped intranet seat login returning HS256 session JWT. |
Canonical MCP Tools
Sulcus implements JSON-RPC 2.0 MCP over Workstation Proxy Stdio (sulcus mcp-proxy), Local Embedded Stdio (sulcus stdio), Streamable HTTP (POST / GET / DELETE /mcp), and Legacy SSE (GET /api/v1/mcp/sse + POST /api/v1/mcp/message).
// Zero-secret workstation MCP configuration (written automatically by sulcus connect)
{
"mcpServers": {
"sulcus": {
"command": "sulcus",
"args": ["mcp-proxy"]
}
}
}
// Direct Streamable HTTP MCP transport (for cloud-hosted agents without local CLI)
{
"mcpServers": {
"sulcus": {
"url": "https://api.sulcus.ca/mcp",
"transport": "streamable-http",
"headers": {
"Authorization": "Bearer sk-..."
}
}
}
}Memory Lifecycle Tools
| Tool | Purpose |
|---|---|
store_memory | Save durable knowledge with optional memory_type, label, pointer_summary, is_pinned, namespace, and tags (aliases on tools/call: record_memory, commit_memory, commit_code, remember). |
search_memory | Hybrid semantic + BM25 + graph resonance recall across primary, global, and linked namespaces, with tier ("hot" | "cold" | "all"), tags, and temporal filters. |
expand_memory | Expand full raw Territory (or optional lines="1-80" slice) by memory UUID or ccr:<hex> handle and reinforce current_heat by +0.15 (aliases: page_in, fetch_memory, get_node). |
update_memory | Update content, pointer_summary, memory_type (reclassify), or is_pinned, or adjust salience via action ("boost" | "deprecate") (aliases: memory_boost, memory_deprecate, memory_reclassify). |
forget_memory | Delete an obsolete memory node and optionally purge cold decayed entries via purge_cold=true (aliases: delete_memory, forget). |
relate_memories | Create a weighted graph edge between source_id and target_id (bidirectional by default; alias: memory_relate). |
Context And Skills
| Tool | Purpose |
|---|---|
build_context | Construct a token-budgeted <sulcus_context> XML block combining pinned mandates and query-relevant memories (prompt, namespace, token_budget, max_nodes). |
list_memories | Return top active working-set nodes sorted by current_heat with optional namespace and memory_type filters (alias: list_hot_nodes). |
list_namespaces | List ACL-readable namespaces and active memory counts for the caller. |
use_skill | List, search, load (action="load"), or ingest procedural playbooks in the Dynamic Skills VMMU on demand (alias: fault_skill). |
reduce_output | Deterministically compress noisy CLI logs (command + output) or heavy JSON/diff payloads (output alone) by 80-95% behind a reversible handle for expand_memory. |
Local Code AST
| Tool | Purpose |
|---|---|
project_map | Build or query the local Tree-sitter AST workspace atlas (modules/crates, entrypoints, symbol counts, and CCR handles via sulcus or sulcus mcp-proxy). |
find_symbol | Locate functions, methods, structs, traits, classes, or types across the workspace with exact [Lstart-Lend] spans. |
get_outline | Parse a workspace file (path) or inline snippet (content) into syntactic signatures, spans, docstrings, imports, and call edges (alias: outline_code). |
get_references | Trace cross-file symbol definitions, callers, and module importers across the workspace. |
Governance And Triggers
| Tool | Purpose |
|---|---|
create_trigger / list_triggers / update_trigger / delete_trigger | Full CRUD for deterministic Reactive Memory Triggers; pass include_history=true to list_triggers for recent firing logs. |
list_activity_ledger / undo_activity | Inspect recorded file and CLI mutations and execute selective Surgical Rewind while preserving later non-overlapping edits. |
agent_bus_status / manage_namespace_connections | Enterprise Event Bus tools: inspect active peer agents, territory conflicts, intent overlaps, and persistent namespace links. |