Skip to main content
The Mastra server package provides a comprehensive set of routes for interacting with your agents, workflows, and tools via HTTP.

​
Available Route Groups

All routes are registered under your configured prefix (default: /api).

​
Agent Routes

Manage and interact with agents:
MethodPathDescription
GET/agentsList all registered agents
GET/agents/:agentIdGet agent metadata
POST/agents/:agentId/generateGenerate agent response
POST/agents/:agentId/streamStream agent response
Example: Generate Response 
curl -X POST http://localhost:3000/api/agents/myAgent/generate \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "What is 2+2?"}
    ]
  }'
Example: Stream Response 
const response = await fetch('http://localhost:3000/api/agents/myAgent/stream', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    messages: [{ role: 'user', content: 'Tell me a story' }],
  }),
});

const reader = response.body.getReader();
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  console.log(new TextDecoder().decode(value));
}

​
Workflow Routes

Execute and manage workflows:
MethodPathDescription
GET/workflowsList all registered workflows
GET/workflows/:workflowIdGet workflow metadata
POST/workflows/:workflowId/executeExecute a workflow
GET/workflows/:workflowId/runs/:runIdGet workflow run status
Example: Execute Workflow 
curl -X POST http://localhost:3000/api/workflows/myWorkflow/execute \
  -H "Content-Type: application/json" \
  -d '{
    "triggerData": {
      "userId": "123",
      "action": "process"
    }
  }'

​
Tool Routes

Discover and inspect available tools:
MethodPathDescription
GET/toolsList all tools
GET/tools/:toolIdGet tool metadata

​
Memory Routes

Interact with memory stores:
MethodPathDescription
GET/memory/:threadIdGet thread messages
POST/memory/:threadId/saveSave messages to thread
DELETE/memory/:threadIdDelete thread

​
Observability Routes

Access telemetry and tracing data:
MethodPathDescription
GET/observability/tracesList traces
GET/observability/traces/:traceIdGet trace details
POST/observability/scoresAdd score to trace
POST/observability/feedbackAdd feedback to trace

​
Log Routes

Query runtime logs:
MethodPathDescription
GET/logsQuery logs with filters
Example: Query Logs 
curl "http://localhost:3000/api/logs?level=error&limit=10"

​
Vector Routes

Vector store operations:
MethodPathDescription
POST/vectors/queryQuery vector store
POST/vectors/upsertUpsert vectors

​
Using Handlers Directly

You can also use handlers directly without the server adapter: 
import { agents } from '@mastra/server/handlers';
import { Mastra } from '@mastra/core';
import { RequestContext } from '@mastra/core/request-context';

const mastra = new Mastra({ /* config */ });

// Call handler directly
const result = await agents.generateHandler({
  mastra,
  requestContext: new RequestContext(),
  agentId: 'myAgent',
  messages: [{ role: 'user', content: 'Hello' }],
});

console.log(result);

​
Handler Groups

Handlers are organized into modules: 
import { 
  agents,       // Agent handlers
  workflows,    // Workflow handlers
  tools,        // Tool handlers
  memory,       // Memory handlers
  observability,// Observability handlers
  logs,         // Log handlers
  vector,       // Vector handlers
  voice,        // Voice handlers
} from '@mastra/server/handlers';

​
Response Types

Routes return different response types:

​
JSON Response

Standard JSON response for most routes: 
{
  "id": "agent-123",
  "name": "My Agent",
  "model": "gpt-4"
}

​
Stream Response

Server-Sent Events (SSE) or chunked streaming: 
// SSE format
data: {"type":"text-delta","text":"Hello"}
data: {"type":"text-delta","text":" world"}
data: [DONE]

// Or chunked format (default)
{"type":"text-delta","text":"Hello"}\x1E
{"type":"text-delta","text":" world"}\x1E

​
Error Response

Standardized error format: 
{
  "error": "Invalid request body",
  "issues": [
    {
      "field": "messages",
      "message": "Required"
    }
  ]
}

​
Request Validation

All routes validate requests using Zod schemas. Invalid requests return 400 status with detailed error messages: 
curl -X POST http://localhost:3000/api/agents/myAgent/generate \
  -H "Content-Type: application/json" \
  -d '{}'

# Response:
{
  "error": "Invalid request body",
  "issues": [
    {
      "field": "messages",
      "message": "Required"
    }
  ]
}

​
Next Steps

Middleware

Add authentication and custom middleware

Server Adapters

Learn about different server adapters

Build docs developers (and LLMs) love

Get started for freeTalk to us