Memory API (REST)

The MCP tools are the recommended way for an agent to reach memory, but every tool has a plain HTTP equivalent on the REST API. Use it from scripts, backends or any client that isn't MCP-aware.

Basics

Base URL: https://api.markdb.cloud
Auth: Authorization: Bearer mk_live_... (see Authentication). Reads need read scope; writes need write.
Bodies: JSON. Unknown fields are rejected, so send only documented keys.
Scoping: all requests are attributed to the key's (account, workspace, agent), which is (tenant, app, agent) in API terms.

Search and recall

POST /v1/memory/search (alias: POST /v1/recall) runs hybrid search over your memory, the exact operation behind the memory_search tool.

Request (all fields except query optional):

{
  "query": "postgres shm exhaustion fix",
  "mode": "hybrid",            // text | vector | hybrid (default)
  "scope": "agent_history",    // agent_history (default) | current_chat | current_session
  "artifact_kind": "session_summary",
  "scope_type": "session",     // day | hour | session | turn
  "start_time": "2026-05-01T00:00:00Z",
  "end_time": "2026-06-01T00:00:00Z",
  "min_importance": 0.3,
  "chat_key": "…",
  "session_id": "…",
  "limit": 5
}

Response:

{
  "query": "postgres shm exhaustion fix",
  "scope": "agent_history",
  "items": [
    {
      "ref": { "type": "page", "id": "8f3c…" },
      "artifact_kind": "session_summary",
      "summary_text": "Fixed Postgres shared-memory exhaustion by …",
      "key_facts": ["shm_size raised to 1g", "…"],
      "decisions": [{ "…": "…" }],
      "scores": { "…": 0.82 },
      "provenance": { "…": "…" },
      "snippet": "…"
    }
  ]
}

Each item's ref ({type, id}) and page_id drive drill-down, exactly like the MCP workflow.

GET /v1/memory/detail/{pageID} returns the compact detail for a page: summary_text, key_facts, decisions, open_questions, citations and child_summaries (each with a preview, page_id, start_time and session_id). Add ?raw=true for the full raw page.

curl https://api.markdb.cloud/v1/memory/detail/8f3c… \
  -H "Authorization: Bearer mk_live_xxx"

Recent pages

GET /v1/recent lists recent pages. Query params: session_id, object_id, limit, include_broadcast=true and scope_type + scope_id to include a broadcast scope. Returns { "items": [...] }.

Raw events by time

POST /v1/events/list returns raw conversation events in a time window. Use it for exact wording, code or IDs summaries don't keep.

{
  "start_time": "2026-05-30T10:00:00Z",
  "end_time": "2026-05-30T11:00:00Z",
  "session_id": "…",   // optional
  "limit": 100          // default 100, max 500
}

Full endpoint map

Area	Endpoints
Search & recall	`POST /v1/memory/search`, `POST /v1/recall`, `POST /v1/search`, `GET /v1/memory/detail/{pageID}`, `GET /v1/summaries/{pageID}`
Recent & context	`GET /v1/recent`, `POST /v1/context/hydrate`
Events	`GET /v1/events`, `POST /v1/events`, `POST /v1/events/list`
Sessions	`POST /v1/sessions`, `GET /v1/sessions/lookup`, `POST /v1/sessions/ensure`, `GET /v1/sessions/{id}`, `GET /v1/sessions/{id}/events`, `POST /v1/sessions/{id}/end`, `GET /v1/sessions/{id}/summary`
Objects & pages	`POST /v1/objects`, `GET /v1/objects/lookup`, `POST /v1/objects/{id}/pages`, `GET /v1/pages/{id}`, `GET /v1/objects/{id}/head`, `POST /v1/objects/{id}/pin`
Durable memory	`POST /v1/promotions`, `POST /v1/checkpoints`, `POST /v1/checkpoints/{id}/restore`, `POST /v1/overlays`
Broadcasts	`POST /v1/broadcasts`, `GET /v1/broadcasts`

REST vs MCP

MCP tool	REST endpoint
`memory_search`	`POST /v1/memory/search`
`memory_get_detail`	`GET /v1/memory/detail/{pageID}`
`memory_list_events`	`POST /v1/events/list`
`memory_get`	`GET /v1/pages/{id}`, `GET /v1/events`, … (by reference type)
`memory_append`	`POST /v1/events`
`memory_pin`	`POST /v1/objects/{id}/pin`
`memory_hydrate_context`	`POST /v1/context/hydrate`
`broadcast_publish` / `broadcast_list`	`POST` / `GET /v1/broadcasts`

Account, workspace and agent management is separate

This is the data plane (memory). Creating workspaces, agents and API keys is a control-plane action done in the dashboard with your signed-in session, not with an mk_live_ key. See Authentication.