跳到主要内容
非官方简体中文翻译，内容版权归 Mastra 所有，遵循 Apache-2.0 许可。

API 参考

Members API
Members API的直接链接

以下端点的根 URL 为：/v1/org/members

方法端点描述
GET/列出成员
POST/invitations发送邀请
GET/invitations列出邀请
DELETE/invitations/:id撤销邀请
PATCH/:id更新成员角色
DELETE/:id移除成员

API tokens
API tokens的直接链接

以下端点的根 URL 为：/v1/auth/tokens

方法端点描述
POST/创建 API token
GET/列出 API tokens
DELETE/:id删除 API token

Studio API
Studio API的直接链接

以下端点的根 URL 为：/v1/studio

方法端点描述
GET/projects列出 studio 项目
POST/projects创建项目
GET/projects/:id获取项目详情和部署
DELETE/projects/:id删除项目
POST/deploys创建部署
POST/deploys/:id/upload-complete确认 artifact 上传
GET/deploys/:id获取部署状态
GET/deploys/:id/logs获取部署日志
GET/deploys/:id/logs/stream流式传输部署日志（SSE）

Server API
Server API的直接链接

以下端点的根 URL 为：/v1/server

方法端点描述
GET/projects列出 server 项目
POST/projects创建项目
GET/projects/:id获取项目详情
DELETE/projects/:id删除项目
PUT/projects/:id/env设置环境变量
GET/projects/:id/env获取环境变量
POST/projects/:id/env/restart环境变更后重启
GET/projects/:id/domains列出域名
POST/projects/:id/domains添加自定义域名
GET/projects/:id/runtime-logs获取运行时日志
POST/projects/:id/redeploy触发重新部署
POST/projects/:id/always-on启用 always-on
DELETE/projects/:id/always-on禁用 always-on
POST/deploys创建部署
POST/deploys/:id/upload-complete确认 artifact 上传
GET/deploys/:id获取部署状态
GET/deploys/:id/logs获取部署日志
POST/deploys/:id/cancel取消排队中或进行中的部署
DELETE/deploys/:id停止正在运行的部署

Gateway API
Gateway API的直接链接

以下端点的根 URL 为：/v1/gateway

方法端点描述
GET/projects列出 gateway 项目
GET/projects/:id获取项目详情
PATCH/projects/:id更新项目设置
DELETE/projects/:id删除项目
POST/projects/provision配置新的 gateway 项目
GET/projects/:id/keys列出 API keys
POST/projects/:id/keys创建 API key
DELETE/projects/:id/keys/:keyId撤销 API key
GET/projects/:id/keys/:keyId/bindings列出 key 级 provider bindings
POST/projects/:id/keys/:keyId/bindings添加 key 级 provider binding（BYOK）
DELETE/projects/:id/keys/:keyId/bindings/:provider移除 key 级 binding
GET/projects/:id/bindings列出项目级 provider bindings
POST/projects/:id/bindings添加项目级 provider binding（BYOK）
DELETE/projects/:id/bindings/:provider移除项目级 binding
GET/projects/:id/usage/has-activity检查项目是否有任何请求
GET/projects/:id/usage/activity获取聚合使用活动
GET/projects/:id/usage/memory-activity获取时间范围内的 memory-token 总量
GET/projects/:id/usage/logs获取请求日志
GET/projects/:id/usage/logs/facets获取日志过滤 facet
GET/projects/:id/usage/logs/:requestId获取特定请求详情
GET/projects/:id/memory/threads列出 threads（dashboard）
POST/projects/:id/memory/threads创建 thread（dashboard）
GET/projects/:id/memory/threads/:threadId获取 thread（dashboard）
PATCH/projects/:id/memory/threads/:threadId更新 thread（dashboard）
DELETE/projects/:id/memory/threads/:threadId删除 thread（dashboard）
POST/projects/:id/memory/threads/:threadId/clone克隆 thread（dashboard）
GET/projects/:id/memory/threads/:threadId/messages列出消息（dashboard）
POST/projects/:id/memory/threads/:threadId/messages保存消息（dashboard）
DELETE/projects/:id/memory/threads/:threadId/messages删除消息（dashboard）
GET/projects/:id/memory/threads/:threadId/observations/history观察历史（dashboard）
GET/models列出可用模型

