Skip to main content
API docs by Redocly

Angareion Agent API (1.0.0)

Download OpenAPI specification:Download

URL: https://angareion.com/support

The agent-facing API for Angareion — autonomous-agent sensing and memory. Agents authenticate by exchanging an API key for a short-lived JWT (POST /auth/token), then call ingest, delivery, memory, and channel endpoints with the JWT in Authorization: Bearer <jwt>.

Errors follow the canonical envelope (see Error schema). Every response carries X-Request-Id for support correlation; rate-limited responses include X-RateLimit-* and Retry-After.

Auth

API key → JWT exchange.

Exchange API key for short-lived JWT

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.

Request Body schema: application/json
required
api_key
required
string = 40 characters ^ak_live_[A-Za-z0-9]{32}$

API key starting with ak_live_ followed by 32 base62 chars (40 total).

Responses

Request samples

Content type
application/json
{
  • "api_key": "ak_live_AbCdEfGhIjKlMnOpQrStUvWxYz0123456"
}

Response samples

Content type
application/json
{
  • "access_token": "eyJhbGciOiJIUzI1NiIs.eyJzdWIiOiJhZ18.signature",
  • "token_type": "Bearer",
  • "expires_at": "2026-05-28T15:30:00Z",
  • "agent": {
    }
}

Events

Publish events into the sensing pipeline.

Publish a CloudEvents-formatted event

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.

Authorizations:
BearerAuth
header Parameters
Idempotency-Key
string <= 255 characters
Example: idem_01H7abc12345

Client-supplied key making POST/PATCH operations idempotent (per PRD-03 §4.1). Repeated requests with the same key return the original response without executing again. Server retains the key for at least 24 hours.

Request Body schema: application/json
required
specversion
required
string
Value: "1.0"
type
required
string

Reverse-DNS event type (e.g., com.example.order.created).

source
required
string

URI identifying the source system.

id
required
string

Unique event ID (used for dedup).

time
string <date-time>
datacontenttype
string
subject
string
data
any

Provider-defined event payload.

Responses

Request samples

Content type
application/json
{
  • "specversion": "1.0",
  • "type": "com.example.order.created",
  • "source": "//orders.example.com",
  • "id": "evt_01H7abc12345",
  • "time": "2026-05-28T15:00:00Z",
  • "datacontenttype": "application/json",
  • "subject": "order/12345",
  • "data": {
    }
}

Response samples

Content type
application/json
{
  • "event_id": "evt_01H7abc12345",
  • "status": "duplicate"
}

Delivery

Poll and acknowledge deliveries.

Poll pending deliveries for the authenticated agent

Returns up to limit pending deliveries scoped to the calling agent's agent_id (extracted from the JWT). Per PRD-01.

Authorizations:
BearerAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 10

Max deliveries to return. Server clamps to 100.

Responses

Response samples

Content type
application/json
Example
{
  • "deliveries": [
    ],
  • "count": 1
}

Acknowledge one or more deliveries

Marks the specified deliveries as acknowledged for the calling agent. Up to 100 IDs per call. The server enforces agent-id scoping.

Authorizations:
BearerAuth
header Parameters
Idempotency-Key
string <= 255 characters
Example: idem_01H7abc12345

Client-supplied key making POST/PATCH operations idempotent (per PRD-03 §4.1). Repeated requests with the same key return the original response without executing again. Server retains the key for at least 24 hours.

Request Body schema: application/json
required
delivery_ids
required
Array of strings [ 1 .. 100 ] items

Responses

Request samples

Content type
application/json
{
  • "delivery_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "acknowledged": 2
}

DLQ

Dead-letter queue inspection and replay.

List dead-letter queue items

Returns DLQ items scoped to the calling agent (agent JWT) or to the tenant (org-admin JWT). The agent SDK only uses the agent-scoped variant.

Authorizations:
BearerAuth
query Parameters
offset
integer >= 0
Default: 0
limit
integer [ 1 .. 200 ]
Default: 50

