# Listings API 参考文档

`PUT /api/listings` 通过一次原子调用创建或更新一个完整的 API 上架页：包括该 API、它的端点、源站密钥、套餐、FAQ 和关联 API。要么全部保存成功，要么什么都不保存。`provider_*` MCP 工具底层正是使用这个接口，你也可以直接从脚本或 CI 中调用它。

## 访问权限

- 任何**已验证邮箱**的账户。未验证或被封禁的账户会收到 `403`。
- 使用你的 [API 密钥](https://zylalabs.com/zh/docs/api-keys) 进行认证：`Authorization: Bearer YOUR_API_KEY`。
- 每个账户的速率限制：每分钟 30 次写入（upsert）和 120 次读取。
- 新建的 API 上架页会计入 [新 API 配额](https://zylalabs.com/zh/docs/quality-rules)，更新则不会。

## 端点

| 方法 | 路径 | 用途 |
|---|---|---|
| PUT | `/api/listings` | 创建或更新一个 API 上架页（传入 `"delete": true` 可删除它） |
| GET | `/api/listings` | 获取你的 API 上架页列表（`status`、`page`、`per_page`） |
| GET | `/api/listings/{product_key}` | 某个 API 上架页的完整定义（不会包含源站密钥） |
| GET | `/api/listings/me` | 你的账户信息、限额、有效的套餐名称和参数类型 |
| GET | `/api/listings/categories` | 分类 ID |

## 示例

```bash
curl -X PUT https://zylalabs.com/api/listings \
  -H "Authorization: Bearer $ZYLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d @listing.json
```

`listing.json`:

```json
{
  "product_key": "trustpilot-api",
  "publish": true,
  "api": {
    "name": "Trustpilot Reviews API",
    "short_description": "Retrieve Trustpilot company reviews, ratings and reviewer details in JSON.",
    "trial": false
  },
  "access": { "in": "header", "key": "X-Origin-Key", "value": "your-origin-secret" },
  "endpoints": [{
    "name": "Get Company Reviews",
    "description": "Returns the latest public reviews for a company domain with pagination.",
    "method": "GET",
    "base_url": "https://origin.example.com/v1/items/||domain||",
    "path_params": { "domain": "example.com" },
    "parameters": [
      { "key": "page", "type": "number", "description": "Page number, starting at 1.", "value": "1", "required": false }
    ],
    "headers": [{ "key": "Accept", "value": "application/json" }],
    "example_response": { "reviews": [{ "rating": 5 }] }
  }],
  "plans": [
    { "name": "Basic", "interval": "Monthly", "price": 24.99, "max_requests": 1000 },
    { "name": "Pro", "interval": "Monthly", "price": 49.99, "max_requests": 5000 },
    { "name": "ProPlus", "interval": "Monthly", "price": 99.99, "max_requests": 15000, "rate_limit": 120 }
  ],
  "faqs": [{ "question": "What data does it return?", "answer": "Public reviews with rating and text." }],
  "slaves": [{ "name": "Company Reviews Lookup API" }]
}
```

## 规则

**标识。** `product_key` 是你为该 API 上架页设置的专属稳定 ID。使用一个新的 key 会创建该上架页；使用你已经用过的 key 会更新它。一个 key 归创建它的账户所有（其他账户使用会收到 `403`）。已删除的上架页不接受编辑（`409`）。

**发布。** 当该 API 上架页通过 [质量规则](https://zylalabs.com/zh/docs/quality-rules) 的检查，并且至少有一个带示例响应的端点和生效的套餐时，它就会上线。如果不满足这些条件，`"publish": true` 会返回 `422`。不传 `publish` 字段表示一旦就绪就立即发布；传 `"publish": false` 则保持为草稿。`false` 永远不会让已上线的上架页下线。

**API 字段。** `name` 遵循 [名称规则](https://zylalabs.com/zh/docs/quality-rules)：最多 50 个字符，必须包含单词 “API”，在 Hub 上必须唯一。`short_description` 至少 50 个字符。上架页的其余内容由 Zyla 为你补全：详细描述会根据你的简短描述自动生成，分类和标签则由 AI 选择。如果你传入 `long_description`、`category_id`、`tags` 或 `website_url`，它们会被忽略，并列在 `warnings` 中。

**端点。** 当传入 `endpoints` 字段时，它代表完整的端点列表：端点按方法 + `base_url`（不含查询字符串）匹配，新的端点会被创建，列表中缺失的端点会被删除。不传 `endpoints` 则保持原有端点不变。
- 描述至少 40 个字符。方法为 GET、POST、PUT、DELETE 或 PATCH。
- `base_url` 必须是合法的 URL。路径参数用 `||` 包裹，例如 `/items/||domain||`，并在 `path_params` 中给出示例值。
- 每个参数需要 `key`、`type`（string、number、email、url、domain、date、datetime）以及至少 10 个字符的描述。
- `example_response` 为必填项，最多 10,000 个字符。

**源站密钥（`access`）。** 这是 Zyla 在每次调用你的源站时附加的请求头或查询参数，使你的服务器只接受来自 Hub 的流量。它会被隐藏存储，永远不会被返回或记录。不传此字段会保留当前的密钥；传 `null` 可将其移除。

**套餐。** 名称必须精确为：Free、Basic、Pro、ProPlus、Premium、Elite、Ultimate、Pay as you go。`price` 单位为美元；按年计费的套餐填写其最终年度价格。`max_requests` 为每个周期的调用次数；同一计费周期内，更贵的套餐必须包含更多调用次数。`rate_limit` 范围为每分钟 60 到 240 次。必须始终保持至少三个生效的付费月度套餐。如果新建 API 上架页时不传套餐，会创建一组默认套餐。

**FAQ。** 如果提供，则为完整列表，最多 10 条。问题 5–100 个字符，答案 3–700 个字符。

**关联 API（`slaves`）。** 是你某个 API 的变体，拥有自己的名称和页面，但复用其端点。它们按名称匹配，并会跟随主 API 端点的变化。主 API 必须有端点，而关联 API 自己不能再有关联 API。

**删除。** `{"product_key": "...", "delete": true}` 会删除该 API 上架页。如果它还有付费订阅，删除会被拒绝并返回 `409`。关联 API 只有在 `slaves` 中被指定时才会被删除。

**不支持的功能。** 响应转换、请求体和文件上传（`422 not_supported`）。这些需求请使用网页向导完成。

## 响应

成功：`{"success": true, "listing": {...}, "warnings": []}`，创建时返回 `201`，更新时返回 `200`。该 API 上架页一旦上线，会设置 `listing.url`。

| 状态码 | `code` | 含义 |
|---|---|---|
| 401 | `unauthenticated` | 密钥缺失或无效 |
| 403 | `forbidden` | 账户未验证或已被封禁，或该 `product_key` 属于另一个账户 |
| 404 | `not_found` | 未知的 `product_key` |
| 409 | `name_taken`, `active_subscriptions`, `endpoints_required`, `listing_deleted`, `slave_of_slave`, `product_key_conflict` | 冲突；未做任何更改 |
| 422 | `validation_failed`, `ai_validation_failed`, `not_supported` | `errors` 按字段列出，例如 `endpoints.2.parameters.0.description` |
| 429 | `creation_limit_reached` | 新 API 配额已用完；`retry_after` 为重试等待的秒数，并附带 `Retry-After` 响应头 |
| 503 | `ai_unavailable` | 内容审核未响应；未保存任何内容；请重试 |
| 500 | `server_error` | 意外错误；未保存任何内容 |


---
Source: https://zylalabs.com/zh/docs/listings-api