CoreDash Agency API：管理项目并跨账户提取数据

为账户中的每个项目提供一把密钥

Agency API 专为管理多个项目的账户而设计。代理机构、运营十几个品牌的内部团队，以及任何不想在每次新客户入驻时都登录仪表板的人。只需生成一次主密钥（master key），即可创建、更新、删除项目，并使用该单一凭证读取所有项目的 Core Web Vitals 数据。

正在寻找按项目（per-project）划分的 API 吗？CoreDash API 页面涵盖了使用项目范围密钥的单个项目。相同的数据工具，范围更窄，设置更简单。

Agency API 主要有两个功能：

1. 项目 CRUD：在 /api/agency/projects 提供小巧的 REST 接口，用于创建、列出、更新和删除项目。
2. 跨项目数据读取：与按项目 API 相同的 JSON-RPC 工具（get_metrics、get_timeseries、get_histogram），位于 /api/mcp。使用主密钥时，你只需在参数中传递 project_id 即可选择所需的项目。

两种 API 密钥

CoreDash 颁发两个层级的密钥。每个层级的作用不同。

主密钥仅适用于标记为代理机构（agency）的账户。如果你没有看到下面描述的 Agency API 选项卡，请联系支持团队。

获取主密钥

主密钥是从 Web UI 生成的，而不是从 API 生成的。

1. 在 app.coredash.app 登录。
2. 打开 My Account（我的账户）并点击 Agency API 选项卡。
3. 点击 Generate master key（生成主密钥），为其命名，然后复制该值。它只会显示一次。

密钥以 cdk_master_ 开头。它们允许持有者管理属于你用户账户的每个项目，并读取其中任何项目的数据。请像对待密码一样对待它们。你可以从同一选项卡中撤销任何主密钥。

身份验证

每个 Agency API 请求都需要在 Authorization 标头中包含主密钥：

Authorization: Bearer cdk_master_YOUR_MASTER_KEY

相同的标头适用于 REST 项目 CRUD 端点和 JSON-RPC 数据端点。其他没有任何改变。

项目 CRUD：REST 接口

用于项目管理的基础 URL：

https://app.coredash.app/api/agency/projects

这些都是普通的 REST 调用。不是 JSON-RPC。

POST /api/agency/projects：创建项目

创建由主密钥用户拥有的新项目。默认情况下，项目以 10 天的试用期开始。传入 agencyplan 可以使其以付费计划开始，并拥有 33 天的计费周期。

curl -X POST https://app.coredash.app/api/agency/projects \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer cdk_master_YOUR_MASTER_KEY" \
  -d '{
    "name": "Acme client",
    "url": "https://acme.example",
    "agencyplan": "starter"
  }'

成功时的响应是 201：

{
  "status": 201,
  "project": {
    "_id": "655f1f77bcf86cd799439011",
    "name": "Acme client",
    "url": "https://acme.example",
    "status": "paid",
    "users": ["644..."],
    "expires": "2026-06-28T12:00:00.000Z",
    "alerts": { "ai": true },
    "created": { "date": "2026-05-26T12:00:00.000Z" }
  }
}

_id 就是你放在客户网站跟踪代码段（tracking snippet）中的内容。它也是你传递给下面数据工具的 project_id。

GET /api/agency/projects：列出项目

返回你的用户所拥有的项目，按创建日期排序（最新的排在前面）。通过 limit（最大 500，默认 100）和 offset 进行分页。

curl "https://app.coredash.app/api/agency/projects?limit=50" \
  -H "Authorization: Bearer cdk_master_YOUR_MASTER_KEY"

{
  "status": 200,
  "projects": [
    { "_id": "...", "name": "Acme client", "url": "https://acme.example", "status": "paid" },
    { "_id": "...", "name": "Beta client", "url": "https://beta.example", "status": "trial" }
  ]
}

GET /api/agency/projects/:id：获取一个项目

返回单个项目文档。如果你的用户不拥有该项目，则返回 404。我们故意不区分“未找到”和“不属于你”，因此无法跨账户枚举项目 ID。

curl https://app.coredash.app/api/agency/projects/655f1f77bcf86cd799439011 \
  -H "Authorization: Bearer cdk_master_YOUR_MASTER_KEY"

