CoreDash Agency API: Gerencie Projetos e Extraia Dados Entre Contas
Gerencie vários projetos a partir de uma conta. Crie uma chave mestra uma vez, crie e exclua projetos via REST, e extraia dados do Core Web Vitals através de todos eles com uma única chave.
Trusted by market leaders · Client results
Uma chave para cada projeto na sua conta
A Agency API é para contas que gerenciam muitos projetos. Agências, equipes internas que operam diversas marcas, qualquer pessoa que não queira fazer login no dashboard sempre que um novo cliente entrar a bordo. Crie uma chave mestra uma vez, e em seguida crie projetos, atualize-os, exclua-os e leia dados do Core Web Vitals através de todos eles com essa única credencial.
Procurando pela API por projeto em vez disso? A página da CoreDash API abrange um único projeto com uma chave com escopo de projeto. Mesmas ferramentas de dados, escopo mais restrito, configuração mais simples.
A Agency API 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 chave mestra você passaproject_idnos argumentos para escolher qual projeto você quer.
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 |
|---|---|---|---|
| Chave de projeto | cdk_ | Um projeto | Lê dados de RUM para aquele projeto através do endpoint JSON-RPC. Veja /api. |
| Chave mestra | cdk_master_ | Todos os projetos da conta | Cria, lista, atualiza e exclui projetos através de REST. Também lê dados de qualquer projeto na conta ao passar project_id nas ferramentas de dados. |
As chaves mestras estão disponíveis apenas em contas marcadas como agência. Se você não vir a aba Agency API descrita abaixo, fale com o suporte.
Obtenha uma chave mestra
As chaves mestras são geradas a partir da interface web (UI), não da 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 é exibido apenas uma vez.
As chaves começam com cdk_master_. Elas permitem que o portador gerencie cada projeto que pertence à sua conta de usuário e leia dados de qualquer um deles. Trate-as como senhas. Você pode revogar qualquer chave mestra na mesma aba.
Autenticação
Toda requisição para a Agency API precisa de uma chave mestra no cabeçalho Authorization:
Authorization: Bearer cdk_master_YOUR_MASTER_KEY
O mesmo cabeçalho funciona tanto para os endpoints REST de CRUD do projeto quanto para o endpoint de dados JSON-RPC. 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 simples. Não JSON-RPC.
POST /api/agency/projects: crie um projeto
Cria um novo projeto de propriedade do usuário da chave mestra. Por padrão, o projeto inicia como uma avaliação (trial) de 10 dias. Passe agencyplan para iniciá-lo em um plano pago em vez disso, com um período de faturamento de 33 dias.
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
name | string | sim | Nome do projeto exibido 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 uma avaliação. |
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: liste projetos
Retorna os projetos que o seu usuário possui, ordenados pela data de criação (os mais recentes primeiro). Paginado com limit (máximo 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: busque um projeto
Retorna um único documento de projeto. Retorna 404 se o seu usuário não possuir o projeto. Nós 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: atualize o nome ou URL
Atualiza o name e/ou url. Ambos os campos são opcionais. Campos omitidos permanecem como estavam. Qualquer outra coisa no corpo (body) é ignorada. Status, faturamento, expiração 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: exclua permanentemente 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 armazenamento de dados de apoio não são excluídos nesta chamada. Eles permanecem vinculados ao ID antigo do projeto, mas tornam-se órfãos. Não há caminho de recuperação. O ID do projeto é desativado.
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 chave mestra
Para extrair dados do Core Web Vitals de 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 continuam inalteradas: get_metrics, get_timeseries, get_histogram. A única diferença em comparação com o fluxo por projeto é que você passa project_id em arguments para que a chamada saiba para qual projeto olhar. Chaves de projeto não precisam disso porque cada chave de projeto já tem o escopo de um projeto. Chaves mestras cobrem muitos projetos, então a requisição tem que 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 da API por projeto, com o payload processado em result.content[0].text. O formato 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 chave de projeto. O único requisito extra é o argumento project_id.
O mesmo se aplica a get_timeseries e get_histogram. Passe o project_id e depois os argumentos habituais.
Todos os outros parâmetros funcionam da mesma forma: filters, group, percentile, date, granularity, e assim por diante. A referência de dimensões (d, cc, ff, lcpel, inpel, todas elas), os limiares das métricas e a semântica de percentis estão todos documentados na página da CoreDash API. Leia isso para conhecer a superfície completa de parâmetros e dimensões. Esta página cobre apenas o que é diferente quando você se autentica com uma chave mestra.
Integração (onboarding) de um novo projeto de cliente
O fluxo típico para uma agência adicionando um novo cliente:
- Gere uma chave mestra uma vez em My Account → aba Agency API e armazene-a de forma segura.
- Faça um
POST /api/agency/projectscom o nome e a URL do cliente. A resposta contém o novo_id. - Incorpore o snippet de rastreamento no site do cliente com esse
_id. - Leia os dados de RUM para aquele projeto a qualquer momento via
POST /api/mcpcom a mesma chave mestra e"project_id": "<o _id>"nos argumentos. Nenhuma chave de projeto separada é necessária.
Esse é todo o ciclo 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 simples:
| Status | Significado |
|---|---|
400 | Campo obrigatório ausente na criação, ou ID de plano desconhecido. |
401 | Chave mestra ausente, inválida ou revogada. |
404 | Projeto não encontrado, ou não pertence ao seu usuário. |
500 | Erro no banco de dados. |
As leituras de dados em /api/mcp retornam objetos de erro JSON-RPC, da mesma forma que com uma chave de projeto. A tabela de códigos de erro está na página da CoreDash API. 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 chave mestra chamando get_metrics para o projeto A conta na cota diária do projeto A, e uma chamada para o projeto B conta na do projeto B. Consulte a tabela de limites de taxa na página da CoreDash API. As chamadas de CRUD de projeto não possuem os mesmos limites de taxa.
