跳至主要內容

Server route

呼叫 server.init() 時，server adapter 會註冊以下 route。如已設定 prefix 選項，所有 route 都會加上該前綴。

Agents
Agents 的直接連結

Method路徑說明
GET/api/agents列出所有 Agent
GET/api/agents/:agentId按 ID 取得 Agent（支援 version query 參數）
POST/api/agents/:agentId/generate產生 Agent response
POST/api/agents/:agentId/stream以 stream 傳送 Agent response
POST/api/agents/:agentId/send-message向運行中或閒置的 thread 傳送使用者訊息
POST/api/agents/:agentId/queue-message將使用者訊息排入下一個 thread turn 的佇列
POST/api/agents/:agentId/signals向運行中或閒置的 thread 傳送較低層級的訊號
POST/api/agents/:agentId/threads/subscribe訂閱 thread stream
POST/api/agents/:agentId/send-tool-approval核准或拒絕 Tool call，並透過 thread subscription 恢復運行
POST/api/agents/:agentId/resume-stream使用自訂資料恢復已暫停的 Agent stream
GET/api/agents/:agentId/tools列出 Agent Tool
POST/api/agents/:agentId/tools/:toolId/execute執行 Agent Tool

取得 Agent 的 query 參數
取得 Agent 的 query 參數 的直接連結

GET /api/agents/:agentId 接受可選 query 參數，用以控制將哪個已儲存的設定版本套用為程式碼所定義 Agent 的覆寫設定：

參數類型預設值說明
status'draft' | 'published''published'要解析的已儲存版本。draft 傳回最新版本，published 傳回生效中的版本。
versionIdstring無要解析的指定 version ID。優先於 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
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
Generate response 的直接連結

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

Agent 訊息 route
Agent 訊息 route 的直接連結

使用 POST /api/agents/:agentId/send-message 向運行中的 Agent loop 傳送使用者訊息，或喚醒閒置 thread。當運行中的 run 應先完成，Mastra 才開始後續 run 時，請使用 POST /api/agents/:agentId/queue-message。

兩個 route 接受相同的 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>;
  };
}

省略 runId 時，必須提供 resourceId 及 threadId。ifIdle 只適用於以 thread 為目標的 request，不適用於以 run 為目標的 request。

傳送訊息
傳送訊息 的直接連結

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

將訊息排入佇列
將訊息排入佇列 的直接連結

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

兩個 route 都會傳回：

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

Subscription Tool 核准 route
Subscription Tool 核准 route 的直接連結

當 client 已有運行中的 thread subscription 時，請使用 POST /api/agents/:agentId/send-tool-approval。此 route 會恢復 run 並傳回 JSON 確認。恢復後的 stream chunk 會透過 POST /api/agents/:agentId/threads/subscribe 傳送。

此 route 接受以下 request body：

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

此 route 傳回：

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

Workflows
Workflows 的直接連結

Method路徑說明
GET/api/workflows列出所有 Workflow
GET/api/workflows/run-counts取得每個 Workflow 運行中及已暫停的 run 數目
GET/api/workflows/:workflowId按 ID 取得 Workflow
POST/api/workflows/:workflowId/create-run建立新的 Workflow run
POST/api/workflows/:workflowId/start-async啟動 Workflow 並等待結果
POST/api/workflows/:workflowId/stream以 stream 傳送 Workflow 執行結果
POST/api/workflows/:workflowId/resume恢復已暫停的 Workflow
POST/api/workflows/:workflowId/resume-async以非同步方式恢復
GET/api/workflows/:workflowId/runs列出 Workflow run
GET/api/workflows/:workflowId/runs/:runId取得指定 run

Run 數目 response
Run 數目 response 的直接連結

/api/workflows/run-counts endpoint 會傳回每個已註冊 Workflow 的 running 及 suspended run 數目。Record 使用 Mastra 設定中的 Workflow registry key 作為 key，而 server 可能會快取 response 數秒：

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

動態 Workflow
動態 Workflow 的直接連結

動態 Workflow 定義（beta）是以 JSON 表示、透過 workflowDefinitions storage domain 持久保存，並即時註冊至運行中 instance 的 Workflow。請參閱動態 Workflow。

