REST

Referência da API

O MemoryFirst expõe uma API REST nativa. A mesma memória é acessível por MCP (veja o guia de MCP).

URL base

https://api.memoryfirst.ai/v1

Autenticação

Todas as requisições exigem uma chave de API no cabeçalho Authorization :

curl https://api.memoryfirst.ai/v1/experts/{expertId}/query \
  -H "Authorization: Bearer mf_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"question": "What did we promise this client?", "k": 8}'

Endpoints

  • POST /v1/experts/{id}/sources: processar uma nova fonte
  • POST /v1/experts/{id}/query: consultar a memória com citações
  • GET /v1/experts: listar especialistas no seu workspace
  • POST /v1/experts: criar novo especialista
  • GET /v1/usage: estatísticas de uso do período atual
  • POST /v1/brain/event: registra um evento do cérebro (decisão, bloqueio, deploy, contato com cliente). Responde 202 com o id do evento.

Novas tentativas sem duplicatas: Idempotency-Key

Se o seu cliente tenta de novo após uma queda de rede ou reenvia uma caixa de saída, envie o cabeçalho Idempotency-Key em POST /v1/brain/event com uma chave sua (1 a 255 caracteres ASCII imprimíveis, sem espaços). A mesma chave do mesmo workspace devolve, durante 24 horas, o evento já criado com 200 e idempotent_replay: true, e não cria outro.

curl https://api.memoryfirst.ai/v1/brain/event \
  -H "Authorization: Bearer mf_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: outbox-2026-11-13-0042" \
  -H "Content-Type: application/json" \
  -d '{"project": "my-project", "event_type": "decision_taken", "title": "Move blobs to R2"}'

Se o corpo repetido for diferente, devolve-se o evento original sem alterações e payload_differs: true. A mesma chave com outro projeto responde 422; enquanto a primeira requisição ainda está em andamento, 409 (tente novamente com a mesma chave). Com a ferramenta MCP mf_record, passe o argumento idempotency_key.

Especificação OpenAPI 3.1 completa em breve. Escreva para hola [at] memoryfirst.ai para acesso antecipado.