RetainDB
API

Browse docs

Agent Memory Bus

Tap to expand

Memory Router

Contribute

APIUpdated 2026-05-25

Agent Memory Bus API

REST routes for agent events, context bundles, handoffs, and handoff resume.

Applies to: RetainDB API v1

Base URL:

text
https://api.retaindb.com

All routes require Authorization: Bearer $RETAINDB_API_KEY or X-API-Key.

POST /v1/agent/memory/events

Record an agent work event.

bash
curl -X POST "https://api.retaindb.com/v1/agent/memory/events" \
  -H "Authorization: Bearer $RETAINDB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "app",
    "agent_id": "planner",
    "task_id": "checkout-redesign",
    "type": "decision",
    "summary": "Use hosted checkout in v1.",
    "details": {
      "reason": "Lower implementation risk."
    },
    "salience": 0.9,
    "write_mode": "async"
  }'

POST /v1/agent/memory/context

Return an agent-ready context bundle for a task.

bash
curl -X POST "https://api.retaindb.com/v1/agent/memory/context" \
  -H "Authorization: Bearer $RETAINDB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "app",
    "agent_id": "builder",
    "task_id": "checkout-redesign",
    "query": "What should I know before implementation?",
    "top_k": 8
  }'

POST /v1/agent/memory/handoffs

Create a handoff packet from one agent to another.

bash
curl -X POST "https://api.retaindb.com/v1/agent/memory/handoffs" \
  -H "Authorization: Bearer $RETAINDB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "app",
    "from_agent_id": "planner",
    "to_agent_id": "builder",
    "task_id": "checkout-redesign",
    "summary": "Build hosted checkout.",
    "context": "Use hosted checkout. Keep custom payment UI out of v1."
  }'

GET /v1/agent/memory/handoffs/:handoffId

Fetch a handoff packet.

bash
curl "https://api.retaindb.com/v1/agent/memory/handoffs/handoff_123" \
  -H "Authorization: Bearer $RETAINDB_API_KEY"

POST /v1/agent/memory/handoffs/:handoffId/resume

Resume or fork a handoff into a new session.

bash
curl -X POST "https://api.retaindb.com/v1/agent/memory/handoffs/handoff_123/resume" \
  -H "Authorization: Bearer $RETAINDB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "builder-session-001"
  }'

Response shape

Successful responses include the created or retrieved event, context, or handoff fields plus trace metadata when available.

Example event response:

json
{
  "success": true,
  "event_id": "evt_...",
  "memory_job_id": "job_...",
  "trace_id": "trc_..."
}

Errors use RetainDB's standard error envelope:

json
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing API key or Authorization header"
  },
  "trace_id": "..."
}

Idempotency

For retryable event and handoff writes, send an Idempotency-Key header from your job or agent runtime. Use a deterministic value such as ${taskId}:${agentId}:${eventId}.

Scope isolation

Always send the same project, agent_id, and task_id for a shared task. Add user_id and session_id when the task is also tied to a specific user or run.

Next: SDK Agent Task API.

Was this page helpful?

Your feedback helps us prioritize docs improvements weekly.