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 App Service/container health checks and load-balancer 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.

Admin UI BFF: Handbook Policy Review

The Admin UI BFF OpenAPI is owned by packages/admin-contracts/openapi.yaml. docs/openapi/admin-api.json is not the complete dashboard BFF contract.

Handbook policy-review browser calls use /admin-api/* locally and /dashboard/admin-api/* in testing. The route definitions are in apps/admin-api/src/routes/admin/handbook-rag.ts.

Method	BFF path after /admin-api	Description
GET	/admin/handbook/policy-review	Read policy-review dashboard state, including DB-backed artifact options, selected artifacts, active job, job history, saved runs, run detail, findings, checklist review, usage summary, and diagnostics.
POST	/admin/handbook/policy-review/run	Enqueue a policy-review run. Body may include ownerScopeId, policyArtifactId, and handbookArtifactId.
POST	/admin/handbook/policy-review/retry	Retry a failed policy-review job. Body may include jobId.
POST	/admin/handbook/policy-review/resume	Resume/view a saved run. Body requires runId.
POST	/admin/handbook/policy-review/findings/:findingId/actions	Record reviewer action: mark_reviewed, request_district_input, accept_suggested_wording, dismiss_as_local_only, or reopen.
POST	/admin/handbook/policy-review/findings/:findingId/feedback	Record quality feedback with evidenceQuality, reasoningQuality, and outcomeAccuracy.
POST	/admin/handbook/rag-presets/pdf-jobs	Prepare uploaded PDFs for Handbook RAG or policy review. Use preparationMode: "reviewable-unit-v2" or policyReviewPreparation: true for Review Flow.

The six /policy-review routes return the same dashboard projection shape (handbook.policy-review-admin-dashboard.v1) so the UI can update selectors, job state, run detail, findings, checklist flags, and diagnostics after each mutation.

The OpenAPI source includes typed request schemas for the policy-review mutations and PDF preparation body, while the dashboard projection remains a named generic projection because it carries nested run/finding/checklist data.

The one-page product UI is:

/admin/?dashboardScope=handbook&dashboardTab=policy-review-flow

The detailed findings queue is:

/admin/?dashboardScope=handbook&dashboardTab=policy-review

For source-level payload details, DB tables, checklist behavior, and verification notes, see Handbook API, Handbook Policy Review, and docs/internal/handbook/policy-review-admin-api.md.