Documentation Index
Fetch the complete documentation index at: https://docs.crewship.ai/llms.txt
Use this file to discover all available pages before exploring further.
Memory
Read-only endpoint for the memory health dashboard. Backed by internal/consolidate.ComputeHealth. The five aggregate queries it runs are cheap, so the handler recomputes on every request rather than reading the persisted memory_health_snapshots table — those snapshots exist for time-series plots, not real-time reads.
See Episodic memory — health scoring for the formula and operator interpretation.
Get health snapshot
GET /api/v1/memory/health
| Param | Type | Description |
|---|
crew_id | string | Optional. Crew ID (not slug) to scope the score to a single crew. Omit for workspace-aggregate. The ID is validated against the caller’s workspace via crewBelongsToWorkspace; a foreign ID returns 404. |
200 OK
{
"workspace_id": "ws_123",
"crew_id": "",
"computed_at": "2026-04-30T11:42:18.018Z",
"overall": 77.4,
"metrics": {
"freshness": 83.1,
"coverage": 62.0,
"coherence": 80.2,
"efficiency": 77.4,
"reachability": 78.0
},
"details": {
"indexed_entries": 1284,
"embeddable_entries": 1390
}
}
| Field | Type | Description |
|---|
workspace_id | string | Echo of the session’s workspace. |
crew_id | string | Echo of the request’s crew_id (empty for workspace-aggregate). |
computed_at | string (RFC3339) | When this response was computed. The handler always recomputes, so this is now. |
overall | number | Weighted composite, 0–100. Formula: 0.25·freshness + 0.25·coverage + 0.20·coherence + 0.15·efficiency + 0.15·reachability. |
metrics.* | number | Each metric, 0–100. See the guide for what each one measures. |
details | object | Free-form supplementary data (entry counts, embedding model, recent compaction stats, …). Schema is not stable across versions; consume defensively. |
band field — clients categorise locally:
| Band | Range |
|---|
| Red | overall < 50 |
| Yellow | 50 ≤ overall < 75 |
| Green | overall ≥ 75 |
internal/cli colour helpers) and the FE follows.
Errors:
| Status | Condition |
|---|
| 401 | No workspace context in session. |
| 404 | crew_id set and not in caller’s workspace. |
| 500 | Compute failure — propagated from ComputeHealth. |
Memory versions audit trail
The HTTP mirror of crewship memory log/show. Workspace is anchored from the session — query strings never carry workspace_id, so a cross-workspace probe can’t smuggle a foreign id through. Restore (POST /api/v1/memory/versions/{sha}/restore) is documented separately on the Admin reference because it requires OWNER/ADMIN and mutates canonical state; the two read endpoints below are MEMBER+.
GET /api/v1/memory/versions
Returns the audit chain for one canonical memory path, newest-first.
Auth: required + workspace context.
Query parameters:
| Param | Type | Default | Description |
|---|
path | string | — | Required. Canonical memory path (e.g. agent:martin/AGENT.md). 400 when omitted. |
limit | integer | 20 | Max rows to return. Any positive integer is accepted; non-positive or non-numeric values fall back to the default. |
200 OK
{
"path": "agent:martin/AGENT.md",
"count": 2,
"entries": [
{
"id": "mv_01HZA...",
"sha256": "abc...",
"bytes": 1284,
"written_at": "2026-05-18T08:30:00Z",
"written_by": "audit-watcher",
"parent_sha": "def..."
},
{
"id": "mv_01HZ9...",
"sha256": "def...",
"bytes": 1180,
"written_at": "2026-05-17T22:11:48Z",
"written_by": "audit-watcher",
"parent_sha": null
}
]
}
| Field | Type | Description |
|---|
path | string | Echo of the request’s path. |
count | integer | len(entries) — handy when paging is bounded by limit. |
entries[] | array | Newest-first list of memory_versions rows for this path in the caller’s workspace. |
| Status | Condition |
|---|
400 | Missing path query parameter. |
401 | No workspace context in the session. |
500 | Underlying memory.LogVersions query failed. |
GET /api/v1/memory/versions/{sha}
Returns the raw blob bytes for one historical version. Pipe-friendly: the body is the historical content, metadata travels in headers so a CLI pipe to a file produces the exact bytes that were written.
Auth: required + workspace context.
Path parameters:
| Param | Description |
|---|
sha | Content sha256 from memory_versions.sha256. |
| Param | Type | Description |
|---|
path | string | Required. The canonical memory path the sha was written under. The same sha can be paired with different paths if two paths happen to converge on identical content. |
200 OK — raw bytes, Content-Type: application/octet-stream.
| Header | Description |
|---|
X-Memory-Version-Sha | Echo of the path’s sha. |
X-Memory-Version-Bytes | Body length (matches memory_versions.bytes). |
| Status | Condition |
|---|
400 | Missing sha path segment or missing path query parameter. |
401 | No workspace context. |
404 | No memory_versions row matches (workspace_id, path, sha) — cross-workspace lookups masked as 404 to avoid leaking row existence. |
500 | Read failure from the underlying blob store. |
The restore endpoint (POST /api/v1/memory/versions/{sha}/restore) is OWNER/ADMIN-only and applies extra server-side path confinement to refuse canonical targets outside the configured memory root. See the Admin reference for the full mutation surface.
Tenancy
workspace_id is always pulled from the session — never accepted as a query parameter or body field.crew_id, when set, is validated via crewBelongsToWorkspace (same helper as the Paymaster API). Cross-tenant lookups return 404.
