REST API

Machine-readable contract: OpenAPI 3.1. Orientation for LLMs: api.chainmemory.ai/llms.txt.

Authentication

All API calls require authentication via API Key in the header:

HTTP
x-api-key: your-api-key

Base URL: https://api.chainmemory.ai/v1

Memories

bash
curl -X POST https://api.chainmemory.ai/v1/memory \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "summary": "Decided to use PostgreSQL instead of MongoDB",
    "category": "decision",
    "importance": 8,
    "platform": "manual"
  }'

javascript
const res = await fetch('https://api.chainmemory.ai/v1/memory', {
  method: 'POST',
  headers: {
    'x-api-key': 'your-api-key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    summary: 'Decided to use PostgreSQL instead of MongoDB',
    category: 'decision',
    importance: 8,
    platform: 'api'
  })
});
const memory = await res.json();
// { id: 207, hash: '0x4f2a...', memory_number: 42 }

python
import requests

res = requests.post(
    'https://api.chainmemory.ai/v1/memory',
    headers={'x-api-key': 'your-api-key'},
    json={
        'summary': 'Decided to use PostgreSQL instead of MongoDB',
        'category': 'decision',
        'importance': 8,
        'platform': 'api'
    }
)
memory = res.json()
# {'id': 207, 'hash': '0x4f2a...', 'memory_number': 42}

Parameters

Projects

Response (trimmed)
{
  "project": "payment-system",
  "schema_version": 2,
  "version": 4,
  "state_hash": "0x3f8c2a…e91d",
  "generated_at": "2026-09-13T22:02:35.000Z",
  "anchor": { "status": "anchored", "onchain_anchor_id": 12, "tx_hash": "0x…", "block_number": 681919 },
  "state": {
    "phase": "beta",
    "current_focus": "PCI review before opening to the first tenants",
    "decisions": [
      { "id": "dec_0002", "title": "PostgreSQL with RLS for multi-tenancy",
        "statement": "Row-level security removes tenant filtering from the application layer",
        "status": "confirmed", "superseded_by": null,
        "evidence_root": "0x9a41…c07e", "created_version": 2, "updated_version": 3 }
    ],
    "milestones": [
      { "id": "mil_0001", "title": "Database schema", "status": "done",
        "evidence_root": "0x5b2d…81fa", "created_version": 1, "updated_version": 2 }
    ],
    "risks": [
      { "id": "risk_0001", "title": "RLS performance at 100K tenants", "severity": "med", "status": "open",
        "evidence_root": "0xd7e0…2a19", "created_version": 3, "updated_version": 3 }
    ],
    "state_meta": { "version": 4, "consolidated_until_event": 150, "previous_state_hash": "0x7b2e…f4c0" }
  }
}

Always the latest version; requires the owner's API key. Severity values are low, med and high.

Response (trimmed)
{
  "project": "payment-system",
  "version": 4,
  "state_hash": "0x3f8c2a…e91d",
  "level": "public",
  "budget": 7000,
  "lang": "en",
  "since": 3,
  "length": 2841,
  "text": "[ChainMemory · Project State: payment-system v4]
…"
}

With task, the response carries task instead of since. Always the latest version; requires the owner's key or an organization key with access to the project (a project key only reads its own project).

Injection

Response

The endpoint returns the selected memories formatted for injection. Each memory arrives tagged with its user-facing number and a verification reference, so an AI can cite the exact memory behind any statement — and you can trace that citation back to its on-chain evidence. A claim stops being "trust me" and becomes "here's the memory, verify it yourself."

Verification

Response
{
  "project": "chainmemory",
  "projectId": "0x77f7d980...",
  "version": 3,
  "state_hash": "a7b3c9f2...",
  "anchor": {
    "status": "anchored",
    "tx_hash": "0xce55a800a2a4e30b...",
    "block_number": 123539,
    "contract": "0xa7A8BA51950255b3e223a6745597C67009Fe7875"
  }
}

Error Codes

Feature Equivalence: Extension ↔ MCP ↔ API

Not every feature is available through every integration method. This table shows what's available where:

Trust & Governance

Every memory carries a trust status from the moment it is written: trusted, tentative (flagged at write time by deterministic screening rules), or quarantined (condemned by the owner). Tentative memories are always delivered marked — agents see the flag and decide. Quarantined memories are excluded from context, injection, quotes and oracle queries, while their on-chain fingerprint remains as immutable evidence. All read responses include a trust field.

bash
curl -X POST https://api.chainmemory.ai/v1/memories/487/trust \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"action": "quarantine"}'

Actions: approve → trusted · quarantine → quarantined · tentative → tentative. Response includes the previous status for auditability.

bash
curl https://api.chainmemory.ai/v1/memory/485/forensics \
  -H "x-api-key: your-api-key"

Timeline events: born, trust, batched, checkpoint_anchored, recalled (every read, with endpoint and query), injected (every delivery, with target platform), cited_as_evidence (Project Brain items citing this memory). Includes cross-checked counters and on-chain anchoring proof. This answers the forensic question: which memory caused what, when did it enter, who read it, and where did it go.

bash
curl -X POST https://api.chainmemory.ai/v1/project/myproject/state/rollback \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"to_version": 35}'

Append-only restore: rolling back to version N never deletes anything — it creates a new version whose content is byte-identical to N. Since hashes are computed over canonical bytes, the new version's hash equals the hash already anchored on-chain for N: the faithfulness of the restoration is a mathematical fact, not a promise. Before restoring, the server re-computes the stored content's hash and refuses (HTTP 409) if it does not match — corruption can never be restored. History is never mutated.