合作伙伴 API

概述

Firecrawl 合作伙伴集成 API 让你的平台可以直接在自己的后端为用户创建和管理 Firecrawl API 密钥。用户无需离开你的平台即可开始使用 Firecrawl。

你可以在 Firecrawl dashboard 中自行配置合作伙伴 API。组织中的任何管理员或成员都可以创建集成：命名、选择一种配置方式、接受该方式对应的协议，然后复制合作伙伴密钥。该密钥仅显示一次。之后你可以在 Settings 中签发和吊销密钥。无需申请或审批。

共有两种配置方式。两者开通账户的流程相同，都通过下方的接口完成；区别在于由谁为用户的使用量付费：

Partner API：每个开通的账户各自保留自己的 Firecrawl 方案和计费。用户从 Free 套餐起步，直接向 Firecrawl 升级。
Gateway：由你的集成创建的账户会被纳入 Gateway，因此在用户自身的额度用尽后，其符合条件的使用量将计费到你的组织。Gateway 账户仅支持 API 调用，没有自己的 dashboard 登录入口。

配置方式在创建集成时选定，之后不易更改，因此我们建议在接受协议前仔细比较两种选项。请参见合作伙伴 API 页面了解概况。部分合作伙伴优惠会为开通的用户赠送促销额度；如有此类优惠，合作伙伴额度会说明用户具体能获得什么。

基本 URL

https://integrations.firecrawl.dev

身份验证

所有合作伙伴集成 API 请求都必须在 Authorization 标头中附带您的合作伙伴密钥：

Authorization: Bearer <partner key>

合作伙伴密钥与标准 Firecrawl API 密钥不同。您可以在 Firecrawl dashboard 的 Settings > Partner API 中创建和吊销合作伙伴密钥。

安全要求

仅限服务器端：合作伙伴密钥只能用于服务器端代码。切勿在前端代码、客户端 JavaScript 或移动应用中暴露合作伙伴密钥。
服务条款：调用 POST /partner/v1/accounts 前，你的平台必须提示用户接受 Firecrawl 的服务条款。

接口

创建用户

为你的某个用户 (以邮箱地址标识) 开通 Firecrawl 账户，并返回其 API 密钥。

POST /partner/v1/accounts

行为说明

采用 合作伙伴 API 配置方式时：

如果用户还没有 Firecrawl 账户，则会创建新用户和新团队。
如果用户已有 Firecrawl 账户，但没有与你的集成关联的团队，则会创建一个新的合作伙伴关联团队。
如果用户已有 Firecrawl 账户，且已有与你的集成关联的团队，则返回该已有团队。

采用 Gateway 配置方式时：

每个账户都只为你的集成创建。即使邮箱地址相同，请求也绝不会关联到已有的 Firecrawl 账户。该邮箱仅作为账户的联系地址存储，不用于查找账户。
对同一邮箱重复调用会返回同一个账户及其 API 密钥。

如果你的集成包含促销额度，这些额度只在账户首次创建时发放一次。

请求

cURL

curl -X POST "https://integrations.firecrawl.dev/partner/v1/accounts" \
  -H "Authorization: Bearer <partner key>" \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com"}'

请求体

字段	类型	必填	描述
`email`	string	是	用户邮箱地址。在 Gateway 配置方式下，它会被存储为该账户的联系地址。

响应

200 OK

{
  "apiKey": "fc-...",
  "alreadyExisted": false
}

在 Gateway 配置方式下，响应中还会包含注册 status：

{
  "apiKey": "fc-...",
  "alreadyExisted": false,
  "gatewayStatus": "enrolled"
}

字段	类型	描述
`apiKey`	string	该用户所属合作伙伴关联团队的 Firecrawl API 密钥
`alreadyExisted`	boolean	如果你的集成已为该邮箱开通过账户，则为 `true`。它并不说明该邮箱是否存在于 Firecrawl 的其他地方。
`gatewayStatus`	string	仅适用于Gateway 集成。创建账户的那次调用返回 `enrolled`，对同一邮箱的重复调用返回 `already_enrolled`。