Responses

Response samples

Content type
application/json
{
  • "dlq_items": [
    ],
  • "total": 1
}

Replay a DLQ item back to pending

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: dlv_01H7abc12345
header Parameters
Idempotency-Key
string <= 255 characters
Example: idem_01H7abc12345

Client-supplied key making POST/PATCH operations idempotent (per PRD-03 §4.1). Repeated requests with the same key return the original response without executing again. Server retains the key for at least 24 hours.

Responses

Response samples

Content type
application/json
{
  • "status": "replayed",
  • "delivery_id": "dlv_01H7abc12345"
}

Agents

Agent registry CRUD and lifecycle.

List agents in the caller's tenant

Authorizations:
BearerAuth
query Parameters
offset
integer >= 0
Default: 0
limit
integer [ 1 .. 200 ]
Default: 50
status
string
Enum: "active" "inactive"

Responses

Response samples

Content type
application/json
{
  • "agents": [
    ],
  • "total": 1
}

Register a new agent

Authorizations:
BearerAuth
header Parameters
Idempotency-Key
string <= 255 characters
Example: idem_01H7abc12345

Client-supplied key making POST/PATCH operations idempotent (per PRD-03 §4.1). Repeated requests with the same key return the original response without executing again. Server retains the key for at least 24 hours.

Request Body schema: application/json
required
name
required
string non-empty
description
string or null
delivery_mode
required
string
Enum: "poll" "push" "sse"
client_type
required
string
Enum: "claude-desktop" "claude-code" "chatgpt" "gemini" "cursor" "other"

Which chat client this agent represents. Closed 6-value enum.

team_id
string or null

Responses

Request samples

Content type
application/json
{
  • "name": "production-classifier",
  • "description": "Classifies incoming order events by priority",
  • "delivery_mode": "poll",
  • "client_type": "other",
  • "team_id": "team_01H7abc12345"
}

Response samples

Content type
application/json
{
  • "id": "ag_01H7abc12345",
  • "tenant_id": "tn_01H7abc12345",
  • "name": "production-classifier",
  • "description": "Classifies incoming order events by priority",
  • "status": "active",
  • "delivery_mode": "poll",
  • "team_id": "team_01H7abc12345",
  • "created_at": "2026-05-28T15:00:00Z",
  • "updated_at": "2026-05-28T15:00:00Z"
}

Get an agent by id

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: ag_01H7abc12345

Responses

Response samples

Content type
application/json
{
  • "id": "ag_01H7abc12345",
  • "tenant_id": "tn_01H7abc12345",
  • "name": "production-classifier",
  • "description": "Classifies incoming order events by priority",
  • "status": "active",
  • "delivery_mode": "poll",
  • "team_id": "team_01H7abc12345",
  • "created_at": "2026-05-01T10:00:00Z",
  • "updated_at": "2026-05-28T15:00:00Z"
}

Update an agent's metadata or delivery settings

Authorizations:
BearerAuth
path Parameters
id
required
string
header Parameters
Idempotency-Key
string <= 255 characters
Example: idem_01H7abc12345

Client-supplied key making POST/PATCH operations idempotent (per PRD-03 §4.1). Repeated requests with the same key return the original response without executing again. Server retains the key for at least 24 hours.

Request Body schema: application/json
required
name
string
description
string or null
delivery_mode
string
Enum: "poll" "push" "sse"
delivery_endpoint
string or null <uri>

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "id": "ag_01H7abc12345",
  • "tenant_id": "tn_01H7abc12345",
  • "name": "production-classifier",
  • "description": "Classifies incoming order events by priority",
  • "status": "active",
  • "delivery_mode": "push",
  • "delivery_endpoint": "https://agent.example.com/webhook",
  • "team_id": "team_01H7abc12345",
  • "created_at": "2026-05-01T10:00:00Z",
  • "updated_at": "2026-05-28T15:05:00Z"
}

