Knowledge and ontology API

Knowledge navigation, ontology proposal, dreaming, and checkpoint endpoints.

Back to HTTP API overview.

Knowledge graph navigation

Signet exposes the structured memory graph as a navigable hierarchy for agents. Search discovers unknown paths; navigation inspects known paths without loading the full constellation graph.

Entity -> Aspect -> Group -> ClaimKey -> Attributes

The house/filesystem analogy is intentional: entities are houses or top-level folders, aspects are rooms, groups are dressers, claim keys are drawers, and attributes are notes inside those drawers.

All routes accept optional agent_id and default to default.

GET /api/knowledge/navigation/entities

List entities with structural counts. Query parameters: q, type, limit, offset.

GET /api/knowledge/navigation/entity

Resolve one entity by name.

/api/knowledge/navigation/entity?name=Nicholai

GET /api/knowledge/navigation/tree

Return a compact entity outline for agent browsing. The tree includes aspects, groups, claim slots, counts, and active previews so agents can decide where to drill next without loading the full constellation graph. Query parameters: entity, depth, max_aspects, max_groups, max_claims.

Depth controls how far the outline expands: 1 returns aspects, 2 returns aspects and groups, and 3 returns aspects, groups, and claim slots.

/api/knowledge/navigation/tree?entity=Nicholai&depth=3

GET /api/knowledge/navigation/aspects

List aspects for an entity.

/api/knowledge/navigation/aspects?entity=Nicholai

GET /api/knowledge/navigation/groups

List groups under an entity aspect. Attributes without group_key appear under general for backward compatibility.

/api/knowledge/navigation/groups?entity=Nicholai&aspect=food

GET /api/knowledge/navigation/claims

List claim slots under an entity/aspect/group path.

/api/knowledge/navigation/claims?entity=Nicholai&aspect=food&group=restaurants

GET /api/knowledge/navigation/attributes

List attributes under an entity/aspect/group/claim path. Defaults to status=active; pass status=all to include superseded history. Query parameters: entity, aspect, group, claim, status, kind, limit, offset.

/api/knowledge/navigation/attributes?entity=Nicholai&aspect=food&group=restaurants&claim=favorite_restaurant

CLI equivalents:

signet knowledge tree Nicholai
signet knowledge entities --query Nicholai
signet knowledge entity Nicholai
signet knowledge aspects Nicholai
signet knowledge groups Nicholai food
signet knowledge claims Nicholai food restaurants
signet knowledge attributes Nicholai food restaurants favorite_restaurant
signet knowledge attributes Nicholai food restaurants favorite_restaurant --status all
signet knowledge hygiene

GET /api/knowledge/constellation

Return the bounded graph overlay used by the dashboard Ontology constellation. Query parameters: agent_id, limit, max_aspects_per_entity, max_attributes_per_aspect, and dependency_limit. When agent_id is omitted, the daemon uses the configured daemon agent ID (SIGNET_AGENT_ID, or default). The read includes the requested agent plus agents whose read_policy is shared, and clamps limits so dashboard navigation cannot load the entire knowledge graph into one read response.

Defaults: limit=150, max_aspects_per_entity=6, max_attributes_per_aspect=4, and dependency_limit=500.

GET /api/knowledge/hygiene

Return a report-only graph hygiene scan. Query parameters: agent_id, limit, and memory_limit.

The response includes suspicious entities, duplicate canonical entity groups, attribute rows missing group_key or claim_key, attributes without source memories, and safe mention-link candidates where an existing entity name appears in a memory that is not yet linked. This endpoint does not mutate graph data.

MCP exposes the same report as knowledge_hygiene_report.

Entity aliases

Entity aliases are reviewed ontology metadata used by prompt-submit entity detection and navigation tooling. They do not create duplicate entities. Active aliases are matched as exact normalized phrases and resolve back to the canonical entity current view.

GET /api/ontology/entities/:id/aliases

List aliases for an entity id. Query parameters: agent_id and status. status may be active, archived, or all; it defaults to active.

/api/ontology/entities/entity_signet/aliases?agent_id=ant&status=all

POST /api/ontology/entities/:id/aliases

Create an active alias for an entity id. Body parameters: alias, confidence, and source. confidence is clamped to 0..1 and defaults to 1.0.

{
  "alias": "SignetAI",
  "confidence": 0.95,
  "source": "operator"
}

DELETE /api/ontology/entities/:id/aliases/:aliasId

