开始使用 Product API¶

通过 Product API 访问 MatrixOne Intelligence 中的工作区、数据、工作流和智能体等产品资源。完成本页操作后，你将使用个人访问令牌列出当前账号可见的工作区，并保存一个工作区 ID 供后续请求使用。

完成第一次调用需要三步：准备 Product API 地址和个人访问令牌、发送工作区列表请求、从响应中取得工作区 ID。

开始前¶

请准备以下内容：

Product API Base URL：从当前环境提供的开发者接入信息中获取。本文假设该地址已经包含 /newmoi，后续只追加 /workspaces 等相对路径。
个人访问令牌（PAT）：用于设置 X-API-Key Header。创建和管理个人访问令牌，请参阅访问凭据。

Product API 和 Genesis 模型 API 使用不同的服务地址与认证 Header。不要把 Genesis Base URL、Genesis API Key 或 Authorization: Bearer 示例用于本页请求。

1. 设置请求变量¶

在终端中设置 Product API Base URL 和个人访问令牌。不要把令牌写入源码、镜像或日志。

export PRODUCT_API_BASE_URL='<Product API Base URL ending in /newmoi>'
export PRODUCT_API_KEY='<your-personal-access-token>'

保持 Base URL 中的版本和产品前缀不变。如果接入信息已经以 /newmoi 结尾，不要再次追加该前缀。

2. 列出可见工作区¶

工作区发现接口不需要 X-Workspace-ID，因为调用前还没有选定工作区。下面的请求只读取当前账号可见的工作区：

curl "$PRODUCT_API_BASE_URL/workspaces" \
  -H "X-API-Key: $PRODUCT_API_KEY" \
  -H "Accept: application/json"

不要在同一请求中同时发送个人访问令牌、Authorization Header 或浏览器 Cookie。Product API 会将多种凭据同时出现视为认证冲突。

3. 检查响应¶

成功响应的 data.workspaces 包含当前账号可以看到的工作区。实际 ID、名称、状态和数量会随账号变化。

{
  "code": "OK",
  "msg": "OK",
  "data": {
    "workspaces": [
      {
        "id": "<WORKSPACE_ID>",
        "name": "<WORKSPACE_NAME>",
        "status": "<STATUS>",
        "owner_id": "<OWNER_ID>",
        "created_at": "<CREATED_AT>",
        "access_status": "<ACCESS_STATUS>",
        "invitation_id": ""
      }
    ],
    "total": 1
  }
}

字段	类型	返回条件	说明
`code`	string	始终返回	业务结果代码。`OK` 表示请求成功。
`data.workspaces`	array	请求成功时返回	当前账号可见的工作区列表。没有可见工作区时返回空数组。
`data.workspaces[].id`	string	每个工作区返回	工作区 ID。访问工作区内资源时，通过 `X-Workspace-ID` 继续传递该值。
`data.workspaces[].name`	string	每个工作区返回	工作区名称。名称用于识别，后续请求仍应使用工作区 ID。
`data.workspaces[].status`	string	每个工作区返回	工作区当前状态。只使用当前响应返回的值判断状态。
`data.workspaces[].access_status`	string	每个工作区返回	当前账号与工作区的访问关系。待接受邀请的工作区还会返回 `invitation_id`。
`data.total`	integer	请求成功时返回	本次响应中的工作区数量。

选择目标工作区后，保存 data.workspaces[].id。工作流、数据目录、成员和其他工作区资源请求都需要在 X-Workspace-ID 中使用该值。

常见问题¶

现象	先检查	下一步
返回 `401`	`X-API-Key`、令牌状态以及请求中是否混入其他凭据	只保留有效的个人访问令牌，并确认 Header 名称为 `X-API-Key`。
返回 `403`	当前账号是否已同步到产品、是否具有产品访问权限	先登录当前环境确认账号可访问产品；仍失败时保留请求时间和脱敏错误代码。
返回 `404`	Base URL 是否已经包含正确的产品前缀	从当前环境重新复制 Product API Base URL，不使用网页管理地址或 Genesis 地址。
`workspaces` 为空	当前账号的工作区和邀请状态	在产品中确认账号已创建、加入或接受目标工作区邀请。不要根据工作区名称自行构造 ID。

下一步¶

最后更新于 2026 年 8 月 14 日