API docs by Redocly

AgentMemory API (1.1.0)

Download OpenAPI specification:

AgentMemory is a persistent, semantic memory service for AI agents. It stores conversation history, extracted facts, and vector embeddings, enabling agents to recall relevant past context across sessions and conversations.

Core concepts

AgentMemory organizes data in a three-level hierarchy:

  • User - a persistent identity (human end-user, agent instance, or service account) that owns one or more sessions. A user must exist before sessions or memory can be created.
  • Session - a scoped conversation context owned by a user. The session is the default boundary for semantic search - results are drawn from the current session unless the request explicitly expands scope. Sessions can be ended to prevent further writes.
  • Memory block - the atomic unit of stored knowledge. Each block holds either a chat message (a user-turn and assistant-turn exchange) or a fact (a standalone declarative string). Blocks are independently addressable and retrievable.

Semantic extraction

When a memory block is written, AgentMemory generates its vector embedding before responding, so every block is searchable as soon as the write returns. The optional LLM-generated summary and contexts are produced separately, by default asynchronously in the background. Search returns blocks in any status: a processing or extraction_failed block has no summary or contexts yet, only its raw content.

Authentication

Authentication is optional and controlled by the OIDC_AUTH_ENABLED server configuration. When enabled, all endpoints except GET /health and GET /metrics require a valid JWT Bearer token issued by the configured OIDC provider.

Include the token in every request: Authorization: Bearer <token>

Tokens are validated against the provider's JWKS endpoint. A 401 response indicates a missing, malformed, or expired token.

Authorization

Role-based authorization is a separate switch, AGENTMEMORY_AUTHZ_ENABLED, off by default. When it is off, any valid token reaches every endpoint. When it is on, the token's roles claim must carry at least one of three ranked roles:

Role Grants
ams_ro Reads: search, get, list, and the /health/* diagnostics
ams_rw Everything ams_ro does, plus user, session, and memory mutations
ams_admin Everything, plus GET /users, prompt mutations, and GET /logs/collect

Ranks are cumulative, so a single role is enough - ams_admin does not also need the lower two. Roles the server does not recognize are ignored rather than rejected, so unrelated realm roles in the same claim are harmless. A token carrying none of the three is denied on every non-public endpoint.

A 403 response means the token was valid but its rank was below what the endpoint requires; the response body names the role needed, for example Insufficient permissions. Required role: ams_rw or higher.

Request and response format

All request and response bodies use application/json. All timestamps are ISO 8601 strings in UTC. Errors are returned as a JSON object with an error code, a human-readable message, and an optional details field.

Rate limiting and ingestion

Memory block ingestion is accepted immediately, but semantic extraction (embedding generation and summarization) is rate-limited by the configured model provider. If the extraction queue reaches capacity, ingestion requests return 503 with a retry_after_seconds field.

Users

Create and manage user identities. A user is the top-level entity in the AgentMemory hierarchy - every session and memory block is owned by a user.

The user_id is application-defined and must be unique across the deployment. Use your application's native user identifier (UUID, account ID, or similar) as user_id to avoid maintaining a separate mapping table.

Deleting a user is a cascade operation - it permanently removes all sessions and memory blocks associated with that user. There is no soft-delete or recovery.

Create User

Create a new user with the specified ID, name, and optional metadata. The user_id must be unique — attempting to create a user with an existing ID returns a conflict error.

Authorizations:
HTTPBearer
Request Body schema: application/json
required
user_id
required
string (User Id)

Unique user ID. Must not be blank. A duplicate returns 409.

name
required
string (Name)

Display name. Must not be blank.

Metadata (object) or Metadata (null) (Metadata)

Free-form JSON stored with the user. GET /users can filter on its values.

Responses

Request samples

Content type
application/json
{
  • "user_id": "user_123",
  • "name": "John Doe",
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "sessions": [
    ],
  • "metadata": { }
}

List Users

Retrieve users, optionally filtered by name and/or metadata, paginated. Criteria are combined with AND logic and match on exact equality — no wildcards. Returns an empty list if no users match, or if no users exist.

Authorizations:
HTTPBearer
query Parameters
Name (string) or Name (null) (Name)

Filter by exact user name

Array of Metadata (strings) or Metadata (null) (Metadata)

Filter by metadata, as repeated key=value params. Values are matched as strings on exact equality.

limit
integer (Limit) [ 1 .. 500 ]
Default: 50
offset
integer (Offset) >= 0
Default: 0

Responses

Response samples

Content type
application/json
{
  • "users": [
    ],
  • "count": 0,
  • "total": 0,
  • "limit": 1,
  • "offset": 0
}

Get User

Retrieve a single user by ID. Responds with 404 if no such user exists. Filtered lookup lives on the List Users endpoint.

Authorizations:
HTTPBearer
path Parameters
user_id
required
string (User Id)

Unique identifier for the user

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "sessions": [
    ],
  • "metadata": { }
}

Update User

Update an existing user's name and/or metadata. At least one field must be provided. Omitted fields retain their existing values.

Authorizations:
HTTPBearer
path Parameters
user_id
required
string (User Id)

Unique identifier for the user

Request Body schema: application/json
required
Name (string) or Name (null) (Name)

New display name. Omit to keep the current one.

Metadata (object) or Metadata (null) (Metadata)

Replaces the whole metadata object (no merge). Omit to keep the current one. At least one of name or metadata is required.

Responses

Request samples

Content type
application/json
{
  • "name": "Jane Smith",
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "sessions": [
    ],
  • "metadata": { }
}

Delete User

Permanently delete a user and all associated sessions and memory blocks. This operation is irreversible — there is no soft-delete or recovery.

Authorizations:
HTTPBearer
path Parameters
user_id
required
string (User Id)

Unique identifier for the user

Responses

Response samples

Content type
application/json
Example
{
  • "error": "AUTHENTICATION_REQUIRED",
  • "message": "Authentication required"
}

Update Memory Block TTL

Update the time-to-live (TTL) for memory blocks belonging to a user. Optionally scope the update to one session, or to specific block IDs within that session (block_ids requires session_id). Every targeted session must already be ended; open sessions are rejected before any block is retimed.

Authorizations:
HTTPBearer
path Parameters
user_id
required
string (User Id)

Unique identifier for the user

Request Body schema: application/json
required
Session Id (string) or Session Id (null) (Session Id)

Session to retime. Omit to retime every session the user owns. Every targeted session must already be ended.

Array of Block Ids (strings) or Block Ids (null) (Block Ids)

Retime only these blocks. Requires session_id, and every ID must belong to that session.

new_ttl
required
integer (New Ttl) >= 0

New TTL in seconds, counted from this call. 0 removes the expiry so the blocks never expire.

Responses

Request samples

Content type
application/json
{
  • "session_id": "string",
  • "block_ids": [
    ],
  • "new_ttl": 0
}

Response samples

Content type
application/json
null

List User Sessions

Retrieve a user's sessions, including lifecycle state and annotations, paginated. Returns an empty list if the user has no sessions.

Authorizations:
HTTPBearer
path Parameters
user_id
required
string (User Id)

Unique identifier for the user

query Parameters
limit
integer (Limit) [ 1 .. 500 ]
Default: 50
offset
integer (Offset) >= 0
Default: 0

Responses

Response samples

Content type
application/json
{
  • "sessions": [
    ],
  • "count": 0,
  • "total": 0,
  • "limit": 1,
  • "offset": 0
}

Sessions

Create and manage conversation sessions. A session scopes memory blocks and defines the default retrieval boundary for semantic search.

Sessions have a two-state lifecycle:

  • Open (default) - memory can be added, updated, searched, and deleted.
  • Ended - the session is read-only; no new memory blocks can be added. Call POST /users/{user_id}/sessions/{session_id}/end to end a session.

Deleting a session cascades to all of its memory blocks.

Create Session

Create a new session for the specified user. The session_id must be unique per user — attempting to create a session with a duplicate ID returns a conflict error.

Authorizations:
HTTPBearer
path Parameters
user_id
required
string (User Id)

Unique identifier for the user

Request Body schema: application/json
required
session_id
required
string (Session Id)

Session ID, unique per user. Must not be blank. A duplicate returns 409.

Annotations (object) or Annotations (null) (Annotations)

String key/value labels stored with the session.

Metadata (object) or Metadata (null) (Metadata)

Free-form JSON stored with the session.

Memory Blocks Ttl (integer) or Memory Blocks Ttl (null) (Memory Blocks Ttl)

Default TTL in seconds for blocks added to this session without their own memory_block_ttl. Omit or 0 for no session default: blocks then use AGENTMEMORY_MEMORY_BLOCK_TTL if set, otherwise never expire.

Responses

Request samples

Content type
application/json
{
  • "session_id": "session_456",
  • "annotations": {
    },
  • "metadata": {
    },
  • "memory_blocks_ttl": 3600
}

Response samples

Content type
application/json
{
  • "user_id": "string",
  • "session_id": "string",
  • "start_time": "string",
  • "end_time": "string",
  • "annotations": {
    },
  • "metadata": { },
  • "blocks_ttl": 0
}

Get Session

Retrieve a session by ID, including its lifecycle state, annotations, and metadata.

Authorizations:
HTTPBearer
path Parameters
user_id
required
string (User Id)

Unique identifier for the user

session_id
required
string (Session Id)

Unique identifier for the session

Responses

Response samples

Content type
application/json
{
  • "user_id": "string",
  • "session_id": "string",
  • "start_time": "string",
  • "end_time": "string",
  • "annotations": {
    },
  • "metadata": { },
  • "blocks_ttl": 0
}

Update Session

Update a session's annotations and/or metadata. At least one field must be provided. Omitted fields retain their existing values.

Authorizations:
HTTPBearer
path Parameters
user_id
required
string (User Id)

Unique identifier for the user

session_id
required
string (Session Id)

Unique identifier for the session

Request Body schema: application/json
required
Annotations (object) or Annotations (null) (Annotations)

Replaces all session annotations (no merge). Omit to keep them. Must not be an empty object.

Metadata (object) or Metadata (null) (Metadata)

Replaces all session metadata (no merge). Omit to keep it. Must not be an empty object.

Responses

Request samples

Content type
application/json
{
  • "annotations": {
    },
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "user_id": "string",
  • "session_id": "string",
  • "start_time": "string",
  • "end_time": "string",
  • "annotations": {
    },
  • "metadata": { },
  • "blocks_ttl": 0
}

Delete Session

Permanently delete a session and all its memory blocks. This operation is irreversible.

Authorizations:
HTTPBearer
path Parameters
user_id
required
string (User Id)

Unique identifier for the user

session_id
required
string (Session Id)

Unique identifier for the session

Responses

Response samples

Content type
application/json
Example
{
  • "error": "AUTHENTICATION_REQUIRED",
  • "message": "Authentication required"
}

End Session

Mark a session as ended. Once ended, no new memory blocks can be added. Existing memory blocks remain readable and searchable. Returns the updated session with end_time set.

Authorizations:
HTTPBearer
path Parameters
user_id
required
string (User Id)

Unique identifier for the user

session_id
required
string (Session Id)

Unique identifier for the session

Responses

Response samples

Content type
application/json
{
  • "user_id": "string",
  • "session_id": "string",
  • "start_time": "string",
  • "end_time": "string",
  • "annotations": {
    },
  • "metadata": { },
  • "blocks_ttl": 0
}

Memory

Add, retrieve, update, and search memory blocks. A memory block is the atomic unit of knowledge - each block holds either a chat message exchange or a standalone fact, and is automatically processed for semantic search.

Adding memory - Submit messages or facts in a single request. Semantic extraction runs asynchronously by default; blocks are readable and searchable immediately, and their extracted facts appear once extraction completes.

Searching memory - Provide a natural-language query to retrieve semantically similar blocks. Search is session-scoped by default. Set filters.session_ids to "all" to search across all sessions for a user. Blocks still being processed are returned with their raw content.

TTL and expiry - Memory blocks carry an optional time-to-live in seconds. TTL can be set per-block, per-session, or globally via server configuration.

Add Memory Blocks

Add one or more memory blocks to the session. Each block holds either a chat message (user + assistant turn) or a fact (declarative string). Blocks are written immediately and queued for semantic extraction. The session must be open — ended sessions reject new blocks.

Authorizations:
HTTPBearer
path Parameters
user_id
required
string (User Id)

Unique identifier for the user

session_id
required
string (Session Id)

Unique identifier for the session

Request Body schema: application/json
required
Array of Messages (objects) or Messages (null) (Messages)

Chat exchanges to store, one block per message. Send exactly one of messages or facts.

Array of Facts (strings) or Facts (null) (Facts)

Facts to store, one block per fact. Each must be non-blank. Send exactly one of messages or facts.

Annotations (object) or Annotations (null) (Annotations)

Keys must match ^[a-zA-Z_][a-zA-Z0-9_]*$ (letters, digits, underscore; not starting with a digit): each key becomes an index field and a query identifier. Values are free-form strings.

Created At (string) or Created At (null) (Created At)

ISO 8601 timestamp indicating when the data was originally created. Defaults to the ingestion time if not provided.

async_processing
boolean (Async Processing)
Default: true

If true, returns once blocks are stored with status processing, and LLM extraction runs in the background. If false, extraction finishes before the response. Embeddings are always generated before the response, so blocks are searchable either way.

Memory Block Ttl (integer) or Memory Block Ttl (null) (Memory Block Ttl)

TTL in seconds for the new blocks; 0 means never expire. Omit to use the session's blocks_ttl, then AGENTMEMORY_MEMORY_BLOCK_TTL, otherwise no expiry.

Context Required (boolean) or Context Required (null) (Context Required)

Whether to run LLM extraction (summary and contexts). Omit to use AGENTMEMORY_EXTRACT_SEMANTIC (default true).

Prompt Id (string) or Prompt Id (null) (Prompt Id)

Registry prompt_id to use for extraction. Must already exist (and not be archived) - an unresolvable prompt_id rejects the whole call before any work is done.

Prompt Vid (integer) or Prompt Vid (null) (Prompt Vid)

Pin extraction to this exact immutable registry version of prompt_id, rather than late-binding to whatever prompt_id currently says. Requires prompt_id to also be provided in the same call - rejected otherwise.

Responses

Request samples

Content type
application/json
{
  • "messages": [
    ],
  • "facts": [
    ],
  • "annotations": {
    },
  • "created_at": "2024-06-15T12:00:00",
  • "async_processing": true,
  • "memory_block_ttl": 3600,
  • "context_required": true,
  • "prompt_id": "support_tickets",
  • "prompt_vid": 1
}

Response samples

Content type
application/json
{
  • "message": "Successfully added 2 memory block(s)",
  • "accepted_count": 2,
  • "block_ids": [
    ],
  • "rejected_count": 1,
  • "rejected_details": {
    }
}

Delete Memory Blocks

Delete memory blocks by ID. Pass a list of block IDs to delete specific blocks, or "all" to delete every block in the session.

Authorizations:
HTTPBearer
path Parameters
user_id
required
string (User Id)

Unique identifier for the user

session_id
required
string (Session Id)

Unique identifier for the session

Request Body schema: application/json
required
required
Array of Block Ids (strings) or "all" (string) (Block Ids)

Block IDs to delete, or "all" for every block in the session.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "deleted_count": 0,
  • "failed_count": 0,
  • "failed_block_ids": [ ]
}

Update Memory Block

Update the content, annotations, or TTL of an existing memory block. Providing a new message or fact triggers re-extraction (new embedding and summary). Changing prompt_id or prompt_vid also triggers re-extraction. Omitted fields retain their existing values. To retry a block with status: extraction_failed, resend its message or fact: that re-runs extraction and resets fail_count. async_processing only controls whether that extraction runs in the background. If the block does not exist or has expired due to TTL, responds with 404.

Authorizations:
HTTPBearer
path Parameters
user_id
required
string (User Id)

Unique identifier for the user

session_id
required
string (Session Id)

Unique identifier for the session

block_id
required
string (Block Id)

Unique identifier for the memory block

Request Body schema: application/json
required
ChatMessage (object) or null

New content for a message block. Rejected on a fact block. Re-embeds the block and re-runs extraction.

Fact (string) or Fact (null) (Fact)

New content for a fact block. Rejected on a message block. Re-embeds the block and re-runs extraction.

Annotations (object) or Annotations (null) (Annotations)

New annotations to overwrite existing ones. If None, existing annotations are preserved. Keys must match ^[a-zA-Z_][a-zA-Z0-9_]*$ (letters, digits, underscore; not starting with a digit): each key becomes an index field and a query identifier. Values are free-form strings.

Memory Block Ttl (integer) or Memory Block Ttl (null) (Memory Block Ttl)

New TTL in seconds. If None, existing TTL is preserved.

async_processing
boolean (Async Processing)
Default: false

If True, semantic extraction runs in background via queue.

Context Required (boolean) or Context Required (null) (Context Required)

Whether semantic extraction is required. If None, uses environment variable.

Prompt Id (string) or Prompt Id (null) (Prompt Id)

Omit to inherit the block's existing prompt_id/prompt_vid. Pass the literal string "default" to explicitly clear both to None. Pass a real prompt_id to switch - must already exist (and not be archived).

Prompt Vid (integer) or Prompt Vid (null) (Prompt Vid)

Pin extraction to this exact immutable registry version of prompt_id. Requires a real prompt_id in this same call - rejected if prompt_id is omitted or is 'default'.

Responses

Request samples

Content type
application/json
{
  • "message": {
    },
  • "fact": "Updated fact about the user",
  • "annotations": {
    },
  • "memory_block_ttl": 3600,
  • "async_processing": true,
  • "context_required": true,
  • "prompt_id": "support_tickets",
  • "prompt_vid": 1
}

Response samples

Content type
application/json
{
  • "message": "Memory block updated successfully",
  • "block": {
    }
}

Search Memory

Retrieve memory blocks using semantic similarity and/or filters. Provide a natural-language query to rank blocks by relevance, or use filters alone for deterministic retrieval. Search is session-scoped by default — set filters.session_ids to "all" to search across all sessions for the user. Blocks still being processed are included and carry their raw content until extraction finishes.

Authorizations:
HTTPBearer
path Parameters
user_id
required
string (User Id)

Unique identifier for the user

session_id
required
string (Session Id)

Unique identifier for the session

Request Body schema: application/json
required
Query (string) or Query (null) (Query)

Natural-language text to rank blocks by semantic similarity. Omit to retrieve by filters only.

FilterOptions (object) or null

Scope and filters. Omit to search the current session with defaults.

Responses

Request samples

Content type
application/json
{
  • "query": "What are the user's preferences?",
  • "filters": {
    }
}

Response samples

Content type
application/json
{
  • "memory_blocks": [
    ],
  • "count": 0
}

List Memory Blocks

Paginated list of memory blocks for a user, ordered newest first. Use session_ids to scope results to specific sessions. Always specify limit and offset — unbounded requests on large datasets are slow.

Authorizations:
HTTPBearer
path Parameters
user_id
required
string (User Id)

Unique identifier for the user

query Parameters
Session Ids (string) or Session Ids (null) (Session Ids)

Comma-separated session IDs to filter by, or 'all' for all sessions

limit
integer (Limit) [ 1 .. 200 ]
Default: 20

Maximum number of memory blocks to return (1–200)

offset
integer (Offset) >= 0
Default: 0

Number of memory blocks to skip for pagination

order_by
string (Order By)
Default: "ingested_at"
Enum: "ingested_at" "created_at"

Field to order results by. Defaults to 'ingested_at'.

Responses

Response samples

Content type
application/json
{
  • "memory_blocks": [
    ],
  • "count": 0,
  • "total": 0,
  • "limit": 1,
  • "offset": 0
}

Prompts

Manage the custom extraction prompt registry. A prompt is a named, versioned block of extraction instructions that add_memory/update_memory can reference by prompt_id to customize what gets extracted from a memory block, without touching the locked output schema.

prompt_id is the only identifier - fixed at creation, no renaming. Every update to prompt text appends to an audit-only version history; there is no rollback endpoint.

Create Prompt

Register a new named custom extraction prompt. prompt_id must be globally unique -- a duplicate, or a previously archived prompt_id, returns a conflict error. A previously purged prompt_id is genuinely gone and can be freely re-registered.

Authorizations:
HTTPBearer
Request Body schema: application/json
required
prompt_id
required
string (Prompt Id) <= 128 characters ^[a-zA-Z0-9_-]+$

Only letters, digits, underscores, and hyphens - avoids collision with the internal prompt:::: key encoding. Max 128 characters. Cannot be one of the reserved sentinel values: ['default'].

prompt
required
string (Prompt) <= 4000 characters

Max 4000 characters (~1000 tokens) - keeps custom instructions well within any model's context budget alongside real block content.

description
required
string (Description) <= 200 characters

Short, human-written summary of what this prompt is for - shown in GET /prompts list results for discoverability. No fixed template required; aim for something like the example.

Annotations (object) or Annotations (null) (Annotations)

String key/value labels. Not versioned.

Responses

Request samples

Content type
application/json
{
  • "prompt_id": "support_tickets",
  • "prompt": "Focus on product issues, error codes, and resolution steps.",
  • "description": "Use for support ticket extraction - focuses on product issues and resolution steps",
  • "annotations": {
    }
}

Response samples

Content type
application/json
{
  • "prompt_id": "string",
  • "prompt": "string",
  • "description": "string",
  • "annotations": {
    },
  • "current_vid": 0,
  • "version_count": 0,
  • "last_updated_at": "string",
  • "archived": false
}

List Prompts

List registered prompts (lean head-doc shape, no version history), paginated. Archived prompts are included, flagged via archived.

Authorizations:
HTTPBearer
query Parameters
limit
integer (Limit) [ 1 .. 1000 ]
Default: 100
offset
integer (Offset) >= 0
Default: 0

Responses

Response samples

Content type
application/json
{
  • "prompts": [
    ],
  • "count": 0,
  • "total": 0,
  • "limit": 1,
  • "offset": 0
}

Get Prompt

Retrieve a prompt's current state, or (if vid is given) a single historical version's text along with whether it's archived and whether it's the current version. Use GET .../versions for the full history.

Authorizations:
HTTPBearer
path Parameters
prompt_id
required
string (Prompt Id) ^[a-zA-Z0-9_-]+$

Unique identifier for the prompt

query Parameters
vid
integer (Vid) >= 0

If given, retrieve this specific version instead.

Responses

Response samples

Content type
application/json
Example
{
  • "prompt_id": "string",
  • "prompt": "string",
  • "description": "string",
  • "annotations": {
    },
  • "current_vid": 0,
  • "version_count": 0,
  • "last_updated_at": "string",
  • "archived": false
}

Update Prompt

Update a prompt. Providing prompt creates a new, immutable version; description/annotations are updated in place and never versioned. Omitting a field preserves its existing value. Returns a conflict error if the prompt has been archived.

Authorizations:
HTTPBearer
path Parameters
prompt_id
required
string (Prompt Id) ^[a-zA-Z0-9_-]+$

Unique identifier for the prompt

Request Body schema: application/json
required
Prompt (string) or Prompt (null) (Prompt)

Max 4000 characters (~1000 tokens). Omit to preserve the existing text (no new version created).

Description (string) or Description (null) (Description)

Omit to preserve the existing description. Never versioned (same as annotations) - updating it does not create a new prompt version.

Annotations (object) or Annotations (null) (Annotations)

Replaces all annotations (no merge). Omit to keep them. Never versioned.

Responses

Request samples

Content type
application/json
{
  • "prompt": "Focus on billing disputes and refund policy exceptions.",
  • "description": "Use for billing-dispute extraction - refunds and exceptions",
  • "annotations": {
    }
}

Response samples

Content type
application/json
{
  • "prompt_id": "string",
  • "prompt": "string",
  • "description": "string",
  • "annotations": {
    },
  • "current_vid": 0,
  • "version_count": 0,
  • "last_updated_at": "string",
  • "archived": false
}

Purge Prompt

Permanently delete a prompt (vid=all) or a single version of it (vid=<int>). Irreversible. vid=all removes the prompt and its entire history and frees prompt_id for re-registration; memory blocks still queued against it fall back to the default extraction behavior. vid=<int> removes just that one version, leaving the rest of the history untouched.

Authorizations:
HTTPBearer
path Parameters
prompt_id
required
string (Prompt Id) ^[a-zA-Z0-9_-]+$

Unique identifier for the prompt

query Parameters
vid
required
string (Vid)

"all" for the whole prompt, or a version number for just that one version. Required -- there is no default -- so a caller can never silently escalate to the wrong scope by omitting it.

Responses

Response samples

Content type
application/json
{
  • "error": "INVALID_REQUEST",
  • "message": "Invalid request"
}

List Prompt Versions

List a prompt's version history, paginated. Each item indicates whether that specific version is archived and whether it's the current version. Returns a not-found error if prompt_id doesn't exist.

Authorizations:
HTTPBearer
path Parameters
prompt_id
required
string (Prompt Id) ^[a-zA-Z0-9_-]+$

Unique identifier for the prompt

query Parameters
limit
integer (Limit) [ 1 .. 1000 ]
Default: 100
offset
integer (Offset) >= 0
Default: 0

Responses

Response samples

Content type
application/json
{
  • "versions": [
    ],
  • "count": 0,
  • "total": 0,
  • "limit": 1,
  • "offset": 0
}

Archive Prompt

Archive a prompt (vid=all) or a single version of it (vid=<int>) without deleting it -- content and history are retained. vid=all blocks all new references and permanently reserves prompt_id against reuse; vid=<int> blocks only new references pinned to that exact version. Anything already in progress resolves normally either way.

Authorizations:
HTTPBearer
path Parameters
prompt_id
required
string (Prompt Id) ^[a-zA-Z0-9_-]+$

Unique identifier for the prompt

query Parameters
vid
required
string (Vid)

"all" for the whole prompt, or a version number for just that one version. Required -- there is no default -- so a caller can never silently escalate to the wrong scope by omitting it.

Responses

Response samples

Content type
application/json
{
  • "error": "INVALID_REQUEST",
  • "message": "Invalid request"
}

Health

Monitor the operational status of AgentMemory and its dependencies.

GET /health is a public endpoint suitable for load balancer health probes. All other health endpoints require authentication and provide deeper diagnostic detail about the database connection, model service availability, and the semantic extraction queue.

Status Meaning
healthy Component is operating normally
degraded Component is reachable but not fully functional
unhealthy Component is unreachable or critically impaired

Check Server Health

Return server health status, version, and uptime. Public endpoint — no authentication required.

Responses

Response samples

Content type
application/json
{
  • "status": "healthy",
  • "version": "string",
  • "uptime_seconds": 0
}

Check Database Health

Verify that AgentMemory can reach and query the Couchbase database.

Authorizations:
HTTPBearer

Responses

Response samples

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

Check Model Service Health

Check reachability and status of the configured embedding and LLM model services. status is healthy when both models are healthy, degraded when either is rate limited, and unhealthy when either is in any other state, in which case memory routes that need that model return 503.

Authorizations:
HTTPBearer

Responses

Response samples

Content type
application/json
{
  • "status": "healthy",
  • "embedding": {
    },
  • "llm": {
    }
}

Check Extraction Queue Health

Return lightweight readiness status for the semantic extraction queue.

Authorizations:
HTTPBearer

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "message": "string",
  • "queue": {
    },
  • "rate_budget": {
    },
  • "statistics": {
    },
  • "loop_running": true,
  • "dispatcher_alive": true
}

Get Extraction Queue Statistics

Return detailed queue depth, model API rate budget, and cumulative throughput statistics for the semantic extraction queue.

Authorizations:
HTTPBearer

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "message": "string",
  • "queue": {
    },
  • "rate_budget": {
    },
  • "statistics": {
    },
  • "loop_running": true,
  • "dispatcher_alive": true
}

Check Memory Pressure Status

Return current memory usage relative to the configured quota threshold. When usage exceeds the threshold, new ingestion requests are rejected until pressure subsides.

Authorizations:
HTTPBearer

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "message": "string",
  • "accepting_requests": true,
  • "usage_percent": 0,
  • "threshold_percent": 0,
  • "last_check": 0
}

Metrics

Expose Prometheus-compatible metrics for monitoring and alerting. This endpoint is public and requires no authentication, making it suitable for Prometheus scrape targets and infrastructure monitoring tools.

Scrape Prometheus Metrics

Responses

Response samples

Content type
application/json
null

Logs

Download a ZIP archive of server logs and optional system diagnostics. Use this endpoint to collect diagnostic data for support requests or incident post-mortems. Requires authentication.

Download Diagnostic Logs

Download server logs and optional system diagnostics as a ZIP archive. Use log_types to select log categories and start_time/end_time to narrow the time range. Add sys_commands to include live system snapshots (CPU, memory, disk, network) in the archive. Include this archive in support requests and incident post-mortems.

Authorizations:
HTTPBearer
query Parameters
Start Time (string) or Start Time (null) (Start Time)

Include log lines at or after this timestamp

End Time (string) or End Time (null) (End Time)

Include log lines at or before this timestamp

Array of Log Types (strings) or Log Types (null) (Log Types)

Log categories to include

Array of Sys Commands (strings) or Sys Commands (null) (Sys Commands)

Optional system commands to run and include in the archive

Responses

Response samples

Content type
application/json
null