This document is the canonical human-facing summary of the currently implemented API surface. The runtime source of truth remains the service discovery and manifest endpoints exposed by the application:
GET /v1/manifestGET /v1/discovery/toolsGET /v1/discovery/workflowsThe sections below mirror that runtime shape and group endpoints by behavior rather than implementation order.
For practical agent integration guidance, start with Agent Onboarding. For capsule structure and request/response schemas, see Payload Reference. For the higher-level system thesis, recovery model, and authority boundaries, see Reviewer Guide.
This document covers the machine-facing HTTP contract. The optional /ui operator surface is intentionally outside that API contract: it is a local-only, read-only, server-rendered observability layer over existing read-side services, not a second programmable interface.
GET /health: liveness and git-state checkGET /capabilities: high-level feature flagsGET /v1/capabilities: versioned, machine-readable feature map with per-capability metadataGET /v1/manifest: machine-readable endpoint contractGET /v1/contracts: compatibility and contract metadataGET /v1/governance/policy: governance and authority policy metadataGET /v1/discovery: machine guidance and entrypointsGET /v1/discovery/tools: tool catalog with schemas and scopesGET /v1/discovery/workflows: suggested autonomous workflowsGET /.well-known/cognirelay.json: well-known discovery entrypointGET /.well-known/mcp.json: bounded MCP supplemental descriptor advertising preferred/latest 2025-11-25 and initialize compatibility for 2025-06-18 plus 2025-11-25GET /v1/mcp: deferred in slice 2; returns 405 with Allow: POSTPOST /v1/mcp: bounded MCP Streamable HTTP posture for the base methods initialize, notifications/initialized, ping, tools/list, and tools/call, plus post-bootstrap help/reference request methods including onboarding and validation-limit lookup. initialize accepts protocol versions 2025-06-18 and 2025-11-25; 2025-11-25 remains preferred/latest. clientInfo follows the MCP Implementation metadata shape for the supported protocol versions, including standard optional fields such as title, description, websiteUrl, and icons. Standard request-level params._meta is accepted and ignored as MCP metadata on initialize, tools/list, tools/call, and runtime help/reference request methods.GET /v1/help: top-level machine-facing help indexGET /v1/help/tools/{name}: bounded usage guidance for one supported toolGET /v1/help/topics/{id}: bounded guidance for one supported topicGET /v1/help/hooks: canonical hook guidanceGET /v1/help/errors/{code}: MCP error remediation guidanceGET /v1/help/onboarding: bounded onboarding section indexGET /v1/help/onboarding/bootstrap: compact startup bootstrap payloadGET /v1/help/onboarding/sections/{id}: one bounded onboarding sectionGET /v1/help/limits: validation-limit field-path indexGET /v1/help/limits/{field_path}: one validation-limit item for an exact field pathGET /v1/capabilities — versioned feature mapReturns a deterministic, machine-readable feature map for the current build. No request body, no query parameters, no auth required. The response is byte-identical on every call to the same build.
{
"version": "1",
"features": {
"continuity.read.startup_view": {
"summary": "Startup-oriented read view with mechanical orientation extraction"
},
"continuity.read.trust_signals": {
"summary": "Mechanical trust assessment: recency, completeness, integrity, scope match"
}
}
}
Semantics: Presence of a key in features means the capability is available on this instance. Absence means it is unavailable. Keys are opaque stable identifiers — agents should treat them as exact-match strings, not parse the dots programmatically.
v1 feature registry includes:
| Feature key | Summary |
|---|---|
continuity.read.startup_view |
Startup-oriented read view with mechanical orientation extraction |
continuity.read.trust_signals |
Mechanical trust assessment: recency, completeness, integrity, scope match |
continuity.upsert.session_end_snapshot |
Additive resume-here capture on upsert for session-end handoff |
continuity.read.salience_ranking |
Deterministic multi-signal salience sorting on list and read paths |
continuity.read.thread_identity |
Thread descriptors with scope anchors and lifecycle transitions |
continuity.stable_preferences |
Stable user and peer preferences persisted on continuity capsules |
continuity.upsert.preserve_mode |
Preserve-by-default field merge on upsert with merge_mode='preserve' |
continuity.patch |
Partial list-field patch operations on existing continuity capsules |
continuity.lifecycle |
Standalone lifecycle transitions for thread and task capsules |
context.retrieve.continuity_state |
Multi-capsule continuity-oriented context bundles with fallback and degradation |
context.retrieve.graph_context |
Bounded derived graph context included by default on context retrieval responses |
continuity.read.startup_graph_summary |
Bounded derived graph summary included on startup continuity reads after base read success |
schedule.one_shot_reminders |
SQLite-backed one-shot reminders and task nudges surfaced by pull/list and orientation responses |
coordination.handoffs |
Local-first inter-agent handoff artifacts with consume tracking |
coordination.shared_state |
Owner-authored shared coordination artifacts with version control |
messaging.direct |
Tracked direct messages with ack, reject, defer, and delivery state |
peers.registry |
Peer registration, trust-level transitions, and manifest exchange |
discovery.tools |
Machine-readable tool catalog for the bounded MCP compatibility surface |
Versioning: version is the schema version, not the app version. It increments only when the response shape changes incompatibly. Adding or removing feature keys does not change the version. Clients must tolerate unknown keys. Summaries are human-readable hints, not machine-parsed contracts.
Relationship to legacy GET /capabilities: The two endpoints are independent. The legacy endpoint returns a flat string list and is unchanged.
For the bounded MCP bootstrap flow, initialize protocol compatibility, the post-bootstrap help/reference request-method additions, the tool metadata model, and the POST /v1/mcp posture, see docs/mcp.md.
POST /v1/write: write text content to a repo-relative pathGET /v1/read: read file content by pathPOST /v1/append: append one JSON object as a JSONL recordPOST /v1/index/rebuild: full index rebuildPOST /v1/index/rebuild-incremental: incremental index rebuildGET /v1/index/status: inspect derived index statePOST /v1/search: query-driven search across indexed contentPOST /v1/recent: latest indexed items without a search queryPOST /v1/schedule/items: create a one-shot reminder or task nudgeGET /v1/schedule/items/{schedule_id}: read one scheduled itemGET /v1/schedule/items: list scheduled items with status, due, link, subject, retired, limit, and offset filtersPATCH /v1/schedule/items/{schedule_id}: update mutable fields on a pending scheduled item with expected_versionPOST /v1/schedule/items/{schedule_id}/acknowledge: mark a pending item acknowledged or donePOST /v1/schedule/items/{schedule_id}/retire: retire a scheduled item without deleting itPOST /v1/context/retrieve: compact continuity-oriented context bundlePOST /v1/continuity/upsert: create or replace one continuity capsulePOST /v1/continuity/read: load one active continuity capsule by exact selectorPOST /v1/continuity/compare: compare one active continuity capsule to a candidate capsule without mutating storagePOST /v1/continuity/revalidate: confirm, correct, degrade, or conflict-mark one active continuity capsulePOST /v1/continuity/retention/plan: persist the next deterministic stale-archive retention plan windowPOST /v1/continuity/list: list active continuity capsule summariesPOST /v1/continuity/archive: archive one active continuity capsule and remove the active filePOST /v1/coordination/handoff/create: create one local-first inter-agent handoff artifact from an active continuity capsuleGET /v1/coordination/handoff/{handoff_id}: read one stored handoff artifact by idGET /v1/coordination/handoffs/query: query visible handoff artifacts for one sender and/or recipient identityPOST /v1/coordination/handoff/{handoff_id}/consume: record the recipient’s advisory, deferred, or rejected consume outcomePOST /v1/coordination/shared/create: create one owner-authored shared coordination artifactGET /v1/coordination/shared/{shared_id}: read one stored shared coordination artifact by idGET /v1/coordination/shared/query: query visible shared coordination artifacts for one owner and/or participant identityPOST /v1/coordination/shared/{shared_id}/update: replace one shared coordination artifact under owner-only version checkingPOST /v1/coordination/reconciliation/open: open one bounded reconciliation artifact from visible handoff/shared claimsGET /v1/coordination/reconciliation/{reconciliation_id}: read one stored reconciliation artifact by idGET /v1/coordination/reconciliations/query: query visible reconciliation artifacts for one owner and/or claimant identityPOST /v1/coordination/reconciliation/{reconciliation_id}/resolve: resolve one open reconciliation record under first-write-wins version checkingPOST /v1/context/snapshot: persist deterministic context snapshotGET /v1/context/snapshot/{snapshot_id}: load a persisted snapshotPOST /v1/compact/run: compaction planning and summary/report generationNotable behavior:
POST /v1/search matches terms, not strict phrases, for multi-word queriesPOST /v1/recent is queryless and focused on recencyPOST /v1/context/retrieve is continuity-shaped output rather than a raw ranked search dumpPOST /v1/context/retrieve now supports optional continuity subject selection and returns additive continuity_state metadata when availablePOST /v1/context/retrieve now also accepts bounded continuity_selectors plus continuity_max_capsules for deterministic multi-capsule continuity loadingPOST /v1/context/retrieve now also accepts continuity_verification_policy to allow degraded capsules, prefer healthy capsules first, or require healthy capsules onlyPOST /v1/context/retrieve now also accepts continuity_resilience_policy so callers can allow fallback snapshots, use the explicit active-first prefer_active mode, or require active continuity onlyPOST /v1/context/retrieve keeps indexed retrieval and adds continuity_index_stale; when they are missing, it falls back to a bounded raw file scan and adds continuity_index_missingPOST /v1/context/retrieve includes bundle.graph_context by default. The graph section is derived from existing task and continuity artifacts, uses fixed response caps, and keeps graph warnings local to bundle.graph_context.warnings. When continuity_mode="off", graph derivation is suppressed and the graph section contains graph_suppressed_by_continuity_mode.memory/schedule/schedule.db; create/update/acknowledge/retire do not mutate task files, continuity capsules, graph data, callbacks, commands, or messagesPOST /v1/context/retrieve includes bundle.schedule_context when scoped by primary subject or continuity selectors. POST /v1/continuity/read with view="startup" includes top-level schedule_context. Both are read-only, scoped to matching task/thread/subject links, and include due plus upcoming buckets.POST /v1/continuity/upsert is the V1 write path for continuity capsules under memory/continuity/POST /v1/continuity/upsert and POST /v1/continuity/revalidate now refresh a recovery-only fallback snapshot under memory/continuity/fallback/POST /v1/continuity/upsert and POST /v1/continuity/revalidate surface fallback snapshot failures through additive recovery_warnings instead of failing the already durable active writePOST /v1/continuity/read now returns source_state plus recovery_warnings; exact-active behavior remains the default and structured fallback or missing-state degradation is enabled with allow_fallback=truePOST /v1/continuity/read now accepts an optional view="startup" parameter; when set, the response includes a startup_summary block alongside the unchanged full capsule — a mechanical extraction of startup-relevant orientation fields with no additional I/OPOST /v1/continuity/read with view="startup" also includes top-level graph_summary after the base read succeeds. Non-startup reads remain graph-free, and base validation/error behavior is unchanged.POST /v1/continuity/refresh/plan now returns deterministic refresh candidates and persists the latest plan under memory/continuity/refresh_state.jsonPOST /v1/continuity/retention/plan now returns a bounded next-action stale-archive window, persists it under memory/continuity/retention_state.json, and exposes total_candidates plus has_more so operators can drain backlog through repeated plan/apply cyclesPOST /v1/continuity/compare returns deterministic changed fields, strongest signal, and a recommended verification outcome without mutating the active capsulePOST /v1/continuity/revalidate writes verification status and capsule health through one audited git-backed continuity updatePOST /v1/continuity/list now supports include_fallback, include_archived, and include_cold, returns additive artifact_state plus retention_class, and classifies archive_stale using COGNIRELAY_CONTINUITY_RETENTION_ARCHIVE_DAYSPOST /v1/continuity/delete deletes exact-selector active, fallback, and archive artifacts through one audited git-backed delete pathPOST /v1/continuity/archive writes an archive envelope under memory/continuity/archive/ and removes the active capsule in one git-backed commitPOST /v1/ops/run now supports host-local continuity_cold_store, continuity_cold_rehydrate, and continuity_retention_apply jobs for explicit continuity semi-cold storage, recovery, and stale-archive policy executionPOST /v1/coordination/handoff/create projects only continuity.active_constraints and continuity.drift_signals from one exact active continuity capsule into a stored handoff artifact under memory/coordination/handoffs/POST /v1/coordination/handoff/{handoff_id}/consume records only recipient outcome fieldsGET /v1/coordination/handoffs/query lets senders and recipients discover visible handoffs without relying on successful message or task-reference delivery; corrupt handoff artifacts are skipped with a warning instead of failing the whole queryGET /v1/coordination/handoff/{handoff_id} is visible only to the sender, the recipient, or an admin caller; POST /v1/coordination/handoff/{handoff_id}/consume is recipient-onlyPOST /v1/coordination/shared/create stores owner-authored shared coordination artifacts under memory/coordination/shared/ rather than projecting from a continuity capsuleconstraints, drift_signals, and coordination_alertsGET /v1/coordination/shared/{shared_id} is visible only to the owner, listed participants, or an admin caller; unlike query, direct read does not require read:filesGET /v1/coordination/shared/query requires read:files, skips corrupt artifacts with a warning, returns list results under shared_artifacts, and keeps non-admin discovery bounded to the caller’s own owner/participant identityPOST /v1/coordination/shared/{shared_id}/update is owner-only, requires an exact expected_version, replaces the bounded shared arrays wholesale, and restores the prior artifact bytes if the commit failsPOST /v1/coordination/reconciliation/open stores additive reconciliation artifacts under memory/coordination/reconciliations/ from bounded visible handoff/shared claims rather than mutating local continuity or shared coordination stateobserved_version assertionsGET /v1/coordination/reconciliation/{reconciliation_id} is visible only to the owner, listed participant peers, or an admin caller; like the 5A/5B direct-read pattern, it requires authentication but not read:filesGET /v1/coordination/reconciliations/query requires read:files, applies all supplied filters conjunctively, skips corrupt artifacts with one warning, and keeps non-admin discovery bounded to the caller’s own reconciliation identityPOST /v1/coordination/reconciliation/{reconciliation_id}/resolve is owner-only (or admin), requires expected_version for first-write-wins concurrency, and writes bounded resolve fields (status, resolution_outcome, resolution_summary, resolved_at, resolved_by, version) without mutating local continuity or 5B shared coordination stateupdated=false without a new commit; a different outcome or summary returns HTTP 409advisory_only, conflicted, and rejected; stronger agreement outcomes that would mutate 5B shared artifacts or local continuity capsules are explicit non-goals of this slicePOST /v1/backup/create now includes continuity_counts in the manifest when continuity artifacts are part of the backup scopePOST /v1/backup/restore-test now accepts verify_continuity and returns structured continuity_validation details for restored active, fallback, archive, and cold continuity artifactscontinuity.session_trajectory entries to preserve in-session direction changescontinuity.trailing_notes, continuity.curiosity_queue, and continuity.negative_decisions fields as additive agent-owned orientation payloadPOST /v1/continuity/read and POST /v1/context/retrieve return those additive fields unchanged when present on the stored capsule and when retrieval trimming does not need to drop themPOST /v1/continuity/list summaries intentionally do not expand to include themPOST /v1/continuity/upsert now enforces cross-field validation for source.update_reason=interaction_boundary and metadata.interaction_boundary_kindPOST /v1/continuity/upsert accepts optional lifecycle_transition (suspend/resume/conclude/supersede) and superseded_by to atomically transition a capsule’s thread_descriptor.lifecycle as part of the write — see Payload Reference for field constraintsPOST /v1/continuity/list accepts thread identity filters: lifecycle, scope_anchor, keyword, label_exact, anchor_kind, and anchor_value — see Payload Reference for filter semanticsPOST /v1/continuity/list accepts sort="salience" to apply deterministic multi-signal salience ranking; when applied, each capsule carries a salience block and the response includes aggregate salience_metadata — see Payload Reference for the sort key and response structurePOST /v1/continuity/read and POST /v1/context/retrieve now include a trust_signals block alongside capsule data — an objective, mechanical trust assessment across four dimensions (recency, completeness, integrity, scope_match); trust_signals is null when the capsule is missing; the startup_summary view also includes trust_signals as a top-level key; build_continuity_state returns both per-capsule and aggregate trust_signals; age fields are null (not 0) when timestamps are missing/malformed; recency.phase falls back to "expired" on malformed verified_at; aggregate trust handles compact per-capsule shapes; recovery_warnings includes "trust_signals_aggregate_failed" when aggregate computation failsgraph_anchor_not_provided, graph_anchor_not_supported, graph_anchor_not_found, graph_derivation_failed, graph_truncated, graph_result_malformed, graph_source_denied, and graph_suppressed_by_continuity_mode. Auth/path denials omit denied sources and never copy graph warnings into recovery_warnings or continuity_state.warnings./ui/schedule inspection page. Deferred/non-goals remain recurrence, background scheduler loops, SSE/push, schedule mutation UI, arbitrary execution, webhooks/callbacks, automatic task or continuity mutation, graph mutation, and graph DB integration.1.1 for newly written continuity capsules and continuity archive/fallback/cold artifacts. Stabilized legacy 1.0 continuity payloads remain supported for load/upgrade when they already have the modern required capsule structure. Truly pre-stabilization payloads missing required modern capsule fields are still a bounded unsupported migration case.GET /v1/peers: list known peersPOST /v1/peers/register: create or update a peer recordGET /v1/peers/{peer_id}/manifest: fetch a peer manifestPOST /v1/peers/{peer_id}/trust: apply a trust transition with policy checksPOST /v1/messages/send: send a direct tracked messagePOST /v1/messages/ack: acknowledge, reject, or defer tracked deliveryGET /v1/messages/pending: inspect pending and terminal delivery stateGET /v1/messages/inbox: read inbox messagesGET /v1/messages/thread: read thread recordsPOST /v1/relay/forward: relay a message and record transport artifactsPOST /v1/messages/verify: verify signed envelopes and nonce replay protectionPOST /v1/replay/messages: replay dead-letter tracked messagesNotable behavior:
attachments using the convention "handoff:{handoff_id}"; the server stores these as opaque strings without validating the referenced artifact existsPOST /v1/tasks: create a shared taskPATCH /v1/tasks/{task_id}: update task status, ownership, or metadataGET /v1/tasks/query: query tasks by workflow filtersPOST /v1/docs/patch/propose: propose a unified diff for docs/contentPOST /v1/docs/patch/apply: apply a proposed docs/content patchPOST /v1/code/patch/propose: propose a unified diff for codePOST /v1/code/checks/run: run a lint, test, or build profile and persist the artifactPOST /v1/code/merge: perform merge policy evaluation using recorded check artifactsNotable behavior:
metadata.handoff_id by convention; the server stores this as arbitrary task metadata without validating or acting on itGET /v1/security/tokens: inspect token metadataPOST /v1/security/tokens/issue: issue scoped peer tokensPOST /v1/security/tokens/revoke: revoke a token by identifier or hashPOST /v1/security/tokens/rotate: atomically replace a tokenPOST /v1/security/keys/rotate: rotate signing key materialGET /v1/metrics: summarize delivery, audit, check, and replication metricsPOST /v1/replication/pull: ingest a replication bundlePOST /v1/replication/push: export and optionally push a replication bundlePOST /v1/backup/create: create a backup archive and manifestPOST /v1/backup/restore-test: validate backup recovery through a restore drillGET /v1/ops/catalog: list host-local maintenance jobsGET /v1/ops/status: inspect recent host-local maintenance runs and locksPOST /v1/ops/run: execute one host-local maintenance jobGET /v1/ops/schedule/export: export suggested scheduler payloadsBoundary note:
/v1/ops/* is a host-local control surface and should stay behind a local trust boundaryMost mutating endpoints require bearer-token scopes plus namespace restrictions. The common patterns are:
read:files, read:index, and configured read_namespaceswrite:journal, write:messages, write:projects, and configured write_namespacessearch and read namespace checksImplementation notes that matter for operators and client authors:
admin:peers bypass all scope and namespace checks — see the Reviewer Guide for the full authority modelread_namespaces and write_namespacesnamespaces is still supported as a shorthand applying to both read and writesnapshots/context/For exact runtime expectations, use GET /v1/discovery/tools and GET /v1/manifest.
view="startup" parameter on POST /v1/continuity/read. Returns a startup_summary block with recovery/orientation/context tiers alongside the unchanged full capsule. See Payload Reference.session_end_snapshot on POST /v1/continuity/upsert. A compact helper that merges startup-critical fields into the capsule before persistence. See Payload Reference.trust_signals block on POST /v1/continuity/read and POST /v1/context/retrieve. Four-dimension mechanical trust assessment (recency, completeness, integrity, scope match). See Payload Reference.stable_preferences (list of StablePreference) on ContinuityCapsule. Bounded to 12 entries; only valid on user/peer capsules. Included in read, startup summary, and context-retrieve paths. List summaries include stable_preference_count. Trimmed as a whole unit under token pressure. See Payload Reference.rationale_entries (list of RationaleEntry, max 6) on ContinuityState. Captures decision rationale, assumptions, and unresolved tensions with kind/status lifecycle and supersession semantics. See Payload Reference.thread_descriptor on ContinuityCapsule with ThreadDescriptor model (label, keywords, scope anchors, identity anchors, lifecycle, superseded_by). Added lifecycle_transition and superseded_by on upsert. Added list filters: lifecycle, scope_anchor, keyword, label_exact, anchor_kind, anchor_value. See Payload Reference.sort="salience" on POST /v1/continuity/list and deterministic salience sorting on context-retrieve paths. Six-signal sort key with per-capsule salience block and aggregate salience_metadata. See Payload Reference.1.1 replaces structured-entry set_at with created_at, updated_at, and last_confirmed_at for stable_preferences, rationale_entries, and negative_decisions. Stabilized-shape legacy continuity payloads remain supported for upgrade; truly pre-stabilization payloads missing required modern fields are not auto-migrated. Sammy’s oldest real continuity capsule sample falls into the supported stabilized-shape legacy bucket. See Payload Reference.GET /v1/capabilities: Added versioned, machine-readable feature map endpoint. The registry now covers continuity enhancements, graph context, schedule reminders, coordination, messaging, peers, and discovery. See Discovery and contracts above.tools/cognirelay_client.py, a stdlib-only command-line client for continuity read, upsert, and token hashing. See CLI Client.