API REST

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
{
  "project": "chainmemory",
  "version": 3,
  "state": {
    "context": {
      "summary": "Plataforma de memoria IA con verificación blockchain",
      "goals": ["Memoria persistente cross-model", "Pista de auditoría criptográfica"]
    },
    "decisions": [
      {
        "id": "d001",
        "title": "Usar Clique PoA",
        "statement": "Consenso PoA para blockchain soberana",
        "status": "confirmed",
        "evidence": ["#12", "#45"]
      }
    ],
    "milestones": [
      {
        "id": "m001",
        "title": "MVP API desplegado",
        "status": "completed",
        "date": "2026-04-15",
        "evidence": ["#5", "#18"]
      }
    ],
    "risks": [
      {
        "id": "r001",
        "title": "Latencia del motor de consolidación a escala",
        "severity": "medium",
        "status": "open",
        "mitigation": "Evaluar modelos más grandes al escalar infra",
        "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
  }
}

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.