API REST

Contrato legible por máquinas: OpenAPI 3.1. Orientación para LLMs: api.chainmemory.ai/llms.txt.

Autenticación

Todas las llamadas a la API requieren autenticación mediante API Key en el header:

HTTP
x-api-key: tu-api-key

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

Memorias

bash
curl -X POST https://api.chainmemory.ai/v1/memory \
  -H "x-api-key: tu-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "summary": "Decidimos usar PostgreSQL en vez de MongoDB",
    "category": "decision",
    "importance": 8,
    "platform": "manual"
  }'

javascript
const res = await fetch('https://api.chainmemory.ai/v1/memory', {
  method: 'POST',
  headers: {
    'x-api-key': 'tu-api-key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    summary: 'Decidimos usar PostgreSQL en vez de 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': 'tu-api-key'},
    json={
        'summary': 'Decidimos usar PostgreSQL en vez de MongoDB',
        'category': 'decision',
        'importance': 8,
        'platform': 'api'
    }
)
memory = res.json()
# {'id': 207, 'hash': '0x4f2a...', 'memory_number': 42}

Parámetros

Proyectos

Respuesta (recortada)
{
  "project": "sistema-pagos",
  "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": "Revisión PCI antes de abrir a los primeros tenants",
    "decisions": [
      { "id": "dec_0002", "title": "PostgreSQL con RLS para multi-tenancy",
        "statement": "La seguridad por fila saca el filtrado por tenant de la capa de aplicación",
        "status": "confirmed", "superseded_by": null,
        "evidence_root": "0x9a41…c07e", "created_version": 2, "updated_version": 3 }
    ],
    "milestones": [
      { "id": "mil_0001", "title": "Schema de BD", "status": "done",
        "evidence_root": "0x5b2d…81fa", "created_version": 1, "updated_version": 2 }
    ],
    "risks": [
      { "id": "risk_0001", "title": "Performance de RLS con 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" }
  }
}

Siempre la versión más reciente; requiere la API key del dueño. Los valores de severidad son low, med y high.

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

Con task, la respuesta trae task en lugar de since. Siempre la versión más reciente; requiere la clave del dueño o una clave de organización con acceso al proyecto (una clave de proyecto solo lee su propio proyecto).

Inyección

Respuesta

El endpoint devuelve las memorias seleccionadas formateadas para inyección. Cada memoria llega con su número visible para el usuario y una referencia de verificación, de modo que una IA puede citar la memoria exacta detrás de cualquier afirmación — y vos podés rastrear esa cita hasta su evidencia on-chain. Una afirmación deja de ser "confiá en mí" y pasa a ser "acá está la memoria, verificala vos mismo."

Verificación

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

Códigos de error

Equivalencia de funciones: Extensión ↔ MCP ↔ API

No todas las funciones están disponibles en todos los métodos de integración. Esta tabla muestra qué hay disponible dónde:

Confianza y Gobierno

Cada memoria lleva un estado de confianza desde el momento en que se escribe: trusted, tentative (marcada al escribirse por reglas de evaluación deterministas), o quarantined (condenada por el dueño). Las tentative siempre se entregan marcadas — el agente ve la marca y decide. Las quarantined se excluyen de context, inject, quotes y consultas al oracle, mientras su huella on-chain permanece como evidencia inmutable. Todas las respuestas de lectura incluyen el campo trust.

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

Acciones: approve → trusted · quarantine → quarantined · tentative → tentative. La respuesta incluye el estado anterior para auditoría.

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

Eventos: born, trust, batched, checkpoint_anchored, recalled (cada lectura, con endpoint y consulta), injected (cada entrega, con plataforma destino), cited_as_evidence (ítems del Project Brain que citan esta memoria). Incluye contadores con verificación cruzada y prueba de anclaje on-chain. Responde la pregunta forense: qué memoria causó qué, cuándo entró, quién la leyó y a dónde llegó.

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

Restauración append-only: volver a la versión N jamás borra nada — crea una versión nueva cuyo contenido es byte-idéntico a N. Como los hashes se computan sobre bytes canónicos, el hash de la versión nueva es igual al ya anclado on-chain para N: la fidelidad de la restauración es un hecho matemático, no una promesa. Antes de restaurar, el servidor recomputa el hash del contenido almacenado y se niega (HTTP 409) si no coincide — la corrupción nunca puede restaurarse. La historia jamás se muta.