Listings API 参考文档

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

访问权限

• 任何已验证邮箱的账户。未验证或被封禁的账户会收到 403。
• 使用你的 API 密钥 进行认证：Authorization: Bearer YOUR_API_KEY。
• 每个账户的速率限制：每分钟 30 次写入（upsert）和 120 次读取。
• 新建的 API 上架页会计入 新 API 配额，更新则不会。

端点

示例

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

listing.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 上架页通过 质量规则 的检查，并且至少有一个带示例响应的端点和生效的套餐时，它就会上线。如果不满足这些条件，"publish": true 会返回 422。不传 publish 字段表示一旦就绪就立即发布；传 "publish": false 则保持为草稿。false 永远不会让已上线的上架页下线。

API 字段。 name 遵循 名称规则：最多 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。