错误

状态	描述
`400`	请求错误 - `email` 缺失或格式不正确
`401`	未授权 - 合作伙伴密钥不正确或无效
`500`	内部服务器错误 - 这些错误会由 Firecrawl 监控

验证 API 密钥

验证 Firecrawl API 密钥，并返回关联的团队名称和用户邮箱地址。只有通过此合作伙伴集成创建的 API 密钥才会被视为有效。

POST /partner/v1/api-keys/validate

重要说明

Firecrawl API 密钥不设权限，也不会过期。
用户可以随时手动删除 API 密钥。
已删除的 API 密钥不会进行软删除。Firecrawl 无法区分某个密钥是已被删除，还是从未存在过。

请求

cURL

curl -X POST "https://integrations.firecrawl.dev/partner/v1/api-keys/validate" \
  -H "Authorization: Bearer <partner key>" \
  -H "Content-Type: application/json" \
  -d '{"apiKey": "fc-..."}'

请求体

字段	类型	必填	描述
`apiKey`	string	是	待验证的 API 密钥

响应

200 OK

{
  "teamName": "Example Team",
  "email": "user@example.com"
}

字段	类型	描述
`teamName`	string	与此 API 密钥关联的团队名称
`email`	string	开通该账户时使用的邮箱。对于 Gateway 账户，即你提供的联系地址。

错误

状态	描述
`400`	请求错误 - API 密钥格式不正确
`401`	未授权 - 合作伙伴密钥不正确或无效
`404`	无法识别 API 密钥 - 该密钥不存在或并非通过此合作伙伴集成创建
`500`	内部服务器错误 - 这些错误会由 Firecrawl 监控

轮换 API 密钥

删除现有的 Firecrawl API 密钥，并为同一用户和团队生成一个新的密钥。

POST /partner/v1/api-keys/rotate

请求

cURL

curl -X POST "https://integrations.firecrawl.dev/partner/v1/api-keys/rotate" \
  -H "Authorization: Bearer <partner key>" \
  -H "Content-Type: application/json" \
  -d '{"apiKey": "fc-..."}'

请求体

字段	类型	必填	描述
`apiKey`	string	是	要删除并替换的 API 密钥

响应

200 OK

{
  "apiKey": "fc-..."
}

字段	类型	描述
`apiKey`	string	新创建的 API 密钥

错误

状态	描述
`401`	未授权 - 合作伙伴密钥不正确或无效
`404`	API 密钥无法识别 - 该密钥不存在，或并非通过此合作伙伴集成创建
`500`	内部服务器错误 - 此类错误会由 Firecrawl 监控

开始使用

在 Firecrawl Dashboard 中创建你的集成：登录后选择 Partner API 或 Gateway，接受协议，然后复制你的合作伙伴密钥。该配置方式在完成后不易更改，请在接受协议前确认你的选择。之后即可从你的服务器调用上述接口。对配置方式有疑问？欢迎联系 help@firecrawl.com。想做更大规模的集成？欢迎联系 partnerships@firecrawl.dev。

使用 API

搜索端点

抓取端点

交互 / 浏览器沙箱端点

研究索引端点

开发者索引端点

map端点

解析端点

爬取端点

监控端点

代理端点

反馈端点

代理式调试端点

账户端点

Webhook 负载

合作伙伴 API

概述

基本 URL

身份验证

安全要求

接口

创建用户

行为说明

请求

响应

错误

验证 API 密钥

重要说明

请求

响应

错误

轮换 API 密钥

请求

响应

错误

开始使用

​概述

​基本 URL

​身份验证

​安全要求

​接口

​创建用户

​行为说明

​请求

​响应

​错误

​验证 API 密钥

​重要说明

​请求

​响应

​错误

​轮换 API 密钥

​请求

​响应

​错误

​开始使用

概述

基本 URL

身份验证

安全要求

接口

创建用户

行为说明

请求

响应

错误

验证 API 密钥

重要说明

请求

响应

错误

轮换 API 密钥

请求

响应

错误

开始使用