Journal - Crewship

The Crew Journal is the canonical, append-only event log for a workspace. These endpoints let you read entries (with rich filtering), stream them live over SSE, count a filtered set, look up display metadata for journal cards, and set the one operator-mutable field — the priority marker. See the Crew Journal guide for the data model and entry-type catalog.

Every endpoint requires authentication and is workspace-scoped via the session context. workspace_id is always pulled from the session, never from query params — cross-workspace reads are impossible.

The journal is append-only at the entry level — there is no endpoint that creates, mutates, or deletes a journal row’s payload; entries come from backend code emitting via journal.Writer. The one writable surface is the operator-facing priority marker (POST /api/v1/journal/{id}/priority), which updates only the priority column on an existing row and emits its own memory.priority_changed audit entry.

Endpoints

Method	Endpoint	Purpose
GET	`/api/v1/journal`	List entries with filters and pagination
GET	`/api/v1/journal/stream`	Stream entries live over Server-Sent Events
GET	`/api/v1/journal/{id}`	Get a single entry by ID
GET	`/api/v1/journal/count`	Count entries matching a filter
POST	`/api/v1/journal/{id}/priority`	Set an entry’s priority marker
GET	`/api/v1/journal/lookup`	Workspace lookup table for card enrichment
GET	`/api/v1/journal/spend`	Cost rollup — by agent, by routine, top spenders

List entries

The primary read surface — page through entries with a rich, AND-combined filter set.

GET /api/v1/journal

Query parameters: All filters are AND-combined; CSV-valued ones expand to IN (?, ?, ...) predicates.

Param	Type	Description
`crew_id`	string	Filter by a single crew — id, slug or display name (see References).
`agent_id`	string	Filter by a single agent — id, slug or display name (see References).
`mission_id`	string	Only one issue — its mission id or its identifier (`ENG-4`); resolved per workspace, an unknown reference matches nothing.
`trace_id`	string	Narrow to one run’s spans (`trace_id` == run id). Reaches ad-hoc agent runs only — a routine run never sets `trace_id`.
`run_id`	string	Everything that happened during one run, whichever engine ran it: matches `trace_id` (ad-hoc agent runs), `actor_id` and `payload.run_id` (routine runs), OR-combined. Prefer this over `trace_id`, which reaches agent runs only. AND-combines with every other filter.
`crew_ids`	string	CSV multi-crew filter — takes precedence over `crew_id` when non-empty. Each value is resolved the same way.
`agent_ids`	string	CSV multi-agent filter — takes precedence over `agent_id` when non-empty. Each value is resolved the same way.
`entry_type`	string	CSV of entry types (e.g. `peer.escalation,keeper.decision`).
`exclude_entry_type`	string	CSV of entry types to exclude (`NOT IN`). Useful for hiding `container.metrics` noise. AND-combines with `entry_type`.
`severity`	string	CSV of `info`, `notice`, `warn`, `error`.
`actor_type`	string	CSV of `agent`, `user`, `system`, `keeper`, `sidecar`, `orchestrator`.
`priority`	string	CSV of `normal`, `high`, `pin`, `permanent`. Invalid values → 400.
`since`	string	RFC3339 lower bound on `ts`.
`until`	string	RFC3339 upper bound on `ts`.
`q`	string	FTS5 search across `summary` + `payload` (migration 55). Bounded to 200 chars; tokenised before MATCH (see Free-text search); AND-combined with structural filters.
`cursor`	string	Opaque pagination token from a prior response.
`limit`	integer	1-500, default 100.

Response: 200 OK

{
  "entries": [
    {
      "id": "j_a1b2c3d4e5f60718",
      "workspace_id": "ws_123",
      "crew_id": "crw_backend",
      "agent_id": "agt_viktor",
      "mission_id": "MIS-42",
      "ts": "2026-04-17T10:23:41.000Z",
      "entry_type": "peer.escalation",
      "severity": "warn",
      "priority": "normal",
      "actor_type": "agent",
      "actor_id": "agt_viktor",
      "summary": "escalating DB migration to eva",
      "payload": { "escalation_reason": "unsure about schema impact" },
      "trace_id": "0af7651916cd43dd8448eb211c80319c"
    }
  ],
  "next_cursor": "2026-04-17T10:23:41.000Z|j_a1b2c3d4e5f60718",
  "count": 1
}