Set agent status to inactive

Authorizations:
BearerAuth
path Parameters
id
required
string
header Parameters
Idempotency-Key
string <= 255 characters
Example: idem_01H7abc12345

Client-supplied key making POST/PATCH operations idempotent (per PRD-03 §4.1). Repeated requests with the same key return the original response without executing again. Server retains the key for at least 24 hours.

Responses

Response samples

Content type
application/json
{
  • "status": "inactive"
}

Set agent status back to active

Authorizations:
BearerAuth
path Parameters
id
required
string
header Parameters
Idempotency-Key
string <= 255 characters
Example: idem_01H7abc12345

Client-supplied key making POST/PATCH operations idempotent (per PRD-03 §4.1). Repeated requests with the same key return the original response without executing again. Server retains the key for at least 24 hours.

Responses

Response samples

Content type
application/json
{
  • "status": "active"
}

List recent delivered events for an agent

Returns the latest N delivered (status=acknowledged) events for the specified agent. Backs the dashboard's "Recent activity" section on the agent detail page (Phase 03 D-02). Default limit is 5; the querystring limit accepts values up to 100, with anything larger clamped to 100.

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: ag_01H7abc12345
query Parameters
limit
integer [ 1 .. 100 ]
Default: 5
Example: limit=5

Responses

Response samples

Content type
application/json
Example
{
  • "events": [
    ]
}

Send a synthetic dashboard test event to an agent

Manufactures a synthetic CloudEvent server-side (type=test.dashboard, source=dashboard.test-event, subject=<agent id>) and pushes it through the same dedup -> publish -> meter pipeline that backs POST /events. Backs the dashboard's "Send a test event" CTA on the agent detail page (Phase 03 D-04). Returns 202 + the generated event id immediately; the event surfaces in GET /agents/{id}/events once the delivery worker acknowledges it.

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: ag_01H7abc12345
header Parameters
Idempotency-Key
string <= 255 characters
Example: idem_01H7abc12345

Client-supplied key making POST/PATCH operations idempotent (per PRD-03 §4.1). Repeated requests with the same key return the original response without executing again. Server retains the key for at least 24 hours.

Responses

Response samples

Content type
application/json
{
  • "event_id": "evt_dash_AbCdEfGhIjKlMnOpQrStUvWx"
}

Agent Keys

Per-agent API key issuance and revocation.

List API keys for an agent (no plaintext, no hash)

Authorizations:
BearerAuth
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "keys": [
    ]
}

Mint a new API key (plaintext returned ONCE)

Authorizations:
BearerAuth
path Parameters
id
required
string
header Parameters
Idempotency-Key
string <= 255 characters
Example: idem_01H7abc12345

Client-supplied key making POST/PATCH operations idempotent (per PRD-03 §4.1). Repeated requests with the same key return the original response without executing again. Server retains the key for at least 24 hours.

Request Body schema: application/json
required
scopes
required
Array of strings non-empty
Items Enum: "send" "receive" "memory:read" "memory:write" "admin" "channel:read" "channel:write" "interests:read" "interests:write"
expires_at
string or null <date-time>

Responses

Request samples

Content type
application/json
{
  • "scopes": [
    ],
  • "expires_at": "2027-05-28T00:00:00Z"
}

Response samples

Content type
application/json
{
  • "id": "key_01H7abc12345",
  • "prefix": "ak_live_AbCdEfGh",
  • "key": "ak_live_AbCdEfGhIjKlMnOpQrStUvWxYz0123456",
  • "scopes": [
    ],
  • "expires_at": "2027-05-28T00:00:00Z",
  • "created_at": "2026-05-28T15:00:00Z"
}

Revoke an agent's API key

Authorizations:
BearerAuth
path Parameters
id
required
string
key_id
required
string

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Interests

Per-agent interest declarations.

List interest declarations for an agent

Authorizations:
BearerAuth
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "interests": [
    ]
}

Create an interest declaration for an agent