Archive an alias. Archived aliases are retained for inspection but are ignored by prompt-submit entity matching.

CLI equivalents:

signet ontology entity alias list entity_signet --status all
signet ontology entity alias add entity_signet SignetAI --confidence 0.95 --source operator
signet ontology entity alias archive entity_signet alias_123

Ontology proposal loop

Ontology maintenance writes reviewable proposals before mutating semantic graph state. Read routes require recall; mutation routes require modify. All routes accept optional agent_id.

GET /api/ontology/proposals

List proposal records. Query parameters: status, operation, limit, offset.

GET /api/ontology/proposals/:id

Return one ontology proposal by id, scoped to the resolved agent_id. Returns 404 when the proposal does not exist in that agent scope. Use this before apply/reject flows when an operator needs to inspect the exact operation, payload, rationale, risk, status, source provenance, and evidence that will be promoted or rejected.

/api/ontology/proposals/prop_123?agent_id=ant

GET /api/ontology/proposals/conflicts

List pending add_claim_value proposal conflicts grouped by claim slot. Query parameters: agent_id and limit. Each conflict group includes the entity, aspect, group, claim key, competing values, and proposal ids so operators can review contradictory pending proposals before consolidation or apply.

/api/ontology/proposals/conflicts?agent_id=ant&limit=100

GET /api/ontology/contradictions

List persisted contradiction observations between competing applied claim values. The route is recall-authorized and always scoped to the resolved agent_id. It defaults to status=active; pass status=resolved or status=all to inspect resolved history. Optional filters are entity, entity_id, aspect_id, group, claim, source_id, limit, and offset. The response contains both claim ids and content, each side’s confidence, scope/visibility, source provenance, evidence references, detector, and resolution metadata.

/api/ontology/contradictions?agent_id=ant&entity=Signet&status=all

The initial persisted detector is deterministic and lexical only. An active row means both claim rows are still active in the same slot and continue to match the guard; it is not a third truth value and does not choose between sources. Source removal retains the contradiction snapshot and marks it resolved so callers can answer that evidence conflicted without reading a deleted claim row.

GET /api/ontology/contradictions/:id

Read one contradiction observation by id in the resolved agent scope. Returns 404 when the id belongs to another agent or does not exist.

CLI equivalent:

signet ontology contradictions --agent ant --status all
signet ontology contradictions --entity Signet --group architecture --claim current_value

GET /api/ontology/proposals/:id/evidence

Resolve a proposal’s evidence references against session transcripts and indexed memory artifacts. The endpoint never reads arbitrary filesystem paths.

GET /api/ontology/claims/evidence

Resolve evidence for already-applied claim values from stored attribute provenance. Applied rows include the applying proposal id and copied proposal evidence when the value was promoted through the proposal loop, so this endpoint returns exact proposal lineage before broader source fallback evidence. Query parameters: entity, aspect, group, claim, status, kind, limit, offset.

/api/ontology/claims/evidence?entity=Signet&aspect=architecture&group=ontology&claim=proposal_loop

GET /api/ontology/claims/explain

Return one bounded, authorized claim trace over the existing ontology versions, linked epistemic assertions, proposal evidence, episodic sources, and derived_memory_sources reverse lineage. This endpoint is read-only and does not create a second provenance store or widen cross-agent recall.

Required query parameters are entity, aspect, group, and claim. Optional parameters are kind (attribute or constraint), version_limit (1–50, default 20), premise_limit (1–100, default 50), reverse_limit (1–100, default 50), max_depth (0–3, default 3), agent_id, and session_key.

The resolved agent follows the normal scoped-agent/recall permission path. Project-scoped tokens can only inspect linked claim memories, premises, and reverse dependents in their project. A supplied session key may also be sent as x-signet-session-key; conflicting values are rejected, and remote calls must bind the session to the resolved agent.

Premises must resolve to an existing same-agent canonical episodic source (memory, artifact, transcript, or summary). When a premise includes an exact quote, the quote must occur in the immutable source content. Fabricated or mismatched references return 409; cross-agent, cross-project, or cross-session references return 403. Session-scoped traces fail closed when the source session cannot be proven. Deleted, superseded, stale, and incomplete source records are reported as invalidated or unverified and are never returned as verified evidence.

The response includes current, versions, competing, assertions, premises, reverse, authorization, integrity, traversal, and latencyMs. versions, premises, and reverse each expose their bounded items and truncation state. integrity.status is verified, unverified, or invalidated so consumers cannot silently treat an old explanation as current truth.