Feedback API
Feedback API的直接链接

Feedback API 列出并分析导出到 Mastra Platform Observability 的 feedback。由于该 API 没有版本号，不保证向后兼容。速率限制、保留期和从摄取到查询的新鲜度不属于已发布的契约。

这些端点与 Mastra 运行时 feedback 路由共享查询参数、请求体和响应类型。完整契约（包括列表查询参数和 FeedbackFilter）参见 feedback 参考。

使用你的环境数据驻留区域的根 URL：

区域根 URL
美国https://observability.mastra.ai/api/observability
欧盟https://observability.eu.mastra.ai/api/observability

遥测数据保留在其驻留区域内。查询其他区域不会返回该环境的任何记录。环境到区域的映射参见可观测性同地部署。

认证和项目作用域
认证和项目作用域的直接链接

每个请求都需要 platform access token。在 Mastra Platform 中创建一个，或使用 Platform 设置期间写入 .env 的 token。

包含 X-Mastra-Project-Id 可将结果限制在一个项目内。如果省略它，查询将覆盖 token 所属组织可用的所有项目中的 feedback。

curl -sS "https://observability.mastra.ai/api/observability/feedback?page=0&perPage=20&feedbackType=rating" \
  -H "Authorization: Bearer $MASTRA_PLATFORM_ACCESS_TOKEN" \
  -H "X-Mastra-Project-Id: $MASTRA_PROJECT_ID" | jq

使用组织作用域的 Platform access token。诸如 mk_* key 之类的 Gateway 推理密钥不被接受。即使你提供了项目 ID，查询仍会限制在 token 所属组织内。

端点
端点的直接链接

方法端点描述
GET/feedback列出 feedback 记录
POST/feedback/aggregate返回单个聚合值
POST/feedback/breakdown按维度对 feedback 分组
POST/feedback/timeseries按时间间隔对 feedback 分桶
POST/feedback/percentiles返回百分位数序列

列表端点将每个 FeedbackFilter 字段作为同名查询参数接收，例如 traceId、spanId、feedbackType、feedbackSource、environment、entityName、experimentId 或 tags。为多个值重复一个参数，例如 feedbackType=rating&feedbackType=thumbs。

curl -sS "https://observability.mastra.ai/api/observability/feedback?traceId=trace-123&environment=production" \
  -H "Authorization: Bearer $MASTRA_PLATFORM_ACCESS_TOKEN" \
  -H "X-Mastra-Project-Id: $MASTRA_PROJECT_ID" | jq
参数描述
page, perPage从零开始的页码和页大小（1 到 100）。默认 0 和 10。
field, direction按 timestamp 以 ASC 或 DESC 顺序排序。默认 DESC。
mode=delta从分页切换为增量 delta 轮询。
after来自上一个 delta 响应的 delta 游标。仅 delta 模式。
limit每次 delta 轮询的最大更新数（1 到 100）。仅 delta 模式。

响应包含 feedback 数组以及分页或 delta metadata。完整参数契约（包括 timestamp 等 JSON 编码的对象过滤器）参见 feedback 参考中的列表查询参数。

分析端点接受与 feedback 参考相同的 JSON 请求格式并返回相同类型。分析仅对数值型 feedback 值操作。

curl -sS "https://observability.mastra.ai/api/observability/feedback/aggregate" \
  -X POST \
  -H "Authorization: Bearer $MASTRA_PLATFORM_ACCESS_TOKEN" \
  -H "X-Mastra-Project-Id: $MASTRA_PROJECT_ID" \
  -H "Content-Type: application/json" \
  --data '{"feedbackType":"rating","feedbackSource":"user","aggregation":"avg"}' | jq

对于无效凭据，API 返回 401；对于组织授权失败，返回 403；对于格式错误的查询参数或 JSON 体，返回 400。

托管可观测性不提供 feedback 创建路由。请按照将 feedback 导出到 Mastra Platform中的说明从应用导出 feedback。

Metrics API
Metrics API的直接链接

Metrics API 查询导出到 Mastra Platform Observability 的 metrics。由于该 API 没有版本号，不保证向后兼容。速率限制、保留期和从摄取到查询的新鲜度不属于已发布的契约。

