Admin APIs

Admin APIs give platform administrators and auditors elevated access to Memory Service data — across all users, including archived resources. They are available under the /v1/admin/ path prefix and require the admin or auditor 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>"

Similarly, entries, memberships, forks, attachments, and semantic search all have admin counterparts that bypass ownership checks. Admin conversation payloads expose an archived boolean so clients can distinguish archived records without depending on storage timestamps.

Archiving And Unarchiving Conversations

Admins archive and unarchive conversations by patching the conversation resource:

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. 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
curl "http://localhost:8080/v1/admin/attachments/{id}/content" \
  -H "Authorization: Bearer <admin-token>" \
  -o file.bin

# Get a signed download URL
curl "http://localhost:8080/v1/admin/attachments/{id}/download-url" \
  -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