Admin APIs

Admin APIs give platform administrators and auditors elevated access to Memory Service data — across all users, including archived resources. Most administrative resources are available under the /v1/admin/ path prefix. Episodic memory administration uses /admin/v1/... routes because memory APIs already reserve /v1/memories for agent-facing memory operations. Admin APIs require the admin or auditor role unless an endpoint documents a stricter role.

How Admin APIs Differ from Regular APIs

The regular Agent APIs are scoped to the authenticated caller: a user can only see their own conversations, their own attachments, and resources they have been explicitly shared. Admin APIs remove those ownership boundaries.

Key differences:

Roles

There are three admin roles, each granting a different level of privilege:

Roles can be assigned via OIDC token roles, explicit user lists, or API key client IDs. See the Admin Access Configuration section of the configuration guide for details.

Justification and Audit Logging

Every admin API call is written to a structured audit log entry. This provides a tamper-evident record of who accessed what data and why.

Providing a Justification

All admin endpoints accept an optional justification parameter. For GET endpoints it is a query parameter; for write endpoints it may also appear in the request body.

# Query parameter (GET requests)
curl "http://localhost:8080/v1/admin/conversations?justification=Support+ticket+%231234" \
  -H "Authorization: Bearer <admin-token>"

# Request body (write requests)
curl -X PATCH "http://localhost:8080/v1/admin/conversations/{id}" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <admin-token>" \
  -d '{"archived": true, "justification": "User requested account cleanup per support ticket #789"}'

Requiring Justification

By default, justification is optional. Set --admin-require-justification (or MEMORY_SERVICE_ADMIN_REQUIRE_JUSTIFICATION=true) to make it mandatory — any admin call without a justification will receive a 400 Bad Request response. This is recommended for regulated environments.

Audit Log Format

Each audit log entry is emitted as a structured INFO-level log message with the prefix Admin audit and the following fields:

The log level is controlled via the MEMORY_SERVICE_LOG_LEVEL environment variable (default: info). To route admin audit entries to a separate sink, filter on the Admin audit message prefix in your log aggregation pipeline.

Reading Data Across Users

Admin and auditor endpoints mirror most regular APIs but operate system-wide. For example, listing conversations:

# List all conversations across all users
curl "http://localhost:8080/v1/admin/conversations" \
  -H "Authorization: Bearer <admin-token>"

# Filter to a specific user
curl "http://localhost:8080/v1/admin/conversations?userId=alice" \
  -H "Authorization: Bearer <admin-token>"

# Include archived conversations alongside active ones
curl "http://localhost:8080/v1/admin/conversations?archived=include" \
  -H "Authorization: Bearer <admin-token>"

# Show only archived conversations
curl "http://localhost:8080/v1/admin/conversations?archived=only" \
  -H "Authorization: Bearer <admin-token>"

# Filter by an exact string metadata value
curl --globoff "http://localhost:8080/v1/admin/conversations?metadata[status]=waiting" \
  -H "Authorization: Bearer <admin-token>"

Only one metadata filter is accepted per request. Metadata filter keys may contain alphanumeric characters, underscores, and hyphens; dots are rejected. Matching is exact and string-only, so numeric and boolean metadata values do not match the query value.

Similarly, entries, memberships, forks, attachments, episodic memories, and semantic search all have admin counterparts that bypass ownership checks. Admin conversation payloads expose the metadata map and an archived boolean so clients can inspect conversation state without depending on storage timestamps.

Getting Entries

Admins can retrieve entries from any conversation or fetch a specific entry by its ID:

# Get all entries from a conversation (including archived)
curl "http://localhost:8080/v1/admin/conversations/{conversationId}/entries" \
  -H "Authorization: Bearer <admin-token>"

# Get a specific entry by ID (works across all conversations)
curl "http://localhost:8080/v1/admin/entries/{entryId}" \
  -H "Authorization: Bearer <admin-token>"

The entry-by-ID endpoint is useful for audit trails, debugging, or when you have an entry UUID but don’t know which conversation it belongs to.

Episodic Memory Administration

Episodic memory admin routes use /admin/v1/... instead of /v1/admin/.... Read-only exploration endpoints allow admin or auditor; operational and destructive endpoints require admin.

See Memories for request parameters and examples.

Updating Conversations

Admins can update a conversation’s title and metadata by patching the conversation resource. Metadata uses top-level merge-patch semantics: provided non-null values replace complete top-level values, omitted keys remain unchanged, and keys set to null are removed.

