Server routes

Server adapters register these routes when you call server.init(). All routes are prefixed with the prefix option if configured.

Agents

Method	Path	Description
GET	/api/agents	List all agents
GET	/api/agents/:agentId	Get agent by ID (supports version query params)
POST	/api/agents/:agentId/generate	Generate agent response
POST	/api/agents/:agentId/stream	Stream agent response
POST	/api/agents/:agentId/send-message	Send a user message to an active or idle thread
POST	/api/agents/:agentId/queue-message	Queue a user message for the next thread turn
POST	/api/agents/:agentId/signals	Send a lower-level signal to an active or idle thread
POST	/api/agents/:agentId/threads/subscribe	Subscribe to a thread stream
POST	/api/agents/:agentId/send-tool-approval	Approve or decline a tool call and resume through a thread subscription
POST	/api/agents/:agentId/resume-stream	Resume a suspended agent stream with custom data
GET	/api/agents/:agentId/tools	List agent tools
POST	/api/agents/:agentId/tools/:toolId/execute	Execute agent tool

Get agent query parameters

GET /api/agents/:agentId accepts optional query parameters to control which stored config version is applied as overrides to code-defined agents:

Parameter	Type	Default	Description
status	'draft' | 'published'	'published'	Which stored version to resolve. draft returns the latest version, and published returns the active version.
versionId	string	None	A specific version ID to resolve. Takes precedence over status.

# Get agent with active published overrides (default)
GET /api/agents/my-agent

# Get agent with latest draft overrides
GET /api/agents/my-agent?status=draft

# Get agent with a specific version's overrides
GET /api/agents/my-agent?versionId=abc123

Generate request body

{
  messages: CoreMessage[] | string;       // Required
  instructions?: string;                   // System instructions
  system?: string;                         // System prompt
  context?: CoreMessage[];                 // Additional context
  memory?: { key: string } | boolean;      // Memory config
  resourceId?: string;                     // Resource identifier
  threadId?: string;                       // Thread identifier
  runId?: string;                          // Run identifier
  maxSteps?: number;                       // Max tool steps
  activeTools?: string[];                  // Tools to enable
  toolChoice?: ToolChoice;                 // Tool selection mode
  requestContext?: Record<string, unknown>; // Request context
  output?: ZodSchema;                      // Structured output schema
}

Generate response

{
  text: string;
  toolCalls?: ToolCall[];
  finishReason: string;
  usage?: {
    promptTokens: number;
    completionTokens: number;
  };
}

Agent message routes

Use POST /api/agents/:agentId/send-message to send a user message to the active agent loop or wake an idle thread. Use POST /api/agents/:agentId/queue-message when the active run should finish before Mastra starts a follow-up run.

Both routes accept the same request body:

{
  message: string | Array<TextPart | FilePart> | {
    contents: string | Array<TextPart | FilePart>;
    attributes?: Record<string, JSONValue>;
    metadata?: Record<string, unknown>;
    providerOptions?: ProviderMetadata;
  };
  runId?: string;
  resourceId?: string;
  threadId?: string;
  ifActive?: {
    behavior?: 'deliver' | 'persist' | 'discard';
    attributes?: Record<string, string | number | boolean>;
  };
  ifIdle?: {
    behavior?: 'wake' | 'persist' | 'discard';
    streamOptions?: Omit<AgentExecutionOptions, 'messages'>;
    attributes?: Record<string, string | number | boolean>;
  };
}

When runId is omitted, resourceId and threadId are required. ifIdle only applies to thread-targeted requests, not run-targeted requests.

Send a message

curl -X POST http://localhost:4111/api/agents/supportAgent/send-message \
  -H 'Content-Type: application/json' \
  -d '{
    "message": {
      "contents": "Show the shorter version.",
      "attributes": { "sentFrom": "web" }
    },
    "resourceId": "user_123",
    "threadId": "thread_456"
  }'

Queue a message