PATCH /api/agency/projects/:id：更新名称或 URL

更新 name 和/或 url。这两个字段都是可选的。省略的字段将保持原样。正文中的任何其他内容都将被忽略。状态、计费、到期和警报均通过仪表板进行管理。

curl -X PATCH https://app.coredash.app/api/agency/projects/655f1f77bcf86cd799439011 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer cdk_master_YOUR_MASTER_KEY" \
  -d '{ "name": "Acme client renamed" }'

DELETE /api/agency/projects/:id：硬删除一个项目

删除该项目及其附加的所有内容：Lighthouse 运行记录、CrUX 数据、警报、快照和快照配置。

后端数据存储中的 RUM 数据在此调用中不会被删除。它保留了在旧项目 ID 上的键值，但成为了孤立数据。没有恢复途径。该项目 ID 将被停用。

curl -X DELETE https://app.coredash.app/api/agency/projects/655f1f77bcf86cd799439011 \
  -H "Authorization: Bearer cdk_master_YOUR_MASTER_KEY"

{ "status": 200, "deleted": true }

使用主密钥读取数据

要提取你的其中一个项目的 Core Web Vitals 数据，请请求与按项目 API 使用的相同的 JSON-RPC 端点：

https://app.coredash.app/api/mcp

这三个工具保持不变：get_metrics、get_timeseries、get_histogram。与按项目流程相比，唯一的区别是你需要在 arguments 中传递 project_id，以便调用知道要查看哪个项目。项目密钥不需要这样做，因为每个项目密钥已经限定在了一个项目的范围内。主密钥涵盖多个项目，因此请求必须指定一个。

示例：针对特定项目的 get_metrics

curl -X POST https://app.coredash.app/api/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer cdk_master_YOUR_MASTER_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "get_metrics",
      "arguments": {
        "project_id": "655f1f77bcf86cd799439011",
        "metrics": "LCP,INP,CLS",
        "date": "-7d"
      }
    }
  }'

响应与按项目 API 的 JSON-RPC 包装器相同，解析后的 payload（有效负载）位于 result.content[0].text 中。内部 JSON 的形状、distribution 对象、时间序列上的 summary 字段、直方图上的存储桶结构，所有这些的行为都与使用项目密钥时相同。唯一额外的要求是 project_id 参数。

这同样适用于 get_timeseries 和 get_histogram。传入 project_id，然后是常用的参数。

所有其他参数的作用方式都相同：filters、group、percentile、date、granularity 等等。所有维度参考（d、cc、ff、lcpel、inpel），指标阈值和百分位数的语义都记录在 CoreDash API 页面上。请阅读该页面以获取完整的参数和维度说明。本页面仅涵盖使用主密钥进行身份验证时的不同之处。

引入新客户项目

代理机构添加新客户的典型流程：

1. 在 My Account → Agency API 选项卡 中生成一次主密钥并妥善存储。
2. 使用客户名称和 URL 发起 POST /api/agency/projects 请求。响应将包含新的 _id。
3. 将包含该 _id 的跟踪代码段嵌入客户的网站。
4. 可以随时通过 POST /api/mcp 读取该项目的 RUM 数据，在参数中使用相同的主密钥和 "project_id": "<该 _id>"。不需要单独的项目密钥。

这就是整个引入循环。一个密钥，一次 POST 请求，一次代码段嵌入，你就已经可以查询新项目的数据了。

错误

项目 CRUD 端点返回普通的 REST 状态码：

在 /api/mcp 的数据读取将返回 JSON-RPC 错误对象，这与使用项目密钥相同。错误代码表在 CoreDash API 页面上。如果你收到 -32001 错误，请仔细检查你的密钥是否以 cdk_master_ 开头，并且你是否在参数中包含了 project_id。

速率限制

当读取数据时，按项目每日的限制仍然适用：主密钥为项目 A 调用 get_metrics 会消耗项目 A 的每日配额，而为项目 B 调用则会消耗项目 B 的配额。请参阅 CoreDash API 页面上的速率限制表。项目 CRUD 调用不受这种方式的速率限制。