CLI and MCP equivalents:

signet ontology explain-claim Signet architecture ontology proposal_loop
signet ontology explain-claim Signet architecture ontology proposal_loop --session-key session-123 --json

MCP clients call signet_explain_claim with the same selectors and bounds.

GET /api/ontology/links/:id/evidence

Resolve evidence for an already-applied ontology link from stored dependency provenance. Links applied through proposals include the applying proposal id and copied proposal evidence before broader source fallback evidence.

GET /api/ontology/assertions

List source-attributed epistemic assertions. Assertions record who claimed, believed, observed, decided, preferred, denied, or questioned something about an entity without promoting that statement into current ontology truth. Query parameters: agent_id, observer_id, entity, entity_id, predicate, status, speaker, source_kind, source_id, query, limit, and offset.

observer_id is the explicit observer-scoped projection for directional reads. In the current agent-only model it must match the authorized agent_id; arbitrary peer observer identities are rejected. Omitting it preserves the existing agent-scoped query behavior.

Valid predicates are claims, believes, observed, decided, prefers, denies, and questions. Valid statuses are active, archived, superseded, and all for list reads.

/api/ontology/assertions?entity=Signet&observer_id=ant&predicate=believes&speaker=Nicholai

GET /api/ontology/assertions/:id

Return one epistemic assertion by id, scoped to the resolved agent_id. The optional observer_id query parameter must match that authorized agent scope. Returns 404 when the assertion does not exist in that agent scope.

/api/ontology/assertions/assertion_123?agent_id=ant&observer_id=ant

POST /api/ontology/assertions

Create a source-attributed epistemic assertion. Body parameters: agent_id, observer_id, entity or entity_id, predicate, content, speaker, asserted_at, confidence, evidence, source_kind, source_id, source_path, source_root, claim_attribute_id, and created_by.

observer_id is optional and must match the authorized agent_id. It records the same agent-only observer projection returned by assertion queries; it does not authorize writing on behalf of another agent.

Every assertion must include either structured evidence or source provenance fields. If claim_attribute_id is supplied, the referenced applied claim value must be active and belong to the same agent and subject entity.

POST /api/ontology/assertions/:id/link-claim

Link an existing assertion to an applied claim attribute. Body parameters: agent_id and attribute_id. The daemon rejects cross-agent and cross-entity links, and it only accepts active claim attribute rows.

POST /api/ontology/assertions/:id/archive

Archive an assertion without deleting evidence. Body parameters: agent_id, actor, and reason.

POST /api/ontology/assertions/:id/supersede

Create a replacement assertion and mark the old assertion superseded. Body parameters match assertion creation plus agent_id. Omitting predicate preserves the old assertion predicate; pass a predicate only when the epistemic meaning is intentionally changing. Omitting source fields inherits source provenance from the old assertion, but replacement content is still required. Supersede keeps the old subject entity; use a new assertion when the subject entity changes.

CLI equivalents:

signet ontology assertions --entity Signet --predicate believes --speaker Nicholai
signet ontology assertion create --entity Signet --predicate believes --content "Signet should model attributed beliefs." --source-kind transcript
signet ontology assertion show <assertion-id>
signet ontology assertion link-claim <assertion-id> --attribute-id <claim-attribute-id>
signet ontology assertion archive <assertion-id> --reason "superseded by newer evidence"
signet ontology assertion supersede <assertion-id> --content "Updated attributed belief." --source-kind transcript
signet ontology assertion import --file assertions.json

POST /api/ontology/extract

Extract candidate ontology proposals and source-attributed assertions from an agent-scoped transcript or memory artifact. Body parameters: from, agent_id, write_proposals, write_assertions, created_by, limit, use_provider, provider_timeout_ms, and provider_max_tokens. from accepts refs such as transcript:<id>, artifact:<source_path>, or source:<source_path>.

The route dry-runs by default. It writes pending proposals only when write_proposals is true and writes epistemic assertions only when write_assertions is true. If both write flags are set, proposal and assertion inserts share one transaction and roll back together on invalid extracted items. When use_provider is true, the route uses the configured memory_extraction inference workload and falls back to deterministic extraction if no valid provider proposals are returned. Provider-returned questions are surfaced in the response for review; this route does not persist first-class question objects yet.

POST /api/ontology/consolidate