curl -X PATCH "http://localhost:8080/v1/admin/conversations/{id}" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <admin-token>" \
  -d '{
    "title": "Escalated support case",
    "metadata": {"status": "reviewed", "queue": null},
    "justification": "Support ticket #456"
  }'

The same endpoint archives and unarchives the conversation fork tree:

curl -X PATCH "http://localhost:8080/v1/admin/conversations/{id}" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <admin-token>" \
  -d '{"archived": false, "justification": "User accidentally archived the conversation — support ticket #456"}'

Set archived to true to archive the fork tree or false to unarchive it. All updates require the admin role, and the response is the updated conversation object.

Eviction: Permanently Removing Archived Data

Archiving keeps data recoverable. Eviction permanently removes resources that have been archived for longer than a specified retention period. This operation is irreversible and requires the admin role.

When to Use Eviction

• Enforcing a data retention policy (e.g., purge conversations archived more than 90 days ago)
• Satisfying a GDPR/right-to-erasure request
• Reclaiming storage after bulk deletes

Synchronous Eviction

By default, the eviction call blocks until complete and returns 204 No Content:

curl -X POST "http://localhost:8080/v1/admin/evict" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <admin-token>" \
  -d '{
    "retentionPeriod": "P90D",
    "resourceTypes": ["conversations"],
    "justification": "Quarterly data cleanup per retention policy"
  }'

The retentionPeriod is an ISO 8601 duration. Common values:

Streaming Eviction (SSE)

For large datasets, use ?async=true (or set Accept: text/event-stream) to receive progress updates as Server-Sent Events instead of blocking:

curl -X POST "http://localhost:8080/v1/admin/evict?async=true" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <admin-token>" \
  -d '{
    "retentionPeriod": "P90D",
    "resourceTypes": ["conversations"],
    "justification": "Quarterly data cleanup per retention policy"
  }'

The response stream emits progress events from 0 to 100:

data: {"progress": 0}

data: {"progress": 25}

data: {"progress": 75}

data: {"progress": 100}

If eviction fails mid-run, an error event is emitted:

event: error
data: {"error": "Database connection failed"}

The eviction runs in batches internally to minimize database lock contention.

Admin Attachment Management

Admins can list, inspect, download, and delete attachments across all users:

# List all attachments (optionally filter by user or status)
curl "http://localhost:8080/v1/admin/attachments?userId=alice&status=unlinked" \
  -H "Authorization: Bearer <admin-token>"

# Get a specific attachment's metadata (including archived)
curl "http://localhost:8080/v1/admin/attachments/{id}" \
  -H "Authorization: Bearer <admin-token>"

# Download attachment content; add disposition=inline or attachment when needed
curl "http://localhost:8080/v1/admin/attachments/{id}/content?disposition=attachment" \
  -H "Authorization: Bearer <admin-token>" \
  -o file.bin

# Get a signed download URL with the same disposition behavior
curl "http://localhost:8080/v1/admin/attachments/{id}/download-url?disposition=attachment" \
  -H "Authorization: Bearer <admin-token>"

# Delete any attachment (admin only)
curl -X DELETE "http://localhost:8080/v1/admin/attachments/{id}" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <admin-token>" \
  -d '{"justification": "GDPR erasure request #999"}'

Attachment deletion uses reference-counting: the stored file blob is only removed when the last attachment record sharing it is deleted.

Admin Events Endpoint

The admin events endpoint streams all real-time events from all users, regardless of conversation membership:

curl -N -H "Authorization: Bearer $(get-admin-token)" \
  "http://localhost:8080/v1/admin/events?justification=Investigating+issue+%231234"

The justification value is optional by default and is logged for audit purposes when provided. If the server enables MEMORY_SERVICE_ADMIN_REQUIRE_JUSTIFICATION=true, admin event subscriptions without a justification are rejected with 400 Bad Request. See Real-Time Events for event format, kinds, and connection lifecycle details.

Admin Stats Summary Endpoint

GET /v1/admin/stats/summary returns a point-in-time inventory snapshot from the configured datastores. It is separate from the Prometheus-backed chart endpoints and works even when Prometheus is not configured.

The response includes nested totals for:

• conversationGroups
• conversations
• entries
• memories
• outboxEvents

conversationGroups.oldestArchivedAt is the oldest updatedAt timestamp among archived conversations. memories.oldestArchivedAt is the oldest memory archive timestamp. outboxEvents is null when the outbox feature is disabled or unsupported for the active datastore.

Next Steps

• Configure admin roles and audit logging in Service Configuration
• Browse the full endpoint specifications in API Contracts