> ## Documentation Index
> Fetch the complete documentation index at: https://docs.meoo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 用户与项目 API

这组接口用于识别已授权用户、创建 Meoo 项目，以及查找用户已有的项目。

基础地址：`https://meoo.com/open/v1`

## 获取用户信息

```text theme={null}
GET /user
```

返回当前凭证对应的用户信息。第三方应用可以使用 `open_id` 在自己的系统中建立用户绑定关系。

所需权限：`user.read`

### 请求示例

```text theme={null}
curl --request GET \
  --url "https://meoo.com/open/v1/user" \
  --header "Authorization: Bearer ${ACCESS_TOKEN}"
```

### 响应字段

| 字段        | 类型             | 说明                   |
| :-------- | :------------- | :------------------- |
| `open_id` | string         | 用户在当前 OAuth 应用下的唯一标识 |
| `name`    | string         | 用户昵称                 |
| `avatar`  | string \| null | 用户头像地址；未设置时为 `null`  |

### 响应示例

```text theme={null}
{
  "open_id": "mou_7tF8pQxExample",
  "name": "小明",
  "avatar": "https://example.com/avatar.png"
}
```

`open_id` 仅在当前 OAuth 应用内稳定。同一位用户授权不同应用时会得到不同的 `open_id`，请勿将其与 Meoo 内部用户 ID 或其他应用的标识关联。

### 常见错误

| HTTP 状态 | 说明                        |
| :------ | :------------------------ |
| `401`   | Access Token 或 API Key 无效 |
| `403`   | 缺少 `user.read` 权限         |
| `404`   | 用户当前不可用                   |

## 查询项目列表

```text theme={null}
GET /projects
```

分页返回当前用户拥有的项目。可以按名称和创建时间筛选。

所需权限：`project.read`

### Query 参数

**参数说明**

* `page_size`（integer，可选）：每页数量，默认 20，最大 100
* `page_token`（string，可选）：上一页响应返回的分页令牌
* `query`（string，可选）：按项目名称进行包含匹配，最长 100 个字符
* `created_from`（integer，可选）：创建时间起点，包含该时刻，Unix 毫秒时间戳
* `created_to`（integer，可选）：创建时间终点，不包含该时刻，Unix 毫秒时间戳

`created_from` 和 `created_to` 可以单独使用。两者同时传递时，`created_to` 必须大于 `created_from`。

### 请求示例

查询 2026 年 8 月创建且名称包含“活动”的项目：

```text theme={null}
curl --request GET \
  --url "https://meoo.com/open/v1/projects?query=%E6%B4%BB%E5%8A%A8&created_from=1785513600000&created_to=1788192000000&page_size=20" \
  --header "Authorization: Bearer ${ACCESS_TOKEN}"
```

### 响应字段

| 字段         | 类型    | 说明   |
| :--------- | :---- | :--- |
| `projects` | array | 项目列表 |

\| `projects[ ].url_id` | string | 项目的公开标识，用于后续项目接口 |

\| `projects[ ].name` | string | 项目名称 |

\| `projects[ ].type` | string | 项目类型，见下表 |

\| `projects[ ].created_at` | integer | 项目创建时间，Unix 毫秒时间戳 |

\| `next_page_token` | string | 下一页令牌；没有下一页时不返回 |

项目类型：

| 值             | 说明          |
| :------------ | :---------- |
| `web`         | Web 应用      |
| `app`         | App 应用      |
| `miniprogram` | 小程序         |
| `skill`       | 技能          |
| `unknown`     | 客户端尚未识别的新类型 |

### 响应示例

```text theme={null}
{
  "projects": [
    {
      "url_id": "event-signup-demo",
      "name": "活动报名助手",
      "type": "web",
      "created_at": 1786410000000
    }
  ],
  "next_page_token": "******"
}
```

### 常见错误

| HTTP 状态 | 说明                        |
| :------ | :------------------------ |
| `400`   | 时间范围、分页令牌或查询参数不正确         |
| `401`   | Access Token 或 API Key 无效 |
| `403`   | 缺少 `project.read` 权限      |
| `429`   | 调用频率超过限制                  |