Consolidate pending ontology proposals into higher-confidence pending proposals. Body parameters: agent_id, status, limit, write_proposals, created_by, use_provider, provider_timeout_ms, and provider_max_tokens. The route dry-runs by default. Provider-backed consolidation uses the configured memory_extraction inference workload and never mutates ontology state directly; it writes only pending proposals when write_proposals is true.

POST /api/ontology/proposals

Create one pending ontology proposal.

POST /api/ontology/proposals/batch

Create multiple pending proposals atomically.

POST /api/ontology/proposals/:id/apply

Apply one pending proposal through its explicit operation handler.

POST /api/ontology/proposals/:id/reject

Reject one pending proposal without mutating graph state.

POST /api/ontology/proposals/repair/duplicates

Detect duplicate same-agent entities and optionally write merge proposals.

Dreaming

Dreaming is a periodic knowledge-graph consolidation process that uses a smart model to merge, prune, and enrich the entity graph.

GET /api/dream/status

Return the current dreaming worker state, configuration, recent passes, quarantined evidence, and pending agent-scoped semantic attention. Attention is operational context for work such as due reviews, hygiene, contested claims, or an explicitly requeued evidence source; it never copies or replaces episodic evidence. Requires admin permission.

Query parameters

Parameter	Type	Required	Description
agentId	string	no	Agent ID (default: daemon configured agent)
agent_id	string	no	Alias for agentId

Response

{
  "enabled": true,
  "worker": { "running": true, "active": false, "activeAgentId": null },
  "episodicTokensPending": 42000,
  "state": {
    "tokensSinceLastPass": 42000,
    "lastPassAt": "2026-04-01T12:00:00.000Z",
    "lastPassId": "abc-123",
    "lastPassMode": "incremental"
  },
  "config": {
    "tokenThreshold": 100000,
    "backfillOnFirstRun": true,
    "maxInputTokens": 128000,
    "maxOutputTokens": 16000,
    "timeout": 300000
  },
  "passes": [
    {
      "id": "pass-uuid",
      "mode": "incremental",
      "status": "completed",
      "startedAt": "2026-04-01T12:00:00.000Z",
      "completedAt": "2026-04-01T12:05:00.000Z",
      "tokensConsumed": 8000,
      "mutationsApplied": 12,
      "mutationsSkipped": 3,
      "mutationsFailed": 1,
      "summary": "Merged 3 duplicate entities, pruned 5 junk attributes",
      "error": null
    }
  ],
  "exclusions": [
    {
      "sourceKind": "artifact",
      "sourceId": "sources/notebook/large-export.md",
      "reason": "semantic_operation_rejected",
      "failureClass": "quote_mismatch",
      "retryCount": 0,
      "passId": "pass-uuid",
      "excludedAt": "2026-04-01 12:00:00",
      "requeueRequestedAt": null,
      "resolvedAt": null
    }
  ],
  "attention": [
    {
      "id": "attention-uuid",
      "kind": "review_due",
      "subjectRef": "entity:aster",
      "details": { "reason": "review_after reached" },
      "priority": 90,
      "createdAt": "2026-04-01 12:00:00"
    }
  ]
}

An exclusion preserves only the source identity and processing status; it does not modify or discard the underlying episodic evidence. Current Dreaming passes record semantic_operation_rejected when the daemon rejects an agent’s cited semantic operation. Oversized immutable evidence is instead resumed at a safe boundary across passes and is not quarantined.

Transient exclusions are classified as incomplete_transcript, source_projection, scope_mismatch, or quote_mismatch. The worker compares the current canonical source fingerprint with the quarantined fingerprint and automatically requests a bounded retry when a repair is visible. Automatic retries use the repair cooldown and hourly budget, allow at most three attempts per exclusion, and mint the same scoped evidence_requeue attention as an explicit request. An unchanged source, an unknown failure, or a source outside the agent scope remains quarantined. The exclusion row stays auditable until a subsequent accepted citation resolves it.

An attention item is selected with the next scoped pass and rendered as non-evidentiary context. It resolves when the pass applies a hygiene operation citing it, or when the agent explicitly declines it (the decline_attention operation, used when the agent inspects the target and judges it should stay as is). Records the agent could not complete stay pending, and a failed pass leaves everything pending. The worker can run for pending attention even when no new episodic evidence has arrived, while normal failure backoff still applies.

GET /api/dream/passes/active

List the currently running passes in the resolved agent scope. This is the selection endpoint used by signet dream attach: the CLI attaches implicitly only when this list contains exactly one item. Requires admin permission.

