# 开始使用 Product API

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

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

## 开始前

请准备以下内容：

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

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

## 1. 设置请求变量

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

```bash
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`，因为调用前还没有选定工作区。下面的请求只读取当前账号可见的工作区：

```bash
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、名称、状态和数量会随账号变化。

```json
{
  "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。 |

## 下一步

- [检查当前工作区身份并列出成员](workspaces-members.md)
- [运行、查询和取消工作流](workflows-workitems-lineage/run-query-cancel.md)
- [浏览数据库与表](data-files-connectors/databases-tables.md)