curl -X POST http://localhost:4111/api/agents/supportAgent/queue-message \
  -H 'Content-Type: application/json' \
  -d '{
    "message": "Also check whether the tests need updates.",
    "resourceId": "user_123",
    "threadId": "thread_456"
  }'

Both routes return:

{
  accepted: true;
  runId: string;
  signal?: CreatedAgentSignal;
}

Subscription tool approval routes

Use POST /api/agents/:agentId/send-tool-approval when the client already has an active thread subscription. The route resumes the run and returns a JSON acknowledgement. Resumed stream chunks are delivered through POST /api/agents/:agentId/threads/subscribe.

The route accepts this request body:

{
  resourceId: string;
  threadId: string;
  toolCallId: string;
  approved: boolean;
  requestContext?: Record<string, unknown>;
}

The route returns:

{
  accepted: true;
  runId: string;
  toolCallId?: string;
}

Workflows

Method	Path	Description
GET	/api/workflows	List all workflows
GET	/api/workflows/run-counts	Get per-workflow counts of running and suspended runs
GET	/api/workflows/:workflowId	Get workflow by ID
POST	/api/workflows/:workflowId/create-run	Create a new workflow run
POST	/api/workflows/:workflowId/start-async	Start workflow and await result
POST	/api/workflows/:workflowId/stream	Stream workflow execution
POST	/api/workflows/:workflowId/resume	Resume suspended workflow
POST	/api/workflows/:workflowId/resume-async	Resume asynchronously
GET	/api/workflows/:workflowId/runs	List workflow runs
GET	/api/workflows/:workflowId/runs/:runId	Get specific run

Run counts response

The /api/workflows/run-counts endpoint returns counts of running and suspended runs for every registered workflow. The record is keyed by the workflow's registry key from the Mastra config, and the server may cache the response for a few seconds:

{
  [workflowRegistryKey: string]: {
    running: number;
    suspended: number;
  };
}

Dynamic workflows

Dynamic workflow definitions (beta) are workflows expressed as JSON, persisted through the workflowDefinitions storage domain, and live-registered on the running instance. See Dynamic workflows.

Method	Path	Description
GET	/api/stored/workflows	List dynamic workflow definitions, filterable by status and authorId
GET	/api/stored/workflows/:dynamicWorkflowId	Get a dynamic workflow definition by ID
POST	/api/stored/workflows	Upsert a definition (plus optional helper dependencies) and live-register it
DELETE	/api/stored/workflows/:dynamicWorkflowId	Delete a dynamic workflow definition and unregister the live workflow

On authenticated servers, the read routes require the stored-workflows:read permission and the write routes require stored-workflows:write. Registered dynamic workflows are executed through the ordinary /api/workflows/:workflowId routes above.

Create run request body

{
  resourceId?: string;     // Associate run with a resource (e.g., user ID)
  disableScorers?: boolean; // Disable scorers for this run
}

Request body for /start-async

{
  resourceId?: string;     // Associate run with a resource (e.g., user ID)
  inputData?: unknown;
  initialState?: unknown;
  requestContext?: Record<string, unknown>;
  tracingOptions?: {
    spanName?: string;
    attributes?: Record<string, unknown>;
  };
}

Stream workflow request body

{
  resourceId?: string;     // Associate run with a resource (e.g., user ID)
  inputData?: unknown;
  initialState?: unknown;
  requestContext?: Record<string, unknown>;
  closeOnSuspend?: boolean;
}

Resume request body

{
  step?: string | string[];
  resumeData?: unknown;
  requestContext?: Record<string, unknown>;
}

Tools

Method	Path	Description
GET	/api/tools	List all tools
GET	/api/tools/:toolId	Get tool by ID
POST	/api/tools/:toolId/execute	Execute tool

Execute tool request body

{
  data: unknown;  // Tool input data
  requestContext?: Record<string, unknown>;
}

Memory

