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

使用单一密钥管理您账户下的所有项目

Agency API 专为管理多个项目的账户设计。代理机构、运营十几个品牌的内部团队、以及任何不想在每次新客户加入时都登录仪表板的人。一次性生成主密钥，然后即可通过该单一凭据创建项目、更新项目、删除项目，并读取所有这些项目中的 Core Web Vitals 数据。

在寻找按项目划分的 API 吗？CoreDash API 页面涵盖了使用项目作用域密钥的单个项目。相同的数据工具，更窄的作用域，更简单的设置。

Agency API 执行两项操作：

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

两种类型的 API 密钥

CoreDash 提供两个层级的密钥。每个层级各有其职。

主密钥仅适用于带有代理机构标记的账户。如果您没有看到下面描述的 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 即为您放置在客户端网站跟踪代码片段中的标识符。它也是您传递给下方数据工具的 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 数据。它仍然保留旧的 project 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"
      }
    }
  }'

响应的 JSON-RPC 包装器与单项目 API 相同，解析后的 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 请求，携带相同主密钥并在参数中添加 "project_id": "<the _id>"，随时读取该项目的 RUM 数据。无需单独的项目密钥。

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

错误处理

项目 CRUD 端点会返回标准的 REST 状态码：

在 /api/mcp 的数据读取将返回 JSON-RPC 错误对象，这与使用项目密钥时相同。错误代码对照表位于 CoreDash API 页面。如果您收到 -32001，请再次检查您的密钥是否以 cdk_master_ 开头，并确认您已在参数中包含了 project_id。

速率限制

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