REST API

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
{
  "project": "chainmemory",
  "version": 3,
  "state": {
    "context": {
      "summary": "AI memory platform with blockchain verification",
      "goals": ["Persistent cross-model memory", "Cryptographic audit trail"]
    },
    "decisions": [
      {
        "id": "d001",
        "title": "Use Clique PoA",
        "statement": "PoA consensus for sovereign blockchain",
        "status": "active",
        "evidence": ["#12", "#45"]
      }
    ],
    "milestones": [
      {
        "id": "m001",
        "title": "MVP API deployed",
        "status": "completed",
        "date": "2026-04-15",
        "evidence": ["#5", "#18"]
      }
    ],
    "risks": [
      {
        "id": "r001",
        "title": "Consolidation engine latency at scale",
        "severity": "medium",
        "status": "open",
        "mitigation": "Optimize consolidation batch size and caching",
        "evidence": ["#33"]
      }
    ],
    "stack": [
      {
        "name": "Node.js",
        "category": "runtime",
        "evidence": ["#2"]
      },
      {
        "name": "Geth (Clique PoA)",
        "category": "blockchain",
        "evidence": ["#12"]
      }
    ]
  },
  "state_hash": "a7b3c9f2...",
  "anchor": {
    "status": "anchored",
    "tx_hash": "0xce55a800...",
    "block_number": 123539
  }
}

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.