API Reference

Overview

The Mastra Agent Framework provides REST APIs for managing agents, workflows, and administrative operations. Each domain exposes endpoints for invoking agents, executing tools, and running workflows.

Domain APIs

K12 API

EOP editing, QRG generation, and safety analysis endpoints with async kickoff/status/result pattern

TAP API

Batch tagging, image captioning, and content safety moderation endpoints

SDAC API

Cost report validation, AI-assisted review, and sendback preparation endpoints

Admin API

Agent profile management, health checks, and system administration

Ingestion Server API

FastAPI health, SDAC worker, session, upload, and operator route contracts

Widget API

Same-origin SDAC widget proxy routes for Replit/browser integration

Common Endpoint Patterns

The generated OpenAPI artifacts under docs/openapi/ are the source-backed contract for the current runtime. In testing, APIM may publish these runtime paths under an /ai prefix; for example, direct /sdac/tools/validate-fringe is commonly called as /ai/sdac/tools/validate-fringe through APIM.

Agent Endpoints

Method	Path	Description
GET	/agents.json	List registered agents for UI discovery
GET	/api/agents/{agentId}	Get Mastra SDK agent metadata
POST	/api/agents/{agentId}/generate	Invoke agent (non-streaming)
POST	/api/agents/{agentId}/stream	Invoke agent (streaming SSE)
POST	/{domain}/agents/{slug}/generate	Invoke a domain-friendly agent route
POST	/{domain}/agents/{slug}/stream	Stream a domain-friendly agent route

Tool Endpoints

Method	Path	Description
GET	/tools.json	List registered tools for UI discovery
POST	/api/tools/{toolId}/execute	Execute a tool
POST	/{domain}/tools/{slug}	Execute a domain-friendly tool route with flat JSON input

Workflow Endpoints

Method	Path	Description
GET	/workflows.json	List registered workflows for UI discovery
POST	/{domain}/workflows/{slug}/create-run	Create a workflow run
POST	/{domain}/workflows/{slug}/start	Start a workflow run
GET	/{domain}/workflows/{slug}/runs/{runId}	Get workflow run status

Domain Discovery

Method	Path	Description
GET	/{domain}/routes.json	Lists source-backed tool, agent, and workflow routes for one domain
GET	/mcp-servers.json	Lists registered MCP servers when runtime directory routes are enabled

Authentication

API endpoints use different authentication methods depending on the environment:

Production (Azure):

• Managed Identity authentication for Azure-hosted services
• API keys for external integrations via Azure API Management (APIM)

Development:

• Bearer tokens for local testing
• API keys for integration tests

Refer to each domain's documentation for specific authentication requirements and APIM gateway details.