Admin API

Overview

The Admin API provides endpoints for managing agent profiles, monitoring system health, and performing administrative operations on the Mastra Agent Framework.

This page covers runtime/admin route families. The Admin UI has its own BFF surface under /admin-api/*; see Admin Dashboard and docs/internal/documentation-revival/endpoint-catalog.md for the Replit/APIM route safety catalog. The committed docs/openapi/admin-api.json artifact is currently narrower than the active source route surface and should not be used as the only source of truth during the documentation revival.

Key Features

• Agent Profile Management - Create, update, and retrieve agent profiles with prompt overrides
• System Health Checks - Verify database connectivity and agent registry status
• Audit Trail - Track agent profile changes and configuration history
• Registry and configuration reads - Inspect registries, feature flags, model capabilities, and active profile state

Common Use Cases

Managing Agent Profiles

Use the Admin API to update agent prompts without redeploying code:

1. Retrieve current agent profile
2. Modify system prompt or LLM parameters
3. Update profile via API
4. Agents automatically rebuild with new configuration

Health Monitoring

Monitor system health and connectivity:

• Database connection status
• Agent registry validation
• LLM provider availability
• Content Safety service status

Health Monitoring

Two sets of health endpoints are available. They differ in purpose and cost.

Lightweight probes (/health)

Designed for load balancer and Kubernetes probes. No external calls — returns immediately.

Endpoint	Description	Response
GET /health	General liveness check	{ status: "healthy", timestamp, uptime }
GET /health/ready	Readiness check — service accepts traffic	{ status: "ready", timestamp }
GET /health/live	Liveness check — process is running	{ status: "alive", timestamp }

All three return HTTP 200 when healthy.

Detailed dependency probe (/admin/health/detailed)

Actively probes each external dependency (DB, LLM provider, Content Safety, search providers). Use for ops dashboards and incident triage.

GET /admin/health/detailed

Response shape:

{
  "status": "healthy | degraded | unhealthy",
  "timestamp": "2026-01-01T00:00:00.000Z",
  "uptime": 1234.5,
  "services": {
    "database": {
      "status": "healthy | degraded | unhealthy | unconfigured",
      "responseTimeMs": 42,
      "details": { ... }
    },
    "llmProvider": { ... },
    "contentSafety": { ... },
    "tavily": { ... },
    "perplexity": { ... }
  }
}

• HTTP 200 when status is healthy or degraded
• HTTP 503 when status is unhealthy
• Per-probe timeout: 5 seconds

Registry & Discovery

Runtime registries

Lightweight JSON endpoints that return a snapshot of loaded artifacts for the current MASTRA_TARGET. No authentication required.

Endpoint	Description
GET /tools.json	All admin + domain tools registered in the runtime
GET /agents.json	All agent registry IDs for the active target
GET /workflows.json	All workflow registry keys
GET /mcp-servers.json	MCP servers registered with Mastra

Each response includes target, count, and the ordered list of registry entries.

Domain discovery

Per-domain route manifests generated automatically from the agent, tool, and workflow registries:

GET /{domain}/routes.json

Example domains: k12, tap, sdac, admin. Response:

{
  "domain": "sdac",
  "toolCount": 40,
  "agentCount": 9,
  "workflowCount": 2,
  "tools": ["/sdac/tools/upload-cost-report", ...],
  "agents": ["/sdac/agents/coordinator/generate", "/sdac/agents/coordinator/stream", ...],
  "workflows": ["/sdac/workflows/validate-full-report"]
}

Domain agent endpoints

Each registered agent gets two auto-generated HTTP routes:

Method	Path	Description
POST	/{domain}/agents/{slug}/generate	Single-turn generation
POST	/{domain}/agents/{slug}/stream	SSE streaming response

Request body (both endpoints):

{ "messages": [{ "role": "user", "content": "..." }] }
// or shorthand:
{ "prompt": "..." }

Optional memory headers: X-User-Id and X-Thread-Id scope the conversation to an authenticated user and session.

Stream events (text/event-stream): delta, tool-call, tool-result, usage, done, error.

Authentication

There are multiple admin-adjacent route families. Do not treat them as one auth model.

Route family	Caller path	Auth boundary
Admin UI shell	/dashboard/admin/ via APIM, direct /admin/ on dashboard app	Dashboard/APIM entrypoint controls.
Admin UI BFF	/dashboard/admin-api/* in testing or local /admin-api/*	Browser sends Ocp-Apim-Subscription-Key; dashboard validates entry/auth settings.
Runtime admin API	Runtime /admin/*	APIM/dashboard forwards X-Mastra-Admin-Proxy-Secret; browser code should not call direct runtime /admin/*.
Docs chat	/docs/chat	Ocp-Apim-Subscription-Key; external scopes use APIM_SUBSCRIPTION_KEY, internal scope uses INTERNAL_DOCS_CHAT_API_KEY.
Runtime health/registries/domain routes	/health, /*.json, /{domain}/...	No shared admin proxy guard in route source; deployment/APIM policies decide exposure.
DB setup	/setup/db*	Operator/setup only; do not call from Replit.

The runtime admin proxy guard lives in packages/platform-runtime/src/server/routes/shared/admin-proxy-guard.ts and wraps /admin/* routes when APIM_GATEWAY_URL or ADMIN_PROXY_SHARED_SECRET is configured. It returns:

• 503 when the guard is required but not configured
• 401 when the upstream proxy secret header is missing
• 403 when the upstream proxy secret is invalid

Admin mutations also use actor headers where available:

• x-actor-id
• x-ms-client-principal-id

When no actor header is present, source routes commonly fall back to dashboard-user.

Operator Setup Routes

The runtime also registers a database setup UI and seed helpers. These routes are included in docs/openapi/runtime-routes-api.json so agents can see the whole code surface, but they are not Replit-safe and should not be called from shared UI workspaces.

Method	Path	Purpose	Replit guidance
GET	/setup/db	Operator HTML setup UI	Never call from Replit.
GET	/setup/db/agents	Read seedable JSON agents	Never call from Replit.
GET	/setup/db/capabilities	Read base LLM capabilities	Never call from Replit.
GET	/setup/db/agents/current	Read current database agent profiles	Never call from Replit.
GET	/setup/db/agents/control	Read cross-environment control-table agents	Never call from Replit.
POST	/setup/db/agents/control/seed	Seed selected control-table agents	Never call from Replit.
POST	/setup/db/seed	Seed model deployments, LLM params, and selected agents	Never call from Replit.