API Agency do CoreDash: Gerencie Projetos e Extraia Dados Entre Contas
Gerencie muitos projetos em uma única conta. Emita uma master key uma vez, crie e exclua projetos via REST, e extraia dados do Core Web Vitals em todos eles usando uma única chave.
Trusted by market leaders · Client results
Uma chave para cada projeto na sua conta
A API Agency é para contas que gerenciam muitos projetos. Agências, equipes internas administrando dezenas de marcas, qualquer um que não queira fazer login no dashboard toda vez que um novo cliente entrar. Emita uma master key uma vez e, em seguida, crie projetos, atualize-os, exclua-os e leia os dados do Core Web Vitals de todos eles com essa única credencial.
Está procurando a API por projeto em vez disso? A página da API do CoreDash abrange um único projeto com uma chave de escopo do projeto. Mesmas ferramentas de dados, escopo mais restrito, configuração mais simples.
A API Agency faz duas coisas:
- CRUD de Projetos: uma pequena superfície REST em
/api/agency/projectspara criar, listar, atualizar e excluir projetos. - Leituras de dados entre projetos: as mesmas ferramentas JSON-RPC da API por projeto (
get_metrics,get_timeseries,get_histogram) em/api/mcp. Com uma master key você passa oproject_idnos argumentos para escolher qual projeto deseja.
Dois tipos de chaves de API
O CoreDash emite dois níveis de chaves. Cada um tem um trabalho diferente.
| Chave | Prefixo | Escopo | O que faz |
|---|---|---|---|
| Project key | cdk_ | Um projeto | Lê dados de RUM para aquele projeto através do endpoint JSON-RPC. Veja /api. |
| Master key | cdk_master_ | Todos os projetos na conta | Cria, lista, atualiza e exclui projetos através de REST. Também lê dados de qualquer projeto na conta passando project_id nas ferramentas de dados. |
As master keys estão disponíveis apenas em contas sinalizadas como agências. Se você não vê a aba API Agency descrita abaixo, fale com o suporte.
Obtenha uma master key
As master keys são emitidas através da interface web, não pela API.
- Faça login em app.coredash.app.
- Abra My Account e clique na aba Agency API.
- Clique em Generate master key, dê um nome a ela e copie o valor. Ele será exibido apenas uma vez.
As chaves começam com cdk_master_. Elas permitem que o portador gerencie todos os projetos que pertencem à sua conta de usuário e leia os dados de qualquer um deles. Trate-as como senhas. Você pode revogar qualquer master key na mesma aba.
Autenticação
Toda requisição à API Agency precisa de uma master key no cabeçalho Authorization:
Authorization: Bearer cdk_master_YOUR_MASTER_KEY
O mesmo cabeçalho funciona tanto para os endpoints REST de CRUD de projetos quanto para o endpoint JSON-RPC de dados. Nada mais muda.
CRUD de Projetos: a superfície REST
URL base para gerenciamento de projetos:
https://app.coredash.app/api/agency/projects
Estas são chamadas REST comuns. Não são JSON-RPC.
POST /api/agency/projects: crie um projeto
Cria um novo projeto de propriedade do usuário da master key. Por padrão, o projeto começa como um trial de 10 dias. Passe agencyplan para iniciá-lo em um plano pago, com um período de cobrança de 33 dias.
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
name | string | sim | Nome do projeto mostrado no dashboard. |
url | string | não | A URL do site que o projeto rastreia. |
agencyplan | string | não | ID do plano (por exemplo, starter). Quando definido, o projeto inicia no plano pago correspondente em vez de um trial. |
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"
}'
A resposta em caso de sucesso é 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" }
}
}
O _id é o que você coloca no snippet de rastreamento no site do cliente. É também o project_id que você passa para as ferramentas de dados abaixo.
GET /api/agency/projects: listar projetos
Retorna os projetos dos quais seu usuário é dono, ordenados por data de criação (mais recentes primeiro). Paginado com limit (máx. 500, padrão 100) e 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: buscar um projeto
Retorna um único documento de projeto. Retorna 404 se o seu usuário não for o dono do projeto. Deliberadamente, não diferenciamos "não encontrado" de "não é seu" para que os IDs de projeto não possam ser enumerados entre contas.
curl https://app.coredash.app/api/agency/projects/655f1f77bcf86cd799439011 \ -H "Authorization: Bearer cdk_master_YOUR_MASTER_KEY"
PATCH /api/agency/projects/:id: atualizar nome ou URL
Atualiza o name e/ou url. Ambos os campos são opcionais. Os campos omitidos são deixados como estavam. Qualquer outra coisa no corpo (payload) é ignorada. Status, faturamento, validade e alertas são gerenciados através do dashboard.
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: exclusão definitiva de um projeto
Exclui o projeto e tudo anexado a ele: execuções do Lighthouse, dados do CrUX, alertas, snapshots e configurações de snapshot.
Os dados de RUM no repositório de dados subjacente não são excluídos nesta chamada. Eles permanecem vinculados ao ID do projeto antigo, mas ficam órfãos. Não há caminho de recuperação. O ID do projeto é aposentado.
curl -X DELETE https://app.coredash.app/api/agency/projects/655f1f77bcf86cd799439011 \ -H "Authorization: Bearer cdk_master_YOUR_MASTER_KEY"
{ "status": 200, "deleted": true }
Lendo dados com uma master key
Para extrair dados do Core Web Vitals para um dos seus projetos, acesse o mesmo endpoint JSON-RPC que a API por projeto usa:
https://app.coredash.app/api/mcp
As três ferramentas não mudam: get_metrics, get_timeseries, get_histogram. A única diferença em comparação ao fluxo por projeto é que você passa o project_id em arguments para que a chamada saiba para qual projeto olhar. As project keys não precisam disso porque cada project key já tem o escopo de um projeto. As master keys cobrem muitos projetos, então a requisição precisa nomear um.
Exemplo: get_metrics para um projeto específico
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"
}
}
}'
A resposta é o mesmo wrapper JSON-RPC que a API por projeto, com o payload analisado em result.content[0].text. A forma do JSON interno, o objeto distribution, o campo summary nas séries temporais, a estrutura de buckets nos histogramas, todos se comportam da mesma maneira que com uma project key. O único requisito extra é o argumento project_id.
O mesmo se aplica ao get_timeseries e get_histogram. Passe project_id, depois os argumentos usuais.
Todos os outros parâmetros funcionam da mesma maneira: filters, group, percentile, date, granularity, e assim por diante. A referência de dimensões (d, cc, ff, lcpel, inpel, todas elas), os limites das métricas e a semântica de percentis estão todos documentados na página da API do CoreDash. Leia para obter a superfície completa de parâmetros e dimensões. Esta página cobre apenas o que é diferente quando você se autentica com uma master key.
Onboarding de um novo projeto de cliente
O fluxo típico para uma agência adicionar um novo cliente:
- Emita uma master key uma vez na aba My Account → Agency API e armazene-a de forma segura.
- Faça um
POST /api/agency/projectscom o nome e URL do cliente. A resposta contém o novo_id. - Incorpore o snippet de rastreamento no site do cliente com aquele
_id. - Leia dados de RUM para aquele projeto a qualquer momento via
POST /api/mcpcom a mesma master key e"project_id": "<o _id>"nos argumentos. Nenhuma project key separada é necessária.
Esse é todo o loop de onboarding. Uma chave, um POST, uma incorporação de snippet, e você já pode consultar os dados do novo projeto.
Erros
Os endpoints de CRUD de projetos retornam códigos de status REST comuns:
| Status | Significado |
|---|---|
400 | Campo obrigatório faltando na criação ou id de plano desconhecido. |
401 | Master key faltando, inválida ou revogada. |
404 | Projeto não encontrado ou não pertence ao seu usuário. |
500 | Erro de banco de dados. |
As leituras de dados em /api/mcp retornam objetos de erro JSON-RPC, o mesmo que com uma project key. A tabela de códigos de erro está na página da API do CoreDash. Se você receber -32001, verifique novamente se a sua chave começa com cdk_master_ e se você incluiu project_id nos argumentos.
Limites de taxa
Os limites diários por projeto ainda se aplicam quando você lê dados: uma master key chamando get_metrics para o projeto A conta no limite diário do projeto A, e uma chamada para o projeto B conta no limite do projeto B. Veja a tabela de limites de taxa na página da API do CoreDash. As chamadas de CRUD de projetos não têm limite de taxa da mesma maneira.