Authorizations:
BearerAuth
path Parameters
id
required
string
header Parameters
Idempotency-Key
string <= 255 characters
Example: idem_01H7abc12345

Client-supplied key making POST/PATCH operations idempotent (per PRD-03 §4.1). Repeated requests with the same key return the original response without executing again. Server retains the key for at least 24 hours.

Request Body schema: application/json
required
event_type
required
string non-empty
filter_expression
string or null
priority
required
integer >= 0
enrichment_depth
required
string
Enum: "none" "light" "full"

Responses

Request samples

Content type
application/json
{
  • "event_type": "com.example.order.*",
  • "filter_expression": "amount_cents > 10000",
  • "priority": 10,
  • "enrichment_depth": "light"
}

Response samples

Content type
application/json
{
  • "id": "int_01H7abc12345",
  • "tenant_id": "tn_01H7abc12345",
  • "agent_id": "ag_01H7abc12345",
  • "event_type": "com.example.order.*",
  • "filter_expression": "amount_cents > 10000",
  • "priority": 10,
  • "enrichment_depth": "light",
  • "active": true,
  • "created_at": "2026-05-28T15:00:00Z",
  • "updated_at": "2026-05-28T15:00:00Z"
}

Delete an interest declaration

Authorizations:
BearerAuth
path Parameters
id
required
string
interest_id
required
string

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Channels

Multi-participant channels, members, and feeds.

List channels in the caller's tenant

Authorizations:
BearerAuth
query Parameters
offset
integer >= 0
Default: 0
limit
integer [ 1 .. 200 ]
Default: 50

Responses

Response samples

Content type
application/json
{
  • "channels": [
    ],
  • "total": 1
}

Create a channel

Authorizations:
BearerAuth
header Parameters
Idempotency-Key
string <= 255 characters
Example: idem_01H7abc12345

Client-supplied key making POST/PATCH operations idempotent (per PRD-03 §4.1). Repeated requests with the same key return the original response without executing again. Server retains the key for at least 24 hours.

Request Body schema: application/json
required
name
required
string non-empty
description
string or null
type
required
string
Enum: "open" "private" "direct"

Responses

Request samples

Content type
application/json
{
  • "name": "ops-alerts",
  • "description": "Operational alerts for production",
  • "type": "open"
}

Response samples

Content type
application/json
{
  • "id": "ch_01H7abc12345",
  • "tenant_id": "tn_01H7abc12345",
  • "name": "ops-alerts",
  • "description": "Operational alerts for production",
  • "type": "open",
  • "created_by_type": "agent",
  • "created_by_id": "ag_01H7abc12345",
  • "created_at": "2026-05-28T15:00:00Z",
  • "updated_at": "2026-05-28T15:00:00Z"
}

Get a channel by id

Authorizations:
BearerAuth
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "ch_01H7abc12345",
  • "tenant_id": "tn_01H7abc12345",
  • "name": "ops-alerts",
  • "description": "Operational alerts for production",
  • "type": "open",
  • "created_by_type": "agent",
  • "created_by_id": "ag_01H7abc12345",
  • "created_at": "2026-05-01T10:00:00Z",
  • "updated_at": "2026-05-01T10:00:00Z"
}

List members of a channel

Authorizations:
BearerAuth
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "members": [
    ]
}

Add a member to a channel

Authorizations:
BearerAuth
path Parameters
id
required
string
header Parameters
Idempotency-Key
string <= 255 characters
Example: idem_01H7abc12345

Client-supplied key making POST/PATCH operations idempotent (per PRD-03 §4.1). Repeated requests with the same key return the original response without executing again. Server retains the key for at least 24 hours.

Request Body schema: application/json
required
participant_type
required
string
Enum: "agent" "org_admin"
participant_id
required
string
role
string
Default: "member"
Enum: "owner" "admin" "member"

Responses

Request samples

Content type
application/json
{
  • "participant_type": "agent",
  • "participant_id": "ag_01H7def67890",
  • "role": "member"
}

