Angareion Agent API (1.1.0)

Public endpoint. Accepts an API key in the request body and returns a 1-hour JWT. Per PRD-03 §4.2. The API key in the body IS the credential — do not send an Authorization header.

Validates the CloudEvents envelope, deduplicates by id, publishes to the sensing pipeline, and returns 202 Accepted. Duplicates return 200 with status: "duplicate" and the original event_id. Per PRD-01.

Returns all sessions created for the agent, ordered most-recent first. Session state is derived server-side from last_seen_at: active if last seen within 24h, idle otherwise. No revoked state in v1.0 (revocation is deferred to v1.1 per REQUIREMENTS.md TS-12). Limit defaults to 20; max 100.

Issues a fresh XXXX-XXXX user_code (Crockford-32, ~38 bits entropy) with a 10-minute TTL. Supersedes any prior pending code for the same agent_id (the prior code transitions to expired). PROTO-01.

Returns a discriminated union over state ∈ {waiting, verifying, connected, denied, expired}. Every response includes server_now (PROTO-08). The connected variant never includes api_key — credentials only flow through :complete (D-02 / NEEDS-DECISION #2). PROTO-02.

Code-as-credential (D-01, SEC-07): no Authorization header is required; the user_code in the request body is the bearer credential. Account scoping comes from the code's bound tenant_id; per-IP rate limit carries the security weight (30/hr/IP). Atomically transitions the device_code from pending → claimed via single-statement conditional UPDATE with RETURNING (Pitfall 2). PROTO-03.

The dashboard user explicitly approves or rejects the claim made by the MCP client. On approve, the server creates the sessions row and stores session_id + api_key_hash in the device_code's claim_metadata; the :complete endpoint reads these back rather than re-creating a session. On reject, the device_code transitions to denied and the event is audit-logged. The verifying → connected (i.e. claimed → approved) transition is the only path other than :confirm:approve that resolves the claim — server-side Storm-2372 mitigation (SEC-04). PROTO-04.

Polled by the MCP client / CLI after :claim. The claim_id is the bearer credential (no Authorization header). Returns {session_id, agent_id, api_key, access_token, expires_at, server_now} ONCE — the plaintext API key is never re-derivable. The session_id is the row created during :confirm:approve; :complete does not create a session. The access_token is a fresh JWT with a 1-hour TTL sourced from auth.AgentIssuer.Issue. PROTO-05 / D-02.

Updates sessions.last_seen_at = NOW() (database clock; Pitfall 7). Per-session rate limit of 1/min (SEC-10, Pitfall 6). PROTO-06.

OPS-05. Unauthenticated lookup used by the /connect/{code} frontend deeplink to resolve the agent_id before navigating to /agents/{agent_id}/connect. Returns ONLY agent_id; never tenant_id, client_info, or claim_metadata. Codes in denied or expired state return 404 (indistinguishable from never-existed) to defeat enumeration.

Returns a read-only, tenant-scoped health snapshot of the memory plane: duplicate_count (open merge proposals), orphan_count (memories with no incoming MENTIONS edge), stale_count (below the decay/archive floor), embed_gap_count (active rows missing a vector), reflection_count, and a decay_distribution histogram over memory importance. Read-only — it never blocks concurrent writes.

Per PRD-02. Performs scope-aware semantic search across the caller's accessible memories (agent → team → institutional ascending). Results are ranked by composite score combining semantic similarity, confidence, and recency. The exact ranking signals may evolve; the request/response keys documented here are stable.

Creates a directed relationship from the memory in the path (id) to another memory (target_memory_id). Backed by MemoryHandler.CreateRelationship in api/internal/handlers/memory.go.

relationship_type is validated against the relationship_type_registry table filtered to tier='semantic', which is AUTHORITATIVE — it is not a closed enum. The registry gains types by migration, so this spec lists common values as examples rather than constraining them; a client that hardcodes the list below will reject values the server accepts.

Commonly used: related_to (general link — the safe default), supports, contradicts, caused_by, derived_from, part_of, supersedes, superseded_by, corrects, corrected_by, references, generalizes, specializes.

A rejected value returns HTTP 400 validation_error whose message enumerates every accepted type — read it rather than guessing. Provenance types (CITES, DERIVED_FROM, HAS_CHUNK, MENTIONS) are reserved for the extraction pipeline and cannot be set by an agent.

strength and metadata are optional. If strength is omitted the server applies a default; if metadata is omitted it is stored as null.

Returns the relationship edges directly incident to the memory at id, in either direction (as source or as target) — one hop only, not a graph traversal.

Backed by MemoryHandler.ListRelationships in api/internal/handlers/memory.go, which calls ListDirectRelationships. Returns the items the caller's tenant is permitted to see; tenant scoping is enforced server-side.

The count field is the number of items returned, not a paginated total.

Removes a single directed relationship by its server-assigned id. Backed by MemoryHandler.DeleteRelationship in api/internal/handlers/memory.go. Tenant scoping is enforced server-side; the caller must be authenticated as an agent in the owning tenant.

Returns the full citation array for a memory: every Document/Chunk the memory was derived from. Requires memory_id (UUID). Each citation has document_id, document_name, page, snippet, source_uri, confidence, version, and freshness{stale, stale_since}. Use this to verify provenance and surface source attribution to the user.

This is a READ. It does NOT record a usefulness signal — to record that the agent cited a memory in a response, use memory_cite, which is a different operation against POST /v1/memories/{id}/cite.

Returns the Citation nodes linked to this memory via CITES edges in Neo4j (Phase 03 read path). Citations are written by the extraction pipeline when source documents are ingested (Phase 02 EXT-01).

Returns an empty citations array (with HTTP 200) for memories created manually without a source document — this is NOT an error condition.

Backed by SearchHandler.Citations in api/internal/search/handler.go, which calls the memory-bridge gRPC GetMemoryCitations RPC with a 2s deadline and falls back to Postgres lineage if the bridge is unavailable.

Resolves an open merge proposal, keeping surviving_memory_id and collapsing the other. Org-admin only — enforced at the REST layer (D-08). A non-admin caller receives 403, surfaced here as a tool error.

Rejects an open merge proposal without collapsing either memory. Org-admin only — enforced at the REST layer (D-08). A non-admin caller receives 403, surfaced here as a tool error.

Phase 04 R5. Reversible self-curation: sets the memory's invalid_at (invalidate-never-delete — the row is preserved) so it stops surfacing in current memory_search, but can be recovered within the reversibility window. This is NOT a hard delete (hard-delete/RTBF is a separate admin-gated path). Backed by MemoryHandler.Forget in api/internal/handlers/memory.go via the RetireOrMerger OpForget primitive.

Idempotent: re-calling on an already-invalidated memory returns HTTP 200 with invalid_at unchanged (no error, no second mutation). Winner-safe: forgetting a contradiction winner never resurrects the losers it invalidated. Requires memory_id (UUID).

Retire-but-retain supersession between two existing memories. The path memory is the one being REPLACED: its invalid_at is set and its superseded_by becomes superseded_by_id, and the graph edge (superseded_by_id)-[:SUPERSEDES]->(id) is written. The row is never deleted — it drops out of default list/search and surfaces on the include_superseded view. Backed by MemoryHandler.Supersede in api/internal/handlers/memory_supersede.go via the RetireOrMerger OpSupersede primitive (the same path as supersedes_id on create).