## 创建项目

```text theme={null}
POST /projects
```

为当前用户创建一个新的 Meoo 项目。创建成功后，可以使用返回的 `url_id` 调用适用于该项目类型的项目级接口；创建成功不等于该类型的所有构建、发布能力都已通过 OpenAPI 开放。

所需权限：`project.write`

### 请求头

```text theme={null}
Content-Type: application/json
```

### 请求字段

**字段说明**

* `name`（string，可选）：项目名称，1～100 个字符，不能全部为空白
* `type`（string，可选）：`web`、`app` 或 `miniprogram`；默认 `web`

### 项目类型能力边界

| 类型            | 创建  | OpenAPI 发布边界                             |
| :------------ | :-- | :--------------------------------------- |
| `web`         | 支持  | 支持默认 Web/静态站点发布                          |
| `app`         | 支持  | 暂不支持生成或发布 APK、IPA 等原生安装包                 |
| `miniprogram` | 支持  | 暂不支持提交到微信、抖音等小程序平台                       |
| `skill`       | 不支持 | 仅可能在项目列表中读取已有项目；不能通过 `POST /projects` 创建 |

OpenAPI 当前也没有修改既有项目类型的接口。Agent、云服务等项目级接口仍分别受 Scope、账号版本、项目状态和具体资源能力限制。发布边界详见[发布 API](https://app.mintlify.com/alibaba-b47c397f/alibaba-b47c397f/~/b31b1b0b-7d62-41df-a2f9-3643354ac937)。

### 请求示例

```text theme={null}
curl --request POST \
  --url "https://meoo.com/open/v1/projects" \
  --header "Authorization: Bearer ${ACCESS_TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "活动报名助手",
    "type": "web"
  }'
```

### 响应示例

```text theme={null}
{
  "url_id": "event-signup-demo",
  "name": "活动报名助手",
  "type": "web",
  "created_at": 1786410000000
}
```

### 常见错误

| HTTP 状态 | 说明                                |
| :------ | :-------------------------------- |
| `400`   | 项目名称或类型不符合要求                      |
| `401`   | Access Token 或 API Key 无效         |
| `403`   | 缺少 `project.write` 权限，或当前账号不能创建项目 |
| `429`   | 创建频率超过限制                          |

## 查询和设置项目去水印

```text theme={null}
GET /projects/{project_id}/watermark-removal
PUT /projects/{project_id}/watermark-removal
```

GET 查询当前项目的去水印状态，需要 `project.read`。PUT 幂等设置去水印状态，需要 `project.write`。

调用方必须是项目 Owner，且凭证绑定的租户必须与项目一致。`project_id` 使用项目的公开 `url_id`，不能传数据库主键。开启去水印还要求当前套餐具备 `watermark_removal` 权益；关闭去水印不要求该权益。

### 查询示例

```text theme={null}
curl --request GET \
  --url "https://meoo.com/open/v1/projects/${PROJECT_ID}/watermark-removal" \
  --header "Authorization: Bearer ${ACCESS_TOKEN}"
```

响应：

```text theme={null}
{
  "enabled": false,
  "editable": true
}
```

| 字段         | 类型      | 说明                                      |
| :--------- | :------ | :-------------------------------------- |
| `enabled`  | boolean | `true` 表示项目页面不展示 Meoo 水印                |
| `editable` | boolean | 当前项目状态是否允许修改；冻结、封禁、审核中或内部水印冻结时为 `false` |

### 设置示例

```text theme={null}
curl --request PUT \
  --url "https://meoo.com/open/v1/projects/${PROJECT_ID}/watermark-removal" \
  --header "Authorization: Bearer ${ACCESS_TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{"enabled":true}'
```

请求体只接受一个布尔字段 `enabled`。重复提交相同目标状态仍返回成功，不重复消耗权益或产生额外状态变化。调用方可以在网络超时后安全重试同一个 PUT 请求。

关闭去水印：

```text theme={null}
curl --request PUT \
  --url "https://meoo.com/open/v1/projects/${PROJECT_ID}/watermark-removal" \
  --header "Authorization: Bearer ${ACCESS_TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{"enabled":false}'
```

### 常见错误

| HTTP 状态 / code                | 说明                                             |
| :---------------------------- | :--------------------------------------------- |
| `400 invalid_request`         | `project_id`、Content-Type 或请求体不合法              |
| `401 invalid_token`           | Access Token 或 API Key 无效                      |
| `403 insufficient_scope`      | GET 缺少 `project.read`，或 PUT 缺少 `project.write` |
| `403 entitlement_required`    | 开启去水印时，当前套餐没有 `watermark_removal` 权益           |
| `404 not_found`               | 项目不存在、不是当前用户拥有的项目，或租户不一致                       |
| `409 project_not_operational` | 项目冻结、封禁、审核中，或内部去水印状态被冻结                        |
| `429`                         | 调用频率超过限制                                       |

## 创建项目级 API Key

```text theme={null}
POST /projects/{project_id}/tokens
```

为当前用户拥有的指定项目创建项目级 API Key。完整 Token 只在本次响应中返回一次。

所需权限：`project.token.write`

本接口只能使用 OAuth Access Token 调用。`project.token.write` 是由开放平台管理员配置给应用的专用 Scope，不能由用户在 Web 端自行申请；普通用户 API Key 和项目级 API Key（包括 `*`）均不能调用本接口。

### Path 参数

**参数说明**

* `project_id`（string，必填）：用户拥有的项目 `url_id`

### 请求字段

**字段说明**

* `name`（string，必填）：Key 名称，1～100 个字符
* `description`（string，可选）：备注，最长 200 个字符
* `expires_in_days`（integer，可选）：有效天数，1～3650
* `scopes`（string\[ ]，必填）：项目型权限列表；至少一项，最多 100 项

`scopes` 支持 `project.read`、Agent、Cloud、Source、Release 等项目型权限，以及：

* `alias.read` / `alias.write`：查询与管理绑定项目的官方子域名前缀，详见[自定义子域名](https://alidocs.dingtalk.com/i/nodes/ZX6GRezwJlzeYoPLF0orLZn3WdqbropQ)。
* `cli.compat`：允许 Meoo CLI 在绑定项目内执行 CLI 兼容操作。
* `*`：当前及未来所有允许配置给项目 AK 的权限。若同时传入其他值，最终按 `*` 保存。

`*` 不包含 `project.token.write` 等不可配置给 API Key 的权限，也不会允许 Key 访问其他项目、项目集合或项目创建接口。

### 请求示例

为项目创建可供 CLI 使用的 Key：

```text theme={null}
curl --request POST \
  --url "https://meoo.com/open/v1/projects/${PROJECT_ID}/tokens" \
  --header "Authorization: Bearer ${OAUTH_ACCESS_TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "project-ci",
    "description": "项目 CI/CD 和 Meoo CLI",
    "expires_in_days": 90,
    "scopes": ["project.read", "cli.compat"]
  }'
```

如需授予该项目 AK 可配置的全部权限，可将请求中的 `scopes` 设置为 `["*"]`。

### 响应示例

```text theme={null}
{
  "token": "******",
  "token_type": "Bearer",
  "project_id": "event-signup-demo",
  "scope": "project.read cli.compat",
  "expires_at": 1794182400000,
  "created_at": 1786406400000
}
```

| 字段           | 类型              | 说明                  |
| :----------- | :-------------- | :------------------ |
| `token`      | string          | 完整项目 API Key，仅返回一次  |
| `token_type` | string          | 固定为 `Bearer`        |
| `project_id` | string          | Key 绑定的项目 `url_id`  |
| `scope`      | string          | 空格分隔的实际 Scope，或 `*` |
| `expires_at` | integer \| null | 过期时间，Unix 毫秒时间戳     |
| `created_at` | integer         | 创建时间，Unix 毫秒时间戳     |

### 常见错误

| HTTP 状态 | 说明                                  |
| :------ | :---------------------------------- |
| `400`   | 请求字段或 `scopes` 不合法                  |
| `401`   | OAuth Access Token 无效或已过期           |
| `403`   | 缺少 `project.token.write`，或用户无权访问该项目 |
| `404`   | 项目不存在                               |
| `429`   | 创建频率或当前租户 API Key 数量超过限制            |

创建后应把 Key 作为 Bearer Token 使用。服务端会在每次请求中同时校验绑定项目和 Scope；Scope 不会绕过项目边界。

## 自定义子域名

项目 Alias 的查询、可用性检查、设置与重置接口，以及权限、参数和示例，详见[自定义子域名](https://app.mintlify.com/alibaba-b47c397f/alibaba-b47c397f/~/a43ffa55-44ea-44e4-b775-eecae4562065)。

## 删除项目

```text theme={null}
DELETE /projects/{project_id}
```

所需权限：`project.write`。无需请求体。

`project_id` 是公开的 `url_id`，不是数据库主键。调用方还必须具有与 Web 相同的项目删除权限（由项目、团队角色共同判定的 Owner 或 Admin）；普通协作者不能删除。项目必须属于凭证绑定的租户，Scope 不会绕过资源权限。团队集成使用具有该 Scope 的成员委托 Bearer Token，不直接使用团队 AK/SK HMAC 调用本接口。

### 删除语义与影响

* 复用 Web 的项目软删除流程，将项目标记为 `deleted`；不是永久擦除全部数据。
* 冻结、封禁、解禁审核中的项目也允许具有删除权限的用户删除。
* 清理自定义域名，并尝试级联软删除关联的社区展示及参赛记录；云服务实例释放、计量同步异步执行。返回成功只表示项目软删除完成，不保证所有关联资源已释放。
* 不承诺立即销毁沙箱或清空工程文件、存储数据，也不应以本接口作为敏感数据彻底擦除的凭据。
* 重复删除、项目不存在或无删除权限均返回 `404 not_found`。重复请求不会重复执行已删除项目的清理流程。调用方可在网络超时后使用相同凭证和项目 ID 重试；`404` 本身不区分已删除与无权限。
* 此接口不移除团队成员，也不转交项目。移除团队成员的接口同样不会自动调用项目删除；如需先删除成员项目，应在撤销其访问权限前完成删除，或由仍具备项目删除权限的用户操作。
* OpenAPI 暂不提供项目恢复接口；软删除不代表已释放的云资源或域名一定可恢复。

### 请求示例

```text theme={null}
curl --request DELETE \
  --url "https://meoo.com/open/v1/projects/${PROJECT_ID}" \
  --header "Authorization: Bearer ${ACCESS_TOKEN}"
```

### 响应示例（HTTP 200）

```text theme={null}
{
  "project_id": "event-signup-demo",
  "status": "deleted"
}
```

| 字段          | 类型     | 说明                   |
| :---------- | :----- | :------------------- |
| project\_id | string | 已删除项目的公开 url\_id     |
| status      | string | 固定为 deleted，表示项目已软删除 |

### 常见错误

| HTTP 状态 / code          | 说明                                  |
| :---------------------- | :---------------------------------- |
| 400 invalid\_request    | 项目 ID 格式无效；只允许字母、数字、下划线、连字符，长度 1～50 |
| 401 invalid\_token      | Bearer 凭证无效、过期或已撤销                  |
| 403 insufficient\_scope | 缺少 project.write                    |
| 403 forbidden           | 项目级凭证试图访问非绑定项目                      |
| 404 not\_found          | 项目不存在、已删除、租户不匹配或调用方无删除权限            |
| 429                     | 调用频率超过限制；按 Retry-After 重试           |
| 500 server\_error       | 删除失败或结果暂时无法确认，可使用相同项目 ID 重试         |

限频：每个 Client 600 次/分钟，每个 Client + 用户 20 次/分钟；仍受资源接口的公共限流约束。

## 数据访问边界

用户身份来自 Bearer 凭证，接口不接受 `user_id` 或 `open_id` 参数来切换用户。项目接口只返回或操作当前用户有权访问的项目；Scope 允许调用某类接口，但不会绕过项目权限和账号权益校验。