Response samples

Content type
application/json
{
  • "id": "mbr_01H7def67890",
  • "channel_id": "ch_01H7abc12345",
  • "participant_type": "agent",
  • "participant_id": "ag_01H7def67890",
  • "role": "member",
  • "joined_at": "2026-05-28T15:00:00Z"
}

Remove a member from a channel

Authorizations:
BearerAuth
path Parameters
id
required
string
participant_type
required
string
Enum: "agent" "org_admin"
participant_id
required
string

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

List feeds (event subscriptions) for a channel

Authorizations:
BearerAuth
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "feeds": [
    ]
}

Subscribe a channel to an event glob (create feed)

Authorizations:
BearerAuth
path Parameters
id
required
string
header Parameters
Idempotency-Key
string <= 255 characters
Example: idem_01H7abc12345

Client-supplied key making POST/PATCH operations idempotent (per PRD-03 §4.1). Repeated requests with the same key return the original response without executing again. Server retains the key for at least 24 hours.

Request Body schema: application/json
required
event_type_glob
required
string non-empty
filter_expression
string or null

Responses

Request samples

Content type
application/json
{
  • "event_type_glob": "com.example.order.*",
  • "filter_expression": "amount_cents > 10000"
}

Response samples

Content type
application/json
{
  • "id": "feed_01H7abc12345",
  • "channel_id": "ch_01H7abc12345",
  • "event_type_glob": "com.example.order.*",
  • "filter_expression": "amount_cents > 10000",
  • "active": true,
  • "created_at": "2026-05-28T15:00:00Z"
}

Delete a channel feed

Authorizations:
BearerAuth
path Parameters
id
required
string
feed_id
required
string

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Memories

Memory CRUD, scope promotion, and search.

List memories accessible to the caller

Authorizations:
BearerAuth
query Parameters
offset
integer >= 0
Default: 0
limit
integer [ 1 .. 200 ]
Default: 50
type
string
Enum: "episodic" "semantic" "procedural" "entity" "reflection" "reasoning"
scope
string
Enum: "agent" "team" "institutional"
search
string

Substring match against title and content (handler-side LIKE).

Responses

Response samples

Content type
application/json
{
  • "memories": [
    ],
  • "total": 1
}

Create a memory

Authorizations:
BearerAuth
header Parameters
Idempotency-Key
string <= 255 characters
Example: idem_01H7abc12345

Client-supplied key making POST/PATCH operations idempotent (per PRD-03 §4.1). Repeated requests with the same key return the original response without executing again. Server retains the key for at least 24 hours.

Request Body schema: application/json
required
title
required
string non-empty
content
required
string [ 1 .. 32768 ] characters
type
required
string
Enum: "episodic" "semantic" "procedural" "entity" "reflection" "reasoning"
scope
required
string
Enum: "agent" "team" "institutional"
team_id
string or null

Required if scope=team and not in JWT context.

project_id
string or null
confidence
number [ 0 .. 1 ]
importance
number [ 0 .. 1 ]
object
source_type
string or null
source_id
string or null
source_url
string or null <uri>
source_event_id
string or null
freshness_date
string or null <date-time>
expires_at
string or null <date-time>

Responses

Request samples

Content type
application/json
{
  • "title": "Customer prefers async support",
  • "content": "Customer cs_42 historically responds to email within 6h...",
  • "type": "semantic",
  • "scope": "agent",
  • "confidence": 0.85,
  • "importance": 0.6,
  • "source_event_id": "evt_01H7abc12345"
}

Response samples

Content type
application/json
{
  • "id": "mem_01H7abc12345",
  • "tenant_id": "tn_01H7abc12345",
  • "agent_id": "ag_01H7abc12345",
  • "scope": "agent",
  • "type": "semantic",
  • "status": "active",
  • "title": "Customer prefers async support",
  • "content": "Customer cs_42 historically responds to email within 6h...",
  • "confidence": 0.85,
  • "importance": 0.6,
  • "metadata": { },
  • "source_event_id": "evt_01H7abc12345",
  • "created_at": "2026-05-28T15:00:00Z",
  • "updated_at": "2026-05-28T15:00:00Z",
  • "accessed_at": "2026-05-28T15:00:00Z"
}