Method路徑說明
GET/api/stored/workflows列出動態 Workflow 定義，可按 status 及 authorId 篩選
GET/api/stored/workflows/:dynamicWorkflowId按 ID 取得動態 Workflow 定義
POST/api/stored/workflowsUpsert 定義（以及可選 helper dependencies）並即時註冊
DELETE/api/stored/workflows/:dynamicWorkflowId刪除動態 Workflow 定義，並取消註冊即時 Workflow

在已啟用驗證的 server 上，讀取 route 需要 stored-workflows:read 權限，寫入 route 則需要 stored-workflows:write。已註冊的動態 Workflow 會透過上述一般 /api/workflows/:workflowId route 執行。

建立 run 的 request body
建立 run 的 request body 的直接連結

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

/start-async 的 request body
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
以 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;
}

恢復用的 request body
恢復用的 request body 的直接連結

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

Tools
Tools 的直接連結

Method路徑說明
GET/api/tools列出所有 Tool
GET/api/tools/:toolId按 ID 取得 Tool
POST/api/tools/:toolId/execute執行 Tool

執行 Tool 的 request body
執行 Tool 的 request body 的直接連結

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

Memory
Memory 的直接連結

Method路徑說明
GET/api/memory/threads列出 thread
GET/api/memory/threads/:threadId取得 thread
POST/api/memory/threads建立 thread
DELETE/api/memory/threads/:threadId刪除 thread
POST/api/memory/threads/:threadId/clone複製 thread
GET/api/memory/threads/:threadId/messages取得 thread 訊息
POST/api/memory/threads/:threadId/messages新增訊息

建立 thread 的 request body
建立 thread 的 request body 的直接連結

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

複製 thread 的 request body
複製 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
    };
  };
}

複製 thread 的 response
複製 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
Vectors 的直接連結

Method路徑說明
POST/api/vectors/:vectorName/upsertUpsert vector
POST/api/vectors/:vectorName/query查詢 vector
POST/api/vectors/:vectorName/delete刪除 vector

Upsert request body
Upsert request body 的直接連結

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

Query request body
Query request body 的直接連結

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

MCP
MCP 的直接連結

Method路徑說明
GET/api/mcp/servers列出 MCP server
GET/api/mcp/servers/:serverId/tools列出 server Tool
POST/api/mcp/:serverIdMCP HTTP transport
GET/api/mcp/:serverId/sseMCP SSE transport

Responses API
Responses API 的直接連結

Method路徑說明
POST/api/v1/responses透過 OpenAI 兼容的 Responses API route 建立 response
GET/api/v1/responses/:responseId擷取已儲存的 response
DELETE/api/v1/responses/:responseId刪除已儲存的 response

完整 request 及 response contract 請參閱 Responses API 參考。

Conversations API
Conversations API 的直接連結

Method路徑說明
POST/api/v1/conversations建立 conversation
GET/api/v1/conversations/:conversationId擷取 conversation
DELETE/api/v1/conversations/:conversationId刪除 conversation
GET/api/v1/conversations/:conversationId/items列出 conversation 的已儲存 item

完整 request 及 response contract 請參閱 Conversations API 參考。

Logs
Logs 的直接連結

Method路徑說明
GET/api/logs列出 log
GET/api/logs/:runId按 run ID 取得 log

Query 參數
Query 參數 的直接連結

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

Telemetry
Telemetry 的直接連結

Method路徑說明
GET/api/telemetry/traces列出 Trace
GET/api/telemetry/traces/:traceId取得 Trace
GET/api/telemetry/traces/:traceId/spans取得 Trace span

常用 query 參數
常用 query 參數 的直接連結

分頁
分頁 的直接連結

大部分清單 endpoint 支援：

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

篩選
篩選 的直接連結

Workflow run 支援：

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

錯誤 response
錯誤 response 的直接連結

所有 route 都以以下格式傳回錯誤：

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

常見 status code：

Code含義
400錯誤 request——參數無效
401未獲授權——缺少 auth 或 auth 無效
403禁止存取——權限不足
404找不到——資源不存在
500Server 內部錯誤
On this page