/v1 catalog. All endpoints require a Bearer token; see
Authentication. Paths use :param for path
parameters.
The surface is organized in two layers. The developer nouns at the top —
memories, documents, submissions, connections — are the happy path: one call to
do the obvious thing. The substrate routes below them (deltas, graph,
packet) are the power surface; every facade response returns the substrate ids
(delta_id, source_id, project_id) so you can descend when you need
control.
Memories
Store and recall agent memory as first-class REST. Writes commit by default; passapply: false to stage a delta instead.
| Method | Path | Purpose |
|---|---|---|
POST | /v1/memories | Create one memory, or a batch of up to 100 ({ "memories": [...] }). |
POST | /v1/memories/search | Search active memory. |
POST | /v1/memories/synthesize | Synthesize recalled memory into a briefing. |
GET | /v1/memories/:id | Read a single memory. |
PATCH | /v1/memories/:id | Update a memory. |
POST | /v1/memories/:id/archive | Retire a memory (lineage preserved). |
content (required), and optional kind, scope
(agent · commons · project), subject, source_context, and
forget_after / forget_reason for time-bound memory. The response carries
id, status (applied or staged), delta_id, and shape_id.
Documents
Add and search documents over the source/file substrate.| Method | Path | Purpose |
|---|---|---|
POST | /v1/documents | Add a document: content, a url to crawl, a multipart file, or signed-upload metadata. |
POST | /v1/documents/search | Search across documents and their chunks. |
GET | /v1/documents | List documents in the project (optional ?search=). |
GET | /v1/documents/:id | Read a single document. |
POST | /v1/documents/:id/extract | Prepare extraction; returns the /v1/extractions/shape call to run. |
Submissions
A generic capture door for app events, form payloads, and anything you want to land as graph structure. The body’s shape routes it: aurl or as_document
becomes a document, a shape plus a source becomes an extraction, everything
else stages a capture delta.
| Method | Path | Purpose |
|---|---|---|
POST | /v1/submissions | Submit content or an event for capture. |
Connections
Headless integration connect. Token-paste platforms (Granola, Attio) in v1; OAuth-class platforms keep the browser consent flow.| Method | Path | Purpose |
|---|---|---|
POST | /v1/connections | Connect a platform: platform, credential, target_project_id. |
GET | /v1/connections | List connected platforms for the org. |
GET | /v1/connections/:id | Read one connection. |
DELETE | /v1/connections/:id | Disconnect. |
POST | /v1/connections/:id/sync | Queue a sync (the platform cron picks it up). |
Search and retrieval
| Method | Path | Purpose |
|---|---|---|
POST | /v1/search | Hybrid search composition across entities and sources. |
GET | /v1/graph/search | Graph-native search. |
GET | /v1/graph/traverse | Traverse from a starting entity. |
GET | /v1/graph/stats | Graph statistics. |
POST | /v1/retrieval/search | Retrieval over the search index. |
POST | /v1/retrieval/search/semantic | Semantic retrieval. |
GET | /v1/retrieval/resolve/entity/:elementId | Resolve an entity to its lineage. |
GET | /v1/retrieval/resolve/chunk/:chunkId | Resolve a source chunk. |
GET | /v1/retrieval/stats | Retrieval index stats. |
Decision quality
Read-only verdicts: is a region of the graph fit to act on? The/v1/decision-quality/* paths are canonical for public use; the shorter
/v1/dq/* paths remain a stable alias.
| Method | Path | Purpose |
|---|---|---|
POST | /v1/decision-quality/check | Fitness-for-action verdict for a subject and purpose. |
POST | /v1/decision-quality/audit | Dry-run check that applying a delta would not degrade the graph. |
POST | /v1/decision-quality/trace | Evidence coverage for a set of claims or entities. |
Extraction
| Method | Path | Purpose |
|---|---|---|
POST | /v1/extractions/shape | Extract entities from text through a shape into a delta. |
GET | /v1/extractions/runs/:jobId | Poll an async extraction run for status and the resulting delta id. |
POST | /v1/shapes/extract | Propose a shape from external material (web crawl or file). |
IR mapping
Map an external API’s type system onto your ontology. RESTful resources over a durable mapping session; tool errors ride back as HTTP 200 withisError: true
rather than a non-2xx status. See the guide.
| Method | Path | Purpose |
|---|---|---|
GET | /v1/ir/tools | List the IR tools and their REST routes. |
POST | /v1/ir/mappings | Open a mapping session for a project. |
POST | /v1/ir/mappings/:id/sources | Ingest a foreign IR (OpenAPI 3.x today). |
POST | /v1/ir/mappings/:id/types | Map one of their types to one of yours. |
POST | /v1/ir/mappings/:id/types/remove | Remove a type mapping. |
POST | /v1/ir/mappings/:id/properties | Map a property pair under a type mapping. |
POST | /v1/ir/mappings/:id/properties/remove | Remove a property match. |
POST | /v1/ir/mappings/:id/proposals/review | Review model-proposed matches without mutating. |
GET | /v1/ir/mappings/:id | Inspect the mapping state. |
POST | /v1/ir/mappings/:id/analyze | Coverage, property coverage, and drift. |
Deltas (governed writes)
The substrate under every write. Reach for it when you want to stage, review, and apply changes as a unit.| Method | Path | Purpose |
|---|---|---|
POST | /v1/deltas | Open a new delta. |
GET | /v1/deltas/:id | Read a delta and its staged contents. |
POST | /v1/deltas/:id/entities | Stage entities. |
POST | /v1/deltas/:id/relationships | Stage relationships. |
POST | /v1/deltas/:id/submit | Mark a delta ready. |
POST | /v1/deltas/:id/plan | Preview how applying it changes the graph. |
POST | /v1/deltas/:id/apply | Commit the delta. |
POST | /v1/deltas/:id/revert/preview | Preview a revert. |
POST | /v1/deltas/:id/revert | Revert an applied delta. |
Nodes and graph
| Method | Path | Purpose |
|---|---|---|
GET | /v1/nodes | List entities. |
GET | /v1/nodes/:elementId | Read a single entity. |
GET | /v1/graph-stats | Summary graph stats. |
POST | /v1/graph/packet | Assemble and evaluate a context packet. |
POST | /v1/graph/hydrate | Hydrate the graph projection. |
POST | /v1/graph/patch | Apply a graph patch. |
Packet
| Method | Path | Purpose |
|---|---|---|
POST | /v1/packet/evaluate | Sufficiency verdict for a context packet. |
Ontology, types, and shapes
| Method | Path | Purpose |
|---|---|---|
GET | /v1/ontology | Read the active ontology as a document. |
GET | /v1/types | List entity types. |
GET | /v1/types/:name | Read a type. |
POST | /v1/types | Create a type. |
PATCH | /v1/types/:name | Update a type. |
DELETE | /v1/types/:name | Delete a type. |
GET | /v1/shapes | List shapes in the project. |
GET | /v1/shapes/kit | The curated starter shapes (not included in the list above). |
GET | /v1/shapes/:id | Read a shape. |
GET | /v1/shapes/:id/schema | Read a shape’s schema. |
GET | /v1/shapes/:id/binding | Read a shape’s binding. |
GET | /v1/shapes/:id/interface | Read a shape’s interface. |
GET | /v1/shapes/:id/extraction-bundle | Read the extraction bundle. |
GET | /v1/shapes/:id/relationships | Read shape relationships. |
GET | /v1/shapes/:id/projections | Read retrieval projections. |
DELETE | /v1/shapes/:id | Delete a shape. |
POST | /v1/shapes/materialize | Materialize a shape. |
Shape workbench
| Method | Path | Purpose |
|---|---|---|
GET | /v1/shape-workbench/tool-access | Workbench tool access status. |
POST | /v1/shape-workbench/:tool | Invoke a workbench tool. |
Auth and realtime
| Method | Path | Purpose |
|---|---|---|
POST | /v1/auth/token | Exchange credentials for a short-lived token. |
GET | /v1/ws | WebSocket upgrade for realtime. |
Health
| Method | Path | Purpose |
|---|---|---|
GET | /health | Service health. |
GET | /v1/health/kernel | Authenticated service provenance. |