Get a memory by id

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid>
Example: mem_01H7abc12345

Responses

Response samples

Content type
application/json
{
  • "id": "mem_01H7abc12345",
  • "tenant_id": "tn_01H7abc12345",
  • "agent_id": "ag_01H7abc12345",
  • "scope": "agent",
  • "type": "semantic",
  • "status": "active",
  • "title": "Customer prefers async support",
  • "content": "Customer cs_42 historically responds to email within 6h...",
  • "confidence": 0.85,
  • "importance": 0.6,
  • "metadata": { },
  • "created_at": "2026-05-01T10:00:00Z",
  • "updated_at": "2026-05-01T10:00:00Z",
  • "accessed_at": "2026-05-28T14:00:00Z"
}

Update mutable fields of a memory

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid>
header Parameters
Idempotency-Key
string <= 255 characters
Example: idem_01H7abc12345

Client-supplied key making POST/PATCH operations idempotent (per PRD-03 §4.1). Repeated requests with the same key return the original response without executing again. Server retains the key for at least 24 hours.

Request Body schema: application/json
required
title
string
content
string <= 32768 characters
confidence
number [ 0 .. 1 ]
importance
number [ 0 .. 1 ]
object
expires_at
string or null <date-time>
freshness_date
string or null <date-time>

Responses

Request samples

Content type
application/json
{
  • "confidence": 0.9,
  • "importance": 0.7
}

Response samples

Content type
application/json
{
  • "id": "mem_01H7abc12345",
  • "tenant_id": "tn_01H7abc12345",
  • "agent_id": "ag_01H7abc12345",
  • "scope": "agent",
  • "type": "semantic",
  • "status": "active",
  • "title": "Customer prefers async support",
  • "content": "Customer cs_42 historically responds to email within 6h...",
  • "confidence": 0.9,
  • "importance": 0.7,
  • "metadata": { },
  • "created_at": "2026-05-01T10:00:00Z",
  • "updated_at": "2026-05-28T15:05:00Z",
  • "accessed_at": "2026-05-28T15:05:00Z"
}

Soft-delete a memory

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Semantic search across memories

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.

Authorizations:
BearerAuth
header Parameters
Idempotency-Key
string <= 255 characters
Example: idem_01H7abc12345

Client-supplied key making POST/PATCH operations idempotent (per PRD-03 §4.1). Repeated requests with the same key return the original response without executing again. Server retains the key for at least 24 hours.

Request Body schema: application/json
required
query
required
string non-empty

Natural-language search query.

scope
string
Enum: "agent" "team" "institutional"

Limit results to a specific scope. Default searches all accessible scopes.

type
string
Enum: "episodic" "semantic" "procedural" "entity" "reflection" "reasoning"
limit
integer [ 1 .. 100 ]
Default: 10
min_confidence
number [ 0 .. 1 ]

Minimum confidence score (0..1) for returned memories.

Responses

Request samples

Content type
application/json
{
  • "query": "customer support preferences",
  • "scope": "agent",
  • "type": "semantic",
  • "limit": 10,
  • "min_confidence": 0.5
}

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "total": 1
}

Create a directed relationship between two memories

Creates a directed relationship from the memory in the path (id) to another memory (target_memory_id). The server enforces a closed enum for relationship_type — values outside the enum are rejected with HTTP 400 validation_error. Backed by MemoryHandler.CreateRelationship in api/internal/handlers/memory.go.

Valid relationship_type values:

  • caused_by
  • related_to
  • contradicts
  • supports
  • derived_from
  • part_of

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

Authorizations:
BearerAuth
path Parameters
id
required
string
Example: mem_01H7abc12345

