> Discover all available pages from the documentation index: https://mastra.ai/llms.txt

# 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'` | `'draft'` | Which stored version to resolve. `draft` returns the latest version, `published` returns the active published version. |
| `versionId` | `string`                 | —         | A specific version ID to resolve. Takes precedence over `status`.                                                      |

```bash
# Get agent with latest draft overrides (default)
GET /api/agents/my-agent

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

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

### Generate request body

```typescript
{
  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

```typescript
{
  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:

```typescript
{
  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

```bash
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

```bash
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:

```typescript
{
  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:

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

The route returns:

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

## Workflows

| Method | Path                                      | Description                     |
| ------ | ----------------------------------------- | ------------------------------- |
| `GET`  | `/api/workflows`                          | List all workflows              |
| `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                |

### Create run request body

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

### Request body for `/start-async`

```typescript
{
  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

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

### Resume request body

```typescript
{
  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

```typescript
{
  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

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

### Clone thread request body

```typescript
{
  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

```typescript
{
  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

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

### Query request body

```typescript
{
  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](https://mastra.ai/reference/client-js/responses).

## 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](https://mastra.ai/reference/client-js/conversations).

## Logs

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

### Query parameters

```typescript
{
  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:

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

### Filtering

Workflow runs support:

```typescript
{
  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:

```typescript
{
  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()](https://mastra.ai/reference/server/create-route): Creating custom routes
- [Server Adapters](https://mastra.ai/docs/server/server-adapters): Using adapters