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

# Server 路由

调用 `server.init()` 时，服务器适配器会注册这些路由。若已配置，所有路由都会添加 `prefix` 选项指定的前缀。

## Agent

| 方法     | 路径                                           | 描述                        |
| ------ | -------------------------------------------- | ------------------------- |
| `GET`  | `/api/agents`                                | 列出所有 Agent                |
| `GET`  | `/api/agents/:agentId`                       | 按 ID 获取 Agent（支持版本查询参数）   |
| `POST` | `/api/agents/:agentId/generate`              | 生成 Agent 响应               |
| `POST` | `/api/agents/:agentId/stream`                | 流式传输 Agent 响应             |
| `POST` | `/api/agents/:agentId/send-message`          | 向活跃或空闲的线程发送用户消息           |
| `POST` | `/api/agents/:agentId/queue-message`         | 将用户消息排队到线程的下一轮            |
| `POST` | `/api/agents/:agentId/signals`               | 向活跃或空闲的线程发送底层信号           |
| `POST` | `/api/agents/:agentId/threads/subscribe`     | 订阅线程流                     |
| `POST` | `/api/agents/:agentId/send-tool-approval`    | 批准或拒绝 Tool 调用，并通过线程订阅恢复执行 |
| `POST` | `/api/agents/:agentId/resume-stream`         | 使用自定义数据恢复已暂停的 Agent 流     |
| `GET`  | `/api/agents/:agentId/tools`                 | 列出 Agent Tool             |
| `POST` | `/api/agents/:agentId/tools/:toolId/execute` | 执行 Agent Tool             |

### 获取 Agent 的查询参数

`GET /api/agents/:agentId` 接受可选查询参数，用于控制将哪个已存储的配置版本作为覆盖项应用于代码定义的 Agent：

| 参数          | 类型                       | 默认值           | 描述                                           |
| ----------- | ------------------------ | ------------- | -------------------------------------------- |
| `status`    | `'draft' \| 'published'` | `'published'` | 要解析的已存储版本。`draft` 返回最新版本，`published` 返回活跃版本。 |
| `versionId` | `string`                 | 无             | 要解析的特定版本 ID。其优先级高于 `status`。                 |

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

### 生成请求体

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

### 生成响应

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

### Agent 消息路由

使用 `POST /api/agents/:agentId/send-message` 向活跃的 Agent 循环发送用户消息，或唤醒空闲线程。若应在 Mastra 启动后续运行前完成当前运行，请使用 `POST /api/agents/:agentId/queue-message`。

两个路由均接受相同的请求体：

```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>;
  };
}
```

省略 `runId` 时，必须提供 `resourceId` 和 `threadId`。`ifIdle` 仅适用于以线程为目标的请求，不适用于以运行为目标的请求。

#### 发送消息

```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"
  }'
```

#### 将消息加入队列

```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"
  }'
```

两个路由均返回：

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

### 订阅 Tool 批准路由

当客户端已有活跃的线程订阅时，使用 `POST /api/agents/:agentId/send-tool-approval`。该路由会恢复运行并返回 JSON 确认信息。恢复后的流分块会通过 `POST /api/agents/:agentId/threads/subscribe` 传送。

该路由接受以下请求体：

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

该路由返回：

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

## Workflow

| 方法     | 路径                                        | 描述                        |
| ------ | ----------------------------------------- | ------------------------- |
| `GET`  | `/api/workflows`                          | 列出所有 Workflow             |
| `GET`  | `/api/workflows/run-counts`               | 获取每个 Workflow 的运行中和暂停运行数量 |
| `GET`  | `/api/workflows/:workflowId`              | 按 ID 获取 Workflow          |
| `POST` | `/api/workflows/:workflowId/create-run`   | 创建新的 Workflow 运行          |
| `POST` | `/api/workflows/:workflowId/start-async`  | 启动 Workflow 并等待结果         |
| `POST` | `/api/workflows/:workflowId/stream`       | 流式传输 Workflow 执行过程        |
| `POST` | `/api/workflows/:workflowId/resume`       | 恢复已暂停的 Workflow           |
| `POST` | `/api/workflows/:workflowId/resume-async` | 异步恢复                      |
| `GET`  | `/api/workflows/:workflowId/runs`         | 列出 Workflow 运行            |
| `GET`  | `/api/workflows/:workflowId/runs/:runId`  | 获取特定运行                    |

### 运行计数响应

