Caura / docs
API Reference

Stats

GET /api/v1/memories/stats — aggregate counts (PR #64); also GET /api/stats — public counters.

The caura_stats MCP tool added in PR #64 calls compute_memory_stats(), which is shared with the REST handler below. Both surfaces return {total, by_type, by_agent, by_status, scope} (REST omits scope).

Memory stats (auth)

GET
/api/v1/memories/stats

Authorization

APIKeyHeader
headerX-API-Key<token>

Query Parameters

tenant_id?string|null
fleet_id?string|null
agent_id?string|null
scope?|

Opt-in aggregate scope, mirroring the MCP/plugin contract. 'agent' = your own memories (trust >= 1); 'fleet' = cross-agent within a fleet (own fleet trust >= 1, a different fleet trust >= 2); 'all' = tenant-wide (trust >= 2). Omit for the historical behaviour. Unrelated to visibility=scope_*, which is the tier a writer stamped on the row rather than a read breadth.

memory_type?string|null
status?string|null
run_id?string|null
exclude_memory_types?array<string>|null
created_after?|null
created_before?|null
include_deleted?Include Deleted

Also count soft-deleted rows. Honoured for tenant credentials; an agent credential needs trust >= 3, below which it is ignored (as on MCP caura_stats).

Defaultfalse

Response Body

Successful Response

application/json
  1. response
total*Total

Live (non-deleted) memory count in scope.

by_type*
by_agent*
by_status*
by_tenant?|

Only for cross-tenant reads spanning more than one tenant.

deleted?|

Only when include_deleted=true.

total_including_deleted?|

Only when include_deleted=true.

pending?|

Background work still outstanding in this scope, from durable row markers. A row can count on more than one axis. Contradiction marks are applied after embed/enrich events and carry no durable marker, so allow a short grace period after settled flips.

settled?|

True when every pending count is zero once the stranded rows are set aside, or every count but embedding when embedding_configured is false. Wait for this before measuring a freshly ingested store, and check stranded: rows counted there are unembedded, so search finds them by keyword only.

stranded?|

Pending rows nothing will come back for, which settled does not wait on.

embedding_configured?|

False when no embedding provider is configured for the tenant: rows are stored without embeddings and searched by keyword only, so pending.embedding counts rows that will stay unembedded until a provider is set and they are re-embedded.

Example Request
curl -X GET 'https://example.com/api/v1/memories/stats'
Example Response
{  "total": 0,  "by_type": {    "property1": 0,    "property2": 0  },  "by_agent": {    "property1": 0,    "property2": 0  },  "by_status": {    "property1": 0,    "property2": 0  },  "by_tenant": {    "property1": 0,    "property2": 0  },  "deleted": 0,  "total_including_deleted": 0,  "pending": {    "embedding": 0,    "enrichment": 0,    "fanout": 0  },  "settled": true,  "stranded": {    "embedding": 0  },  "embedding_configured": true}

Public stats

A lightweight counters endpoint used by the marketing-site status bar. Through the gateway, call it keyless at GET /api/stats; the versioned /api/v1/stats below sits behind the gateway's authenticated /api/v1/ route and needs an X-API-Key.

GET
/api/v1/stats

Response Body

Successful Response

application/json
  1. response
[key: string]?integer
Example Request
curl -X GET 'https://example.com/api/v1/stats'
Example Response
{  "property1": 0,  "property2": 0}

Search

POST /api/v1/search — the same hybrid vector + keyword + entity ranking as Recall, returned as ranked memories without the LLM-written summary.

Keystones

GET / POST / DELETE /api/v1/keystones — mandatory governance rules.

On this page

Memory stats (auth)Public stats