26 endpoints. All requests and responses are JSON. All writes require human_author — anonymous appends are rejected at the protocol level (GR-PROV-015). The base URL for a default local node is http://localhost:9090.
{"ok": true, "data": ...} on success or {"ok": false, "error": "..."} on failure. Parameters marked * are required.| Name | Call | Parameters | Description |
|---|---|---|---|
| Publish | POST/api/cu/publish | subject_id subject_type artifact artifact_type human_author predecessor_id notes tags model_id prompt_lineage scope_id |
Append a new context unit to a lineage chain. The spoke is created automatically on first publish to a new subject_id. If predecessor_id is omitted, the server auto-resolves to the current chain head. Supply predecessor_id explicitly to branch from a specific point in history.
artifact_type: text · code · voice-transcript · structured · mutation · binary
GR-PROV-011 GR-PROV-012 GR-PROV-015
|
| Get | GET/api/cu/get?id=X | id |
Return the full context unit including artifact content. Fetches the artifact blob from context-unit-data.
|
| Download | GET/api/cu/download?id=X | id |
Stream the artifact content directly with the appropriate Content-Type header. Binary artifacts (stored as base64 JSON envelopes) are decoded and served as raw bytes with Content-Disposition: attachment. Text artifacts are served inline as text/plain.
|
| Lineage | GET/api/cu/lineage?subject_id=X | subject_id |
Return the ordered lineage chain for a subject, oldest first. Header only — artifact content is not included. Use /api/cu/get to retrieve individual artifact blobs.
|
| Snapshot | GET/api/cu/snapshot?id=X | id | Return a self-contained reconstruction record: the target CU with its artifact, plus all predecessor headers back to the chain root. An agent can reconstruct full context from this snapshot alone without further queries. |
| List | GET/api/cu/list | subject_type tag limit offset | Return CU headers matching the given filters. Headers only — no artifact content. Results are newest first. |
| Merge | POST/api/cu/merge | subject_id subject_type artifact artifact_type human_author predecessor_id merge_id notes tags |
Publish a merge CU manually. predecessor_id is branch head A; merge_id is branch head B. The reconciled artifact must be supplied by the caller. Human authorization is required — agents cannot merge autonomously.
GR-PROV-016
|
| Scope | GET/api/cu/scope | scope_id limit |
Return all child spokes whose scope_id matches the given parent subject_id. Enables cross-spoke hierarchy queries — e.g. all agent logs scoped to a given order.
GR-PROV-017
|
| Name | Call | Parameters | Description |
|---|---|---|---|
| Create Spoke | POST/api/spoke/create | subject_id label type curator synopsis scope_id |
Explicitly create a spoke record before publishing the first CU. Useful when spoke metadata (label, curator, synopsis) is known before the first append. If a spoke for the given subject_id already exists, returns the existing record.
|
| List Spokes | GET/api/spoke/list | type status scope_id limit | Return spoke records with CU count, last author, and last published timestamp resolved from the tail CU. Supports filtering by type, status (active/archived), or parent scope. |
| Get Spoke | GET/api/spoke/get?subject_id=X | subject_id | Return a single spoke record with tail CU fields resolved. |
| Update Spoke | POST/api/spoke/update | subject_id label synopsis curator status |
Update spoke metadata. Status transitions: active → archived. Archiving does not prevent new CU appends — it is a metadata signal only.
|
| Name | Call | Parameters | Description |
|---|---|---|---|
| Verify | GET/api/chain/verify?subject_id=X | subject_id |
Recompute the hash chain for the given subject and confirm every cu_prev_hash is correct. Artifact content participates in the hash — blob integrity is verified alongside the header. On merge CUs, both branches are verified independently.
Returns {"status":"ok","verified":true,"length":N,"subject_id":"..."} on a clean chain, or {"status":"broken","verified":false,"broken_at":"cu_id","reason":"...","length":N} on the first detected break. Returns an error if the subject has no CUs.
GR-PROV-012
|
Three-way merge and two-way diff operate on text-class artifacts only: text, code, and voice-transcript. Binary and structured artifact types are not merge-eligible.
| Name | Call | Parameters | Description |
|---|---|---|---|
| Two-Way Diff | GET/api/diff/two-way | cu_id_a cu_id_b |
Compute a unified diff between two CU artifacts. Returns a diff string, an identical boolean, and labels for each side.
|
| Three-Way Merge | POST/api/merge/three-way | ancestor_cu_id branch_a_cu_id branch_b_cu_id author notes tags |
Run a three-way merge against the two branch heads and their common ancestor. On a clean merge the server emits the merge CU automatically and returns its cu_id. On conflict the server returns the conflict-marked content for human resolution — submit to /api/merge/resolve after editing.
GR-PROV-016
|
| Resolve Merge | POST/api/merge/resolve | ancestor_cu_id branch_a_cu_id branch_b_cu_id resolved_content author notes tags |
Submit human-resolved merge content. The resolved_content must not contain any conflict markers. The server emits the merge CU under the supplied author, recording both branch heads in the lineage.
|
Echo targets receive a POST of the CU header JSON after every successful publish. The payload contains header fields only — no artifact content. Dispatch is asynchronous and fire-and-forget. Failures are recorded as audit-event CUs on the chain.
| Name | Call | Parameters | Description |
|---|---|---|---|
| Register | POST/api/echo/register | url label | Register a URL as an echo target. Every CU published after registration will POST its header to this URL. Multiple targets are supported. Targets are append-only — deactivate rather than delete. |
| List Targets | GET/api/echo/list | — | Return all echo targets with their active status and registration timestamp. |
| Deactivate | POST/api/echo/deactivate | id | Deactivate an echo target. Deactivated targets stop receiving dispatches but remain in the record. Deactivation cannot be undone — register a new target if needed. |
| Name | Call | Parameters | Description |
|---|---|---|---|
| Create | POST/api/annotation/create | cu_id subject_id author text | Attach a human annotation to a specific CU. Annotations are mutable — they can be updated but not deleted. They are stored as a separate record class, not as CUs on the chain. |
| Update | POST/api/annotation/update | id text | Update the text of an existing annotation. |
| List | GET/api/annotation/list | cu_id subject_id | Return annotations for a given CU or all annotations on a subject's chain. |
| Name | Call | Parameters | Description |
|---|---|---|---|
| Create | POST/api/version-tag/create | subject_id label author cu_ids notes |
Create a named version tag on a spoke — e.g. v1.0, approved, released. Tags reference one or more CU ids and carry a status lifecycle: draft → active → removed.
|
| Update | POST/api/version-tag/update | id label notes cu_ids status | Update a version tag's label, notes, CU references, or status. |
| List | GET/api/version-tag/list | subject_id cu_id | Return version tags for a spoke or for a specific CU. |
| Name | Call | Parameters | Description |
|---|---|---|---|
| Health | GET/api/health | — |
Returns node status, protocol version, self-hosting proof CU id, and active echo target count. Use to confirm the node is running before beginning a session.
Example response
{"ok": true, "protocol": "Chandra", "version": "0.1","self_hosting": true, "proof_id": "19d9385b-...", "active_echo_targets": 0} |
Every AI inference call logged as a Chandra context unit is operating at CRC Boundary pillar score 4 -- the maximum under the CRC Minimum Surface Standard. The call is attributed. The response is logged. The crossing is part of the immutable chain. Deployments that govern their AI inference boundary through Chandra are, by construction, Boundary score 4 deployments. This is not a compliance add-on. It is the operating mode.
The forthcoming GABA Standard (Governed AI Boundary Attestation) defines the formal framework for AI inference boundary risk acceptance. Chandra provides the attestation mechanism: every GABA record is a context unit -- attributed, hash-chained, unforgeable.