这些端点与 Mastra 运行时 metric 路由共享查询参数、请求体和响应类型。完整契约（包括共享过滤器、分析方法和 metric 发现）参见 metric 查询参考。

使用你的环境数据驻留区域的根 URL：

区域根 URL
美国https://observability.mastra.ai/api/observability
欧盟https://observability.eu.mastra.ai/api/observability

遥测数据保留在其驻留区域内。查询其他区域不会返回该环境的任何记录。环境到区域的映射参见可观测性同地部署。

认证和项目作用域
认证和项目作用域的直接链接

每个请求都需要 platform access token。在 Mastra Platform 中创建一个，或使用 Platform 设置期间写入 .env 的 token。

包含 X-Mastra-Project-Id 可将结果限制在一个项目内。如果省略它，查询将覆盖 token 所属组织可用的所有项目中的 metrics。

curl -sS "https://observability.mastra.ai/api/observability/discovery/metric-names?prefix=mastra_model_" \
  -H "Authorization: Bearer $MASTRA_PLATFORM_ACCESS_TOKEN" \
  -H "X-Mastra-Project-Id: $MASTRA_PROJECT_ID" | jq

使用组织作用域的 Platform access token。诸如 mk_* key 之类的 Gateway 推理密钥不被接受。即使你提供了项目 ID，查询仍会限制在 token 所属组织内。

端点
端点的直接链接

方法端点描述
GET/metrics列出原始 metric 记录
POST/metrics/aggregate返回单个聚合值
POST/metrics/breakdown按维度对 metrics 分组
POST/metrics/timeseries按时间间隔对 metrics 分桶
POST/metrics/percentiles返回某个 metric 的百分位数序列
GET/discovery/metric-names列出 metric 名称
GET/discovery/metric-label-keys列出某个 metric 的 label keys
GET/discovery/metric-label-values列出某个 metric label key 的值

列表和发现端点将其参数作为查询参数接收。每个端点接受的参数参见 metric 查询参考中的 listMetrics(args)和 metric 发现。

分析端点接受与 metric 查询参考相同的 JSON 请求体并返回相同类型，包括 name、aggregation、filters、groupBy、interval、percentiles、comparePeriod、limit、orderDirection 和 distinctColumn。

curl -sS "https://observability.mastra.ai/api/observability/metrics/aggregate" \
  -X POST \
  -H "Authorization: Bearer $MASTRA_PLATFORM_ACCESS_TOKEN" \
  -H "X-Mastra-Project-Id: $MASTRA_PROJECT_ID" \
  -H "Content-Type: application/json" \
  --data '{"name":["mastra_model_total_input_tokens","mastra_model_total_output_tokens"],"aggregation":"sum","filters":{"timestamp":{"start":"2026-09-13T00:00:00Z","end":"2026-10-13T00:00:00Z"}},"comparePeriod":"previous_period"}' | jq

filters.timestamp 是可选的。如果省略 start 和 end，查询将覆盖所有保留的数据。comparePeriod 需要同时提供 start 和 end。缺少它们时，上一周期的字段为 null。

对于无效凭据，API 返回 401；对于组织授权失败，返回 403；对于格式错误的查询参数或 JSON 体，返回 400。

MastraClient
mastraclient的直接链接

@mastra/client-js 中的 MastraClient 暴露分析和发现方法。将 baseUrl 设置为区域的 host，不带 /api/observability 路径：

import { MastraClient } from '@mastra/client-js'

const mastraClient = new MastraClient({
  baseUrl: 'https://observability.mastra.ai',
  headers: {
    Authorization: `Bearer ${process.env.MASTRA_PLATFORM_ACCESS_TOKEN}`,
    'X-Mastra-Project-Id': process.env.MASTRA_PROJECT_ID!,
  },
})

const result = await mastraClient.getMetricAggregate({
  name: ['mastra_model_total_input_tokens', 'mastra_model_total_output_tokens'],
  aggregation: 'sum',
})

CLI
CLI的直接链接

mastra api metric命令默认指向美国端点。传入 --url 以查询欧盟区域：

mastra api --url https://observability.eu.mastra.ai metric aggregate '<json>'

Gateway 代理端点
Gateway 代理端点的直接链接

更多详情请访问 Gateway 文档。

On this page