Field	Type	Description
`entries`	array	Page of entries, newest first.
`entries[].id`	string	`j_<16-hex>` stable identifier.
`entries[].ts`	string	RFC3339Nano (milli precision on write).
`entries[].entry_type`	string	See type catalog.
`entries[].severity`	string	`info`, `notice`, `warn`, or `error`.
`entries[].priority`	string	Always present: `normal`, `high`, `pin`, or `permanent`.
`entries[].actor_type`	string	`agent`, `user`, `system`, `keeper`, `sidecar`, `orchestrator`.
`entries[].summary`	string	Human-readable one-liner.
`entries[].payload`	object?	Typed payload, shape varies by entry_type. Omitted when empty.
`entries[].refs`	object?	Cross-entry links (`parent_entry_id`, `approval_id`, …). Omitted when empty.
`entries[].trace_id`	string?	W3C trace ID if telemetry is enabled.
`next_cursor`	string?	Pass back via `?cursor=` for the next page. Absent on the last page.
`count`	integer	Number of entries in this page.

Errors:

Status	Condition
400	Bad `since` / `until` / `limit` / `cursor`.
401	No workspace context.
500	DB error.

Free-text search

q is split on whitespace and the terms are AND-combined, so word order does not change the result set: q=session%20morgan returns exactly what q=morgan%20session returns. The last term is a prefix match — q=morg reaches morgan — while earlier terms match whole words. Each term is wrapped in an FTS5 phrase literal before it reaches SQLite, so operators inside the input (AND, OR, NOT, NEAR(...), *, column:, a bare ") are literal search text. They can neither restructure the query nor produce a 500. Terms containing no letter or digit are dropped; input made up entirely of such terms matches nothing rather than everything. The index covers summary and payload only — never entry_type.

References

crew_id, agent_id, crew_ids and agent_ids accept an id, a slug, or a display name (case-insensitive), resolved within the caller’s workspace. A value that resolves to nothing is used as-is against the id column, so an id whose row has since been deleted still reaches that entity’s history and a typo returns zero rows instead of silently widening the filter. A display name shared by several agents matches all of them.

Stream entries (SSE)

Live tail of the journal over Server-Sent Events, seeded with a recent batch then driven by the emitter’s flush notifications.

GET /api/v1/journal/stream

Server-Sent Events feed. Same query-param filters as List (limit is forced to 50 for the seed batch). Response headers:

Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive
X-Accel-Buffering: no

Event frames:

id: j_a1b2c3d4e5f60718
event: entry
data: {"id":"j_a1b2c3d4e5f60718","ts":"...","entry_type":"peer.escalation", ...}

: heartbeat

id: j_b2c3d4e5f6071829
event: entry
data: {...}

Seed: sends the most recent 50 entries matching filters, then goes live.
Wake-up: notification-driven. The writer signals the stream as soon as a batch commits, so a new entry is on the wire within milliseconds of the flush rather than on a fixed clock. A 20 s fallback ticker re-polls regardless, covering the case where a notification is missed or the wired emitter does not support them. (This used to be a flat 1 s poll per connected client, which is what older revisions of this page described.)
Heartbeat: : heartbeat comment every 15s to keep proxies from closing idle connections. Event handlers ignore comments.
Watermark: compound (ts, id) so bursts sharing a ms timestamp aren’t partially dropped.
Reconnect: clients send the SSE Last-Event-ID header; the server looks the entry up, treats its ts as the lower bound, and pages through the gap (up to 500 entries, 10 × 50-row pages) before going live. A disconnect that produced more than 500 matching entries truncates the older end of the gap and the server logs a warn — clients should reconcile by re-fetching /api/v1/journal?since=<last-known-ts> if they need a longer window. Any client that can set request headers should resume this way, and crewship journal --follow does: internal/cli/sse.go sets Last-Event-ID and followJournal threads it across its own bounded-backoff reconnects. A browser EventSource cannot set request headers. It sends Last-Event-ID only on its built-in automatic retry — a web client that closes the connection and constructs a new EventSource (which is what the web UI does, so it can control the backoff and stop polling on success) starts a fresh stream with no Last-Event-ID and must close its own gap with /api/v1/journal?since=<last-known-ts>. The UI’s journal hook does exactly that: while the stream is down it polls since on a rolling watermark, walking the cursor up to 4 pages per tick, and reports “Entries missing” if the backlog was deeper than that.

Errors:

Status	Condition
401	No workspace context.
400	Bad query parameters.
500	Streaming not supported by writer (ResponseWriter doesn’t implement `http.Flusher`).

Get single entry

Fetch one entry by ID, workspace-scoped.

GET /api/v1/journal/{id}

Path parameters: id is the journal entry ID. The request has no body; the workspace is always taken from the authenticated session. Returns one entry by ID, workspace-scoped. The response body is a single object whose shape matches one element of the entries[] array on List — same fields, same omitempty rules. Response: 200 OK

{
  "id": "j_a1b2c3d4e5f60718",
  "workspace_id": "ws_123",
  "ts": "2026-04-17T10:23:41.000Z",
  "entry_type": "peer.escalation",
  "severity": "warn",
  "priority": "normal",
  "actor_type": "agent",
  "summary": "escalating DB migration to eva",
  "payload": {"escalation_reason": "unsure about schema impact"},
  "trace_id": "0af7651916cd43dd8448eb211c80319c"
}

Errors:

Status	Condition
401	No workspace context.
404	Unknown entry, OR an entry that exists but belongs to another workspace. The shape matches “not found” — existence is not leaked across tenants.

Count entries

Total matching a filter, for result-set badges that stay honest under filter changes.

GET /api/v1/journal/count

Returns the total number of entries matching the same query parameters as List, ignoring cursor and limit. The UI uses this to render result-set badges that stay honest under filter changes — without it, the only way to know the total was to page through every entry. Query parameters: identical to List, except cursor and limit are silently ignored. Response: 200 OK

{ "total": 1283 }

Errors:

Status	Condition
400	Bad query parameter (`since`, `until`, `priority`, oversized `q`, …).
401	No workspace context.
500	DB error.

Set entry priority

The only operator-mutable surface — flag an entry’s importance without touching its payload.

POST /api/v1/journal/{id}/priority

Annotate one entry with an importance marker (normal, high, pin, permanent). Marker affects compaction and recall — see the Crew Journal guide.

Authorization: caller must hold OWNER or ADMIN on the workspace. MEMBER and below get 403.

Request body:

{ "priority": "permanent", "reason": "FX compliance constraint" }

Field	Type	Required	Description
`priority`	string	yes	One of `normal`, `high`, `pin`, `permanent`.
`reason`	string	no	Free-text rationale recorded on the audit emit. Empty is allowed but discouraged — the audit log is the only place the reason lives.

Response: 200 OK

{
  "id": "j_a1b2c3d4e5f60718",
  "priority": "permanent",
  "previous": "normal",
  "reason": "FX compliance constraint"
}

Side effect: writes a memory.priority_changed audit entry to the journal whose payload carries target_entry_id, previous_priority, new_priority, and the supplied reason. The audit emit is best-effort — the priority update is durable even if the audit write fails (a warning is logged in that case). Errors:

Status	Condition
400	Bad JSON body or unknown priority value.
401	No workspace context.
403	Caller is not OWNER/ADMIN on the workspace.
404	Entry not found, OR exists in another workspace.
500	DB error.

Workspace lookup table

The join surface for journal cards — entries store stable IDs only, this resolves them to display strings.

GET /api/v1/journal/lookup

Request: no body. The workspace is derived from the authenticated session; there are no query parameters. The authenticated workspace context determines the lookup scope. Returns workspace-scoped crews, agents, and missions for journal-card enrichment (palette colours and lucide icons). Fetched once on page mount; the frontend invalidates it from realtime crew/agent/mission events. Backend handler: internal/api/journal_lookup.go. Response: 200 OK

{
  "crews": [
    {"id":"crw_abc","slug":"backend","name":"Backend","icon":"server","color":"emerald"}
  ],
  "agents": [
    {"id":"agt_xyz","slug":"viktor","name":"Viktor","crew_id":"crw_abc","avatar_seed":"viktor","avatar_style":"pixel-art"}
  ],
  "missions": [
    {"id":"MIS-42","title":"Migrate auth","status":"IN_PROGRESS"}
  ]
}

Each list is capped at 1000 rows; workspaces beyond that get a useful subset. Empty lists are guaranteed non-null (the JSON arrays are always present), so the frontend can .find() without nil guards.

Field	Type	Description
`crews[].id`	string	Stable crew ID.
`crews[].slug`	string	Workspace-unique URL slug.
`crews[].icon`	string?	Lucide icon name (`server`, `code`, `rocket`, …). May be null.
`crews[].color`	string?	Palette ID (`blue`, `emerald`, `violet`, `amber`, `rose`, `cyan`, `lime`, `fuchsia`). May be null.
`agents[].crew_id`	string?	Foreign key to a `crews[]` entry in this same payload. May be null for crew-less agents.
`agents[].avatar_seed`	string?	Deterministic seed; the frontend renders an avatar from this.
`agents[].avatar_style`	string?	Avatar style hint (`pixel-art`, `lorelei`, …).
`missions[].status`	string	A mission status: `PLANNING`, `IN_PROGRESS`, `REVIEW`, `DONE`, `FAILED`, `CANCELLED` — or, for an issue row, an issue status (`BACKLOG`, `TODO`, `DUPLICATE` as well). `COMPLETED` is retired (B13, #2383): the column holds `DONE`.

Soft-deleted crews and agents (deleted_at IS NOT NULL) are filtered out. Missions have no soft-delete column; all rows are returned, ordered by created_at DESC within the cap. The journal entries themselves never carry display strings — they store stable IDs only. This endpoint is the join surface used by every UI card. Errors: 401 on missing workspace; 500 on DB error.

Spend rollup

Cost rollup over cost.incurred journal entries and pipeline_runs.cost_usd (#1404) — a separate, journal-native surface from Paymaster’s /api/v1/paymaster/spend/*.

GET /api/v1/journal/spend

Query parameters:

Param	Type	Description
`window`	string	`24h`, `7d`, or `30d`. Default `24h`. Unknown values → `400` (not silently defaulted).
`top`	integer	Bounds `top_routines`/`top_runs`. 1-50, default 5.

Response: 200 OK

{
  "window": "24h",
  "total_cost_usd": 12.5,
  "by_agent": [
    {"date": "2026-07-24", "crew_id": "crw_backend", "agent_id": "agt_viktor", "cost_usd": 10.0, "call_count": 5}
  ],
  "by_routine": [
    {"date": "2026-07-24", "pipeline_id": "pln_abc", "pipeline_slug": "nightly-report", "cost_usd": 2.5, "run_count": 2}
  ],
  "top_routines": [
    {"kind": "routine", "id": "pln_abc", "label": "nightly-report", "cost_usd": 2.5}
  ],
  "top_runs": [
    {"kind": "run", "id": "run_xyz", "label": "nightly-report", "cost_usd": 1.5}
  ],
  "truncated": false
}

Field	Type	Description
`total_cost_usd`	number	Sum of `cost.incurred` entries only — the ledger’s source of truth. Not the sum of `by_routine`, which reads a denormalized copy of the same spend. Summed by a dedicated unbounded query, so it stays exact even when `truncated` is set (it is not affected by the `by_agent` row cap).
`by_agent`	array	Day × crew × agent buckets, keyed on the UTC calendar day.
`by_routine`	array	Day × routine buckets, keyed on the UTC calendar day.
`top_routines`	array	Top-N routines by total spend across their runs in the window.
`top_runs`	array	Top-N individual runs by cost in the window.
`truncated`	boolean	Set when the window held more rows than the aggregation cap (20000) — the `by_agent`/`by_routine` breakdowns cover the most-recent rows only. `total_cost_usd` is unaffected.

Errors:

Status	Condition
400	Bad `window` or `top`.
401	No workspace context.
500	DB error.

CLI: crewship spend --window 7d --top 10 — see crewship spend.

Tenancy

workspace_id is always pulled from the session context — not from query params.
Cross-workspace reads are impossible: journal.List / Get / Count refuse to run without a workspace filter.
Unknown or cross-tenant IDs return 404 with the same body as “not found”.

​Endpoints

​List entries

​Free-text search

​References

​Stream entries (SSE)

​Get single entry

​Count entries

​Set entry priority

​Workspace lookup table

​Spend rollup

​Tenancy

​Related

Endpoints

List entries

Free-text search

References

Stream entries (SSE)

Get single entry

Count entries

Set entry priority

Workspace lookup table

Spend rollup

Tenancy

Related