Method	Path	Description
GET	/api/memory/threads	List threads
GET	/api/memory/threads/:threadId	Get thread
POST	/api/memory/threads	Create thread
DELETE	/api/memory/threads/:threadId	Delete thread
POST	/api/memory/threads/:threadId/clone	Clone thread
GET	/api/memory/threads/:threadId/messages	Get thread messages
POST	/api/memory/threads/:threadId/messages	Add message

Create thread request body

{
  resourceId: string;
  title?: string;
  metadata?: Record<string, unknown>;
}

Clone thread request body

{
  newThreadId?: string;           // Custom ID for cloned thread
  resourceId?: string;            // Override resource ID
  title?: string;                 // Custom title for clone
  metadata?: Record<string, unknown>;  // Additional metadata
  options?: {
    messageLimit?: number;        // Max messages to clone
    messageFilter?: {
      startDate?: Date;           // Clone messages after this date
      endDate?: Date;             // Clone messages before this date
      messageIds?: string[];      // Clone specific messages
    };
  };
}

Clone thread response

{
  thread: {
    id: string;
    resourceId: string;
    title: string;
    createdAt: Date;
    updatedAt: Date;
    metadata: {
      clone: {
        sourceThreadId: string;
        clonedAt: Date;
        lastMessageId?: string;
      };
      // ... other metadata
    };
  };
  clonedMessages: MastraDBMessage[];
}

Vectors

Method	Path	Description
POST	/api/vectors/:vectorName/upsert	Upsert vectors
POST	/api/vectors/:vectorName/query	Query vectors
POST	/api/vectors/:vectorName/delete	Delete vectors

Upsert request body

{
  vectors: Array<{
    id: string
    values: number[]
    metadata?: Record<string, unknown>
  }>
}

Query request body

{
  vector: number[];
  topK?: number;
  filter?: Record<string, unknown>;
  includeMetadata?: boolean;
}

MCP

Method	Path	Description
GET	/api/mcp/servers	List MCP servers
GET	/api/mcp/servers/:serverId/tools	List server tools
POST	/api/mcp/:serverId	MCP HTTP transport
GET	/api/mcp/:serverId/sse	MCP SSE transport

Responses API

Method	Path	Description
POST	/api/v1/responses	Create a response through the OpenAI-compatible Responses API route
GET	/api/v1/responses/:responseId	Retrieve a stored response
DELETE	/api/v1/responses/:responseId	Delete a stored response

For the full request and response contract, see the Responses API reference.

Conversations API

Method	Path	Description
POST	/api/v1/conversations	Create a conversation
GET	/api/v1/conversations/:conversationId	Retrieve a conversation
DELETE	/api/v1/conversations/:conversationId	Delete a conversation
GET	/api/v1/conversations/:conversationId/items	List stored items for a conversation

For the full request and response contract, see the Conversations API reference.

Logs

Method	Path	Description
GET	/api/logs	List logs
GET	/api/logs/:runId	Get logs by run ID

Query parameters

{
  page?: number;
  perPage?: number;
  transportId?: string;
}

Telemetry

Method	Path	Description
GET	/api/telemetry/traces	List traces
GET	/api/telemetry/traces/:traceId	Get trace
GET	/api/telemetry/traces/:traceId/spans	Get trace spans

Common query parameters

Pagination

Most list endpoints support:

{
  page?: number;   // Page number (0-indexed)
  perPage?: number; // Items per page (default: 10)
}

Filtering

Workflow runs support:

{
  fromDate?: string;  // ISO date string
  toDate?: string;    // ISO date string
  status?: string;    // Run status filter
  resourceId?: string; // Filter by resource
}

Error responses

All routes return errors in this format:

{
  error: string;      // Error message
  details?: unknown;  // Additional details
}

Common status codes:

Code	Meaning
400	Bad Request - Invalid parameters
401	Unauthorized - Missing/invalid auth
403	Forbidden - Insufficient permissions
404	Not Found - Resource doesn't exist
500	Internal Server Error

Related

• createRoute(): Creating custom routes
• Server Adapters: Using adapters