Entities — HTTP API reference

Companion to the Entities overview — this page lists every HTTP endpoint that touches the entity layer. All endpoints require the standard Bearer token auth.

Extraction on save

Already documented in the Save endpoint reference. Pass metadata.extract_entities: true (or a BYOK key) and the response will include populated metadata.entities[].

GET /api/entities

List or fuzzy-search canonical entities.

Query parameters:

Response: array of entity rows.

[
  {
    "id": "a1b2c3d4-...",
    "display_name": "John Smith",
    "entity_type": "person",
    "aliases": ["John Smith", "John W. Smith"],
    "mention_count": 12,
    "first_seen_at": "2026-04-01T14:00:00Z",
    "last_seen_at": "2026-05-17T22:15:00Z",
    "metadata": {},
    "score": 0.94
  }
]

score is only present when q is provided.

GET /api/entities/:id

Fetch one canonical entity.

Query parameters:

Returns the same shape as the list endpoint plus, optionally, a memories: [...] array.

PATCH /api/entities/:id

Rename / retype / edit aliases on a canonical entity. Body fields are all optional; only the provided ones change.

{
  "display_name": "John W. Smith",
  "entity_type": "person",
  "aliases": ["John Smith", "John W. Smith", "JWS"],
  "metadata": { "wikidata_id": "Q12345" }
}

Metadata semantics: pass an object to merge into existing metadata; pass null to clear it.

Returns the updated entity row.

DELETE /api/entities/:id

Delete a canonical entity. Cascades to all memory_entities edges pointing at it. The memories themselves are untouched — only the entity-link metadata is removed.

Returns { ok: true } on success, 404 if not found.

GET /api/memories?entity=<canonical_id>

Filter memories by canonical entity. Stacks with every other /api/memories query parameter (q, namespace, created_after, etc).

Implementation: an EXISTS subquery against memory_entities. Returns the standard memory row shape.

POST /api/entities/backfill

Retroactively extract entities for existing memories that don't have them yet.

{
  "namespace": "default",
  "since": 1700000000000,
  "until": 1779000000000,
  "limit": 100,
  "force": false,
  "dry_run": false
}

Returns a summary:

{
  "processed": 87,
  "extracted": 412,
  "resolved": 412,
  "skipped": 13,
  "errors": 0,
  "memories": [
    { "id": "...", "namespace": "default", "entities_found": 5, "canonical_ids": ["...", "..."] }
  ]
}

Uses the server's ANTHROPIC_API_KEY or OPENAI_API_KEY env var. BYOK is not supported on backfill since it's not a per-call operation.

Cost: ~$0.001 per processed memory at Haiku pricing. Run in batches.

SDK methods

The TypeScript SDK (@mnueron/sdk) gained these methods in the same release. Python and C# SDK updates ship next.

import { Mnueron } from "@mnueron/sdk";
const m = new Mnueron({ apiKey: "mnu_..." });

// Save with entity extraction
await m.save({
  content: "...",
  metadata: { extract_entities: true },
});

// List entities
const entities = await m.listEntities({ q: "john", type: "person" });

// Get entity + linked memories
const entity = await m.getEntity(id, { includeMemories: true });

// Filter memories by entity
const mems = await m.search({ entity_id: id });

// Backfill
const summary = await m.backfillEntities({ limit: 200 });