`/api/workflows/run-counts` 端点返回每个已注册 Workflow 的 `running` 和 [`suspended`](https://mastra.zisheng.pro/docs/workflows/suspend-and-resume) 运行数量。该记录以 Mastra 配置中的 Workflow 注册表键为键，服务器可能会将响应缓存数秒：

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

### 动态 Workflow

动态 Workflow 定义（beta）是以 JSON 表示的 Workflow，通过 `workflowDefinitions` 存储域持久化，并在运行中的实例上实时注册。请参阅[动态 Workflow](https://mastra.zisheng.pro/docs/workflows/dynamic-workflows)。

| 方法       | 路径                                         | 描述                                           |
| -------- | ------------------------------------------ | -------------------------------------------- |
| `GET`    | `/api/stored/workflows`                    | 列出动态 Workflow 定义，可按 `status` 和 `authorId` 筛选 |
| `GET`    | `/api/stored/workflows/:dynamicWorkflowId` | 按 ID 获取动态 Workflow 定义                        |
| `POST`   | `/api/stored/workflows`                    | 插入或更新定义（以及可选的辅助 `dependencies`），并实时注册它       |
| `DELETE` | `/api/stored/workflows/:dynamicWorkflowId` | 删除动态 Workflow 定义并注销实时 Workflow               |

在已认证的服务器上，读取路由需要 `stored-workflows:read` 权限，写入路由需要 `stored-workflows:write` 权限。已注册的动态 Workflow 通过上方常规的 `/api/workflows/:workflowId` 路由执行。

### 创建运行请求体

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

### `/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>;
  };
}
```

### 流式传输 Workflow 的请求体

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

### 恢复请求体

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

## Tool

| 方法     | 路径                           | 描述           |
| ------ | ---------------------------- | ------------ |
| `GET`  | `/api/tools`                 | 列出所有 Tool    |
| `GET`  | `/api/tools/:toolId`         | 按 ID 获取 Tool |
| `POST` | `/api/tools/:toolId/execute` | 执行 Tool      |

### 执行 Tool 请求体

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

## Memory

| 方法       | 路径                                       | 描述     |
| -------- | ---------------------------------------- | ------ |
| `GET`    | `/api/memory/threads`                    | 列出线程   |
| `GET`    | `/api/memory/threads/:threadId`          | 获取线程   |
| `POST`   | `/api/memory/threads`                    | 创建线程   |
| `DELETE` | `/api/memory/threads/:threadId`          | 删除线程   |
| `POST`   | `/api/memory/threads/:threadId/clone`    | 克隆线程   |
| `GET`    | `/api/memory/threads/:threadId/messages` | 获取线程消息 |
| `POST`   | `/api/memory/threads/:threadId/messages` | 添加消息   |

### 创建线程请求体

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

### 克隆线程请求体

```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
    };
  };
}
```

### 克隆线程响应

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

## Vector

| 方法     | 路径                                | 描述      |
| ------ | --------------------------------- | ------- |
| `POST` | `/api/vectors/:vectorName/upsert` | 插入或更新向量 |
| `POST` | `/api/vectors/:vectorName/query`  | 查询向量    |
| `POST` | `/api/vectors/:vectorName/delete` | 删除向量    |

### 插入或更新请求体

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

### 查询请求体

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

## MCP

| 方法     | 路径                                 | 描述          |
| ------ | ---------------------------------- | ----------- |
| `GET`  | `/api/mcp/servers`                 | 列出 MCP 服务器  |
| `GET`  | `/api/mcp/servers/:serverId/tools` | 列出服务器 Tool  |
| `POST` | `/api/mcp/:serverId`               | MCP HTTP 传输 |
| `GET`  | `/api/mcp/:serverId/sse`           | MCP SSE 传输  |

## Responses API

| 方法       | 路径                              | 描述                                 |
| -------- | ------------------------------- | ---------------------------------- |
| `POST`   | `/api/v1/responses`             | 通过兼容 OpenAI 的 Responses API 路由创建响应 |
| `GET`    | `/api/v1/responses/:responseId` | 检索已存储的响应                           |
| `DELETE` | `/api/v1/responses/:responseId` | 删除已存储的响应                           |

有关完整的请求和响应契约，请参阅 [Responses API 参考](https://mastra.zisheng.pro/reference/client-js/responses)。

## Conversations API

| 方法       | 路径                                            | 描述         |
| -------- | --------------------------------------------- | ---------- |
| `POST`   | `/api/v1/conversations`                       | 创建会话       |
| `GET`    | `/api/v1/conversations/:conversationId`       | 检索会话       |
| `DELETE` | `/api/v1/conversations/:conversationId`       | 删除会话       |
| `GET`    | `/api/v1/conversations/:conversationId/items` | 列出会话的已存储项目 |

有关完整的请求和响应契约，请参阅 [Conversations API 参考](https://mastra.zisheng.pro/reference/client-js/conversations)。

## 日志

| 方法    | 路径                 | 描述          |
| ----- | ------------------ | ----------- |
| `GET` | `/api/logs`        | 列出日志        |
| `GET` | `/api/logs/:runId` | 按运行 ID 获取日志 |

### 查询参数

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

## Telemetry

| 方法    | 路径                                     | 描述            |
| ----- | -------------------------------------- | ------------- |
| `GET` | `/api/telemetry/traces`                | 列出 Trace      |
| `GET` | `/api/telemetry/traces/:traceId`       | 获取 Trace      |
| `GET` | `/api/telemetry/traces/:traceId/spans` | 获取 Trace span |

## 常用查询参数

### 分页

大多数列表端点支持：

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

### 筛选

Workflow 运行支持：

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

## 错误响应

所有路由均以此格式返回错误：

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

常见状态码：

| 状态码 | 含义              |
| --- | --------------- |
| 400 | 错误请求 - 参数无效     |
| 401 | 未授权 - 缺少认证或认证无效 |
| 403 | 禁止访问 - 权限不足     |
| 404 | 未找到 - 资源不存在     |
| 500 | 内部服务器错误         |

## 相关内容

- [createRoute()](https://mastra.zisheng.pro/reference/server/create-route)：创建自定义路由
- [服务器适配器](https://mastra.zisheng.pro/docs/server/server-adapters)：使用适配器