Scope entities
List, inspect, and remove the user, agent, and run scopes derived from active memories.
FishMem exposes user_id, agent_id, and run_id as first-class structural
scope entities. The entity API is a live aggregation over canonical,
non-deleted memories; it does not maintain a second entity table that can drift.
These are memory owners, not people, organizations, places, or concepts extracted into the named-entity graph. A memory containing all three scope fields contributes to all three scope entities.
app_id is intentionally absent. A FishMem project/workspace is the
application namespace and API-key security boundary. Adding another app scope
inside it would duplicate that boundary.
List entities
GET /v1/entities
| Field | Type | Required | Description |
|---|---|---|---|
type | user, agent, or run | no | Return only one structural scope type |
cursor | string | no | Opaque cursor from the previous page |
limit | integer | no | Page size, 1–100 (default 50) |
curl "https://fishmem.com/v1/entities?type=user&limit=50" \
-H "Authorization: Bearer fm_..."{
"results": [
{
"id": "alex",
"type": "user",
"total_memories": 12,
"created_at": "2026-07-01T09:00:00.000Z",
"updated_at": "2026-07-31T12:30:00.000Z"
}
],
"next_cursor": null
}created_at is the earliest active memory timestamp in that scope;
updated_at is the latest. Pages use stable newest-first ordering. Treat the
cursor as opaque and stop when next_cursor is null.
Get one entity
GET /v1/entities/{type}/{id}
curl "https://fishmem.com/v1/entities/user/alex" \
-H "Authorization: Bearer fm_..."Path segments must be URL encoded. A scope with no active canonical memories
returns 404 SCOPE_ENTITY_NOT_FOUND.
Remove an entity's memories
DELETE /v1/entities/{type}/{id}
This removes every active memory matching that one structural scope from recall and records deletion tombstones in canonical history. It does not purge the whole project or delete named graph entities independently.
curl -X DELETE "https://fishmem.com/v1/entities/user/alex" \
-H "Authorization: Bearer fm_..." \
-H "Idempotency-Key: delete-user-alex-v1"{
"id": "alex",
"type": "user",
"deleted_memories": 12
}Idempotency-Key is required. The first call freezes its exact target set;
replaying the key returns the original result and cannot delete matching
memories written later. A new key after the scope has disappeared returns
404. One synchronous removal can target at most 25,000 memories.
All entity reads and removals are free. They still require a valid project API key and remain isolated to that key's project/workspace namespace.