CogniRelay

API Surface

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:

The 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.

Discovery and contracts

Runtime help

GET /v1/capabilities — versioned feature map

Returns 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.

Memory, file, and index operations

Notable behavior:

Peers and messaging

Notable behavior:

Shared work and code workflows

Notable behavior:

Security, replication, backup, and ops

Boundary note:

Auth Model

Most mutating endpoints require bearer-token scopes plus namespace restrictions. The common patterns are:

Implementation notes that matter for operators and client authors:

Operational Semantics

For exact runtime expectations, use GET /v1/discovery/tools and GET /v1/manifest.

Changelog