Source memory id.

header Parameters
Idempotency-Key
string <= 255 characters
Example: idem_01H7abc12345

Client-supplied key making POST/PATCH operations idempotent (per PRD-03 §4.1). Repeated requests with the same key return the original response without executing again. Server retains the key for at least 24 hours.

Request Body schema: application/json
required
target_memory_id
required
string <uuid>

Target memory id (UUID). The source memory id is taken from the path parameter.

relationship_type
required
string
Enum: "caused_by" "related_to" "contradicts" "supports" "derived_from" "part_of"

Closed enum. The server validates this value against the list below and rejects any other value with HTTP 400 validation_error.

strength
number <double> [ 0 .. 1 ]

Optional edge weight in [0, 1]. Server applies a default if omitted (handler stores nil and the persistence layer chooses the default).

object or null

Optional freeform JSON object attached to the edge. May be omitted (sent as null) — the server stores either the object or no metadata.

Responses

Request samples

Content type
application/json
Example
{
  • "target_memory_id": "mem_neighbor1234",
  • "relationship_type": "derived_from",
  • "strength": 0.85,
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "id": "rel_01H7abc12345",
  • "tenant_id": "ten_01H7abc12345",
  • "source_memory_id": "mem_01H7abc12345",
  • "target_memory_id": "mem_neighbor1234",
  • "relationship_type": "derived_from",
  • "strength": 0.85,
  • "metadata": {
    },
  • "created_at": "2026-06-01T12:34:56Z"
}

List relationships for a memory (graph traversal)

Performs a breadth-first traversal of the memory graph starting at id and returns each reached memory along with its hop depth and the cumulative product of edge strengths along the traversal path.

Backed by MemoryHandler.ListRelationships in api/internal/handlers/memory.go. 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.

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid>
Example: mem_01H7abc12345

Source memory id (UUID).

query Parameters
depth
integer [ 1 .. 3 ]
Default: 1
Example: depth=1

Number of relationship hops to traverse. Server clamps to [1, 3]; values <= 0 default to 1, values > 3 are capped at 3.

Responses

Response samples

Content type
application/json
Example
{
  • "relationships": [
    ],
  • "count": 2
}

Delete a memory relationship

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.

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid>
Example: mem_01H7abc12345

Source memory id (UUID).

rel_id
required
string <uuid>
Example: rel_01H7abc12345

Relationship id returned by createMemoryRelationship.

Responses

Response samples

Content type
application/json
{
  • "error": {
    }
}

Promote a memory's scope (agent → team or institutional)

Authorizations:
BearerAuth
path Parameters
id
required
string <uuid>
header Parameters
Idempotency-Key
string <= 255 characters
Example: idem_01H7abc12345

Client-supplied key making POST/PATCH operations idempotent (per PRD-03 §4.1). Repeated requests with the same key return the original response without executing again. Server retains the key for at least 24 hours.

Request Body schema: application/json
required
scope
required
string
Enum: "team" "institutional"

Target scope. Cannot be "agent" (only promotion supported).

team_id
string or null

Required when scope=team.

Responses

Request samples

Content type
application/json
Example
{
  • "scope": "team",
  • "team_id": "team_01H7abc12345"
}

Response samples

Content type
application/json
{
  • "id": "mem_01H7abc12345",
  • "tenant_id": "tn_01H7abc12345",
  • "agent_id": "ag_01H7abc12345",
  • "scope": "team",
  • "team_id": "team_01H7abc12345",
  • "type": "semantic",
  • "status": "active",
  • "title": "Customer prefers async support",
  • "content": "Customer cs_42 historically responds to email within 6h...",
  • "confidence": 0.85,
  • "importance": 0.6,
  • "metadata": { },
  • "created_at": "2026-05-01T10:00:00Z",
  • "updated_at": "2026-05-28T15:10:00Z",
  • "accessed_at": "2026-05-28T15:10:00Z"
}