Coppermind Docs
Public docs only
HomeApp
DocsReference

API Reference

Managed cloud memory routes for the SDK, the advanced cloud MCP package, and dashboard operations.

apigatewayreferenceroutes

This page documents the managed cloud route family. In local-first mode, Coppermind exposes the same logical memory operations without requiring cloud credentials.

Memory operations

The stable logical operations are:

  • ingest
  • search
  • inspect
  • stats
  • delete

The cloud route family maps those operations onto HTTP.

SDK and advanced cloud MCP routes

These routes are used by the SDK and the advanced direct-cloud MCP package. They require API key auth.

MethodRoutePurpose
GET/v1/memoryRetrieve memory context
POST/v1/memoryRetrieve memory context with a request body
GET/v1/memory/searchSearch memory
POST/v1/ingestIngest memory
POST/v1/memory/deleteDelete memory records
GET/v1/statsGet counts and token estimates

Dashboard-only routes

These routes are used by the dashboard and require dashboard auth.

MethodRoutePurpose
GET/v1/memoriesList memory fragments for the dashboard
GET/v1/memories/:idGet one fragment
POST/v1/memory-management/deleteDelete from the dashboard surface
GET/v1/memory-management/statsDashboard stats
POST/v1/byodb/ingestBYODB direct ingest

Authentication

API-key requests use:

Authorization: Bearer ***

The API key identifies the tenant. A logical userId can still scope memory inside that tenant.

Example requests

Search

GET /v1/memory/search?query=release%20checklist&limit=5

Ingest

{
  "userId": "default",
  "data": [
    {
      "content": "Release after smoke tests pass.",
      "tags": ["release", "ops"]
    }
  ]
}

Delete

{
  "userId": "default",
  "episodeIds": ["ep_123"]
}

Send that delete payload to POST /v1/memory/delete.

Example response shapes

Memory retrieval returns fragments:

{
  "userId": "default",
  "fragments": [
    {
      "id": "mem_123",
      "content": "Release after smoke tests pass.",
      "tags": ["release", "ops"],
      "createdAt": "2026-04-09T00:00:00.000Z"
    }
  ],
  "total": 1
}

Stats returns lightweight aggregates:

{
  "totalEpisodes": 12,
  "totalTokens": 1480,
  "oldestAt": "2026-04-01T00:00:00.000Z",
  "newestAt": "2026-04-09T00:00:00.000Z"
}

Common failure semantics

CodeMeaning
400Malformed request
401 / 403Auth, entitlement, or plan failure
429API key creation blocked — user already has 3 keys (key_limit_reached)
503Backend reachable but not ready for memory
502BYODB backend failed

Common storage-related errors include:

  • memory_backend_not_configured
  • memory_backend_unavailable
  • byodb_query_failed

Where to go next

Back to docs index