{
  "agentId": "noam",
  "items": [
    {
      "id": "pass-uuid",
      "mode": "incremental",
      "status": "running",
      "startedAt": "2026-04-01 12:00:00",
      "completedAt": null,
      "summary": null,
      "error": null
    }
  ]
}

The response is always scoped to the daemon’s current agent context unless an agent selector is supplied through the existing scoped-agent headers/query parameters. A pass ID from another agent is never accepted by the live stream route.

GET /api/dream/passes/:passId/events

Open a read-only Server-Sent Events (SSE) stream for one agent-scoped pass. Requires admin permission. The optional after query parameter, or the Last-Event-ID header, resumes after a non-negative event cursor:

GET /api/dream/passes/pass-uuid/events?after=42
Accept: text/event-stream

Set verbose=1 (or verbose=true) when the operator has opted into raw debugging data. The default stream omits raw fields; the CLI reconnects on the same SSE transport when Ctrl+V toggles this mode.

The first event is a snapshot whose data contains the current pass metadata and replay window. Subsequent events carry a monotonic id and include assistant deltas, reasoning deltas, Pi lifecycle transitions, tool start/ progress/end events, detailed tool_trace events, session metadata, and a terminal pass_completed or pass_failed event. Tool traces and Pi events remain ephemeral; the durable dreaming_passes and dreaming_tool_calls rows are the audit source.

When the requested cursor is outside the bounded in-memory replay window, the stream sends a gap event with requestedCursor, availableFrom, availableTo, and reason. The snapshot is authoritative and the client can continue from the latest cursor. Heartbeats are sent as SSE comments so idle connections remain detectable. Slow viewers are disconnected once their bounded stream queue fills and can reconnect from the last delivered cursor.

The verbose event data includes bounded raw fields for the opt-in terminal view. These may contain prompts, system/developer instructions, model reasoning, evidence, tool arguments, and tool results. The daemon does not persist a second transcript for attachment and the stream exposes no control or prompt-submission action.

POST /api/dream/exclusions/requeue

Request one quarantined evidence source be considered again after correcting the model or configuration issue that caused a rejected semantic operation. Requires admin permission.

Request body

{
  "sourceKind": "artifact",
  "sourceId": "sources/notebook/large-export.md",
  "agentId": "noam"
}

sourceKind must be one of memory, artifact, transcript, or summary. sourceId is the identifier returned by GET /api/dream/status. agentId uses the same scoped-agent resolution as Dreaming trigger requests.

Returns 404 when the scoped exclusion is no longer active. Requeueing also records an evidence_requeue attention item, so it can wake a scoped Dreaming pass without waiting for unrelated new evidence.

POST /api/dream/operations

Apply a batch of cited ontology operations for an external Dreaming agent. Requires modify permission. This is the daemon-owned semantic apply seam: the caller supplies operations and evidence, but the daemon resolves every episodic source in the credential’s agent scope before it writes graph state.

Request body

{
  "agentId": "noam",
  "actor": "dreaming-agent",
  "operations": [
    {
      "operation": "set_claim_value",
      "payload": { "entityId": "entity-id", "aspect": "role", "value": "Engineer" },
      "reason": "The cited note explicitly identifies this role.",
      "evidence": [{ "sourceKind": "artifact", "sourceId": "note.md", "quote": "..." }],
      "confidence": 0.9
    }
  ]
}

operations must contain 1–100 entries. Each entry must use one of the same closed, payload-validated ontology operation schemas exposed by apply_ontology_ops from GET /api/dream/tools; a write requires a canonical episodic source and an exact supporting quote. The daemon validates every input, citation, and resolvable target before it mints hygiene attention or writes graph state. It then applies operations in order through bounded, yielding write transactions. Each operation’s savepoint, provenance, and attention resolution are atomic, while an application failure is reported without blocking later operations. The whole request is not an all-or-nothing transaction. If writer admission fails after earlier chunks committed, the response is 503 with the committed items, retryable: true, and retryFrom. Retry only the uncommitted suffix, never the returned prefix; replace any earlier attention:$<index> reference with attention:<uuid> built from the flag item’s returned result.attentionId. Other validation failures return 400; a fully handled request returns 200. agentId uses scoped-agent resolution and cannot cross the credential’s agent scope.

GET /api/dream/passes/:passId/tools

Return the local, ordered Pi capability trace for one Dreaming pass: every tool’s input, output, success result, and latency. The route is agent-scoped and requires admin permission. It is intended for reviewing whether the agent searched graph or episodic evidence before proposing semantic writes.

GET /api/dream/quality

Return deterministic, agent-scoped semantic quality measures for the current Dreaming graph. citationCoverage counts active claim values that retain an exact quote in canonical proposal evidence plus a resolvable episodic source; a source pointer without a quote is not citation coverage. graphGarbageRate applies the shared entity-quality classifier and detects possessive duplicates, excluding source-native topology. structureQuality reports the unknown entity-type rate, exact profile aspect rate, and generic-aspect rate (profile, details, general, and information) for model-ablation comparisons. Requires admin permission.

GET /api/dream/tools

List the canonical Dreaming capability registry, including each capability’s JSON Schema. Pi sessions, restricted Dreaming MCP, and signet dream bind this same registry; clients must not reproduce a separate tool list. Requires modify permission.

The registry includes list_contradictions, a read-only, bounded agent-scoped view of persisted competing-claim observations. It exposes both claim snapshots and their source/evidence metadata without selecting a winner; correction still goes through apply_ontology_ops and the normal proposal governance path.

POST /api/dream/tools/:capability

Invoke one canonical Dreaming capability through the daemon. This is the transport binding for restricted MCP and shell-driven harnesses; the daemon validates the registry schema and pins all reads and writes to the credential’s agent scope. Requires modify permission.

Request body

{
  "agentId": "noam",
  "input": { "query": "deployment target" }
}

input must satisfy the selected capability’s schema from GET /api/dream/tools. For example, search_entities accepts query, type, limit, and offset; apply_ontology_ops accepts a cited operations batch. Its schema is a closed union of the 19 audited ontology operations and each operation’s payload fields, so clients can validate an operation before attempting a write. The daemon bounds each write transaction by operation count and elapsed processing time, yielding between chunks while preserving request order. check_entity_label, find_duplicate_entities, and check_contradiction expose the daemon’s read-only deterministic guards so a reasoner can consult them before proposing a write; cited operation validation and semantic writes remain daemon-owned. The request body cannot supply a second agent scope inside input. A writer failure after a committed prefix returns 503 with retryable: true, retryFrom, and the committed items; retry only operations.slice(retryFrom), never the returned prefix. runbook_read returns recent scoped pass outcomes, applied/rejected operations, evidence windows, unresolved quarantines, and notes; runbook_write stores one short structured note on a currently running pass. CLI callers supply that pass with --pass-id; the Pi and restricted ACPX bindings receive it from the daemon-owned pass context.

POST /api/dream/trigger

Manually trigger a dreaming pass. Requires admin permission. Returns 202 Accepted immediately and runs the pass in the background (passes can take up to several minutes on large graphs). Returns 409 if a pass is already running. Returns 503 if the dreaming worker is not started.

Poll GET /api/dream/status and check passes[0].status for completion, or use GET /api/dream/passes/:passId/events for a live read-only view.

Request body

{
  "mode": "incremental",
  "agentId": "noam"
}

mode is "incremental" (default) or "compact". agentId is optional and defaults to the daemon configured agent; agent_id, the agentId query parameter, the agent_id query parameter, and x-signet-agent-id are also accepted.

Explicit triggers always run the combined incremental runbook (hygiene queue first, then content ingestion). The worker’s scheduled sweep passes, in contrast, alternate between two focused runbooks when both kinds of work are pending — incremental-hygiene (attention queue only) and incremental-content (new evidence only) — so content ingestion gets a guaranteed turn even while the hygiene queue stays full (#1098). The pass row’s mode column and the status response’s state.lastPassMode record the runbook that actually ran.

Response — 202 Accepted

{
  "accepted": true,
  "passId": "pass-uuid",
  "status": "running",
  "mode": "incremental",
  "agentId": "noam"
}

Checkpoints

Session checkpoints track continuity state at compaction boundaries.

GET /api/checkpoints

List session checkpoints for a project.

Query parameters

Parameter	Type	Required	Description
project	string	yes	Project path to filter by
limit	integer	no	Max results (default: 10, max: 100)

Response

{
  "checkpoints": [
    {
      "session_key": "abc-123",
      "project": "/path/to/project",
      "trigger": "periodic",
      "created_at": "2026-02-21T10:00:00.000Z"
    }
  ],
  "count": 1
}

GET /api/checkpoints/:sessionKey

Get all checkpoints for a specific session.

Response

{
  "checkpoints": [ ... ],
  "count": 3
}