API REFERENCE

A compact HTTP surface for causal data.

The /db/v1 API covers typed graphs, evidence, deterministic views, provenance, and read-only counterfactuals. JSON is used for requests and responses.

OpenAPI 3.1Versioned at /db/v1JSON

Base URL

endpointHTTPS

https://api.your-domain.com/db/v1

For a local instance, the default base URL is http://localhost:9876/db/v1.

Authentication

Reachable instances use a Bearer credential. Organization keys begin with cok_; personal tokens begin with cut_. The development override also accepts an organization identifier header.

request headersproduction

Authorization: Bearer cok_…
Content-Type: application/json

request headerslocal development

X-Org-Id: 8f78…
Content-Type: application/json

Endpoints

Graphs

GET/db/v1

Service descriptor and enabled capabilities

GET/db/v1/graphs

List graphs in the caller’s organization

POST/db/v1/graphs

Create a graph

GET/db/v1/graphs/{graphId}

Read one graph

DELETE/db/v1/graphs/{graphId}

Delete a graph and its data

Topology

GET/db/v1/graphs/{graphId}/topology

Read the typed topology

PUT/db/v1/graphs/{graphId}/topology

Replace topology atomically

POST/db/v1/graphs/{graphId}/nodes

Add an event or gate

PATCH/db/v1/graphs/{graphId}/nodes/{nodeId}

Update a node

POST/db/v1/graphs/{graphId}/edges

Add a parent-to-child edge

Evidence & views

GET/db/v1/graphs/{graphId}/evidence

List evidence records

POST/db/v1/graphs/{graphId}/evidence

Append evidence

POST/db/v1/graphs/{graphId}/views/analysis

Compute or serve cached analysis

GET/db/v1/graphs/{graphId}/views/analysis

Read with the freshness contract

POST/db/v1/graphs/{graphId}/views/what-if

Compute a read-only counterfactual

POST/db/v1/graphs/{graphId}/compile

Compile a tree from mechanism facts

Provenance

GET/db/v1/graphs/{graphId}/revision

Read the current input revision

GET/db/v1/graphs/{graphId}/deltas

Read changes over a revision range

GET/db/v1/graphs/{graphId}/snapshots

List computed-view history

GET/db/v1/chains

Traverse mechanism propagation

Create a graph

Request

POST/db/v1/graphs

{
  "name": "packaging-line",
  "description": "Causal model for line availability"
}

Response · 200

application/json200

{
  "id": "gr_7f31c2",
  "name": "packaging-line",
  "stage": "active",
  "created_at": "2026-08-14T04:00:00Z"
}

Read analysis freshness

analysis is non-null only while the stored result revision equals the graph revision. A stale read carries the revision pair and the deltas that explain invalidation.

GET/graphs/{graphId}/views/analysis

{
  "project_id": "gr_7f31c2",
  "analysis": null,
  "stale": true,
  "computed_at_revision": 41,
  "current_revision": 42,
  "changes_since": [
    {"kind":"node_edit","revision":42,"changed":[{"id":"E_SEAL","field":"probability"}]}
  ]
}

Errors

Status	Meaning	Action
`400`	Validation failed	Check required fields, node types, and graph structure.
`401`	Unauthenticated	Supply a valid Bearer credential.
`403`	Permission denied	Use a role with permission for the requested operation.
`404`	Not found	Confirm the identifier belongs to the authenticated organization.

Errors use a stable JSON envelope: {"error":"message"}.

Versioning

The /db/v1 surface evolves additively. Clients should ignore unknown response fields and inspect GET /db/v1 for capability packs enabled on an instance.

NEXTUse the TypeScript or Python client →