CoreDash Agency API: Gestiona proyectos y extrae datos de varias cuentas

Gestiona muchos proyectos desde una sola cuenta. Acuña una clave maestra una vez, crea y elimina proyectos mediante REST, y extrae datos de Core Web Vitals de todos ellos con una única clave.

Arjen Karel Core Web Vitals Consultant
Arjen Karel - linkedin
Last update: 2026-05-29

Trusted by market leaders · Client results

aleteialoopearplugssnvmonarchvpnebayharvardcomparemarktplaatsfotocasaadevintawhowhatweardpg mediaperionhappyhorizonkpnnina caresaturnworkivaerasmusmcmy work featured on web.devnestle

Una clave para cada proyecto en tu cuenta

La Agency API es para cuentas que gestionan muchos proyectos. Agencias, equipos internos que manejan una docena de marcas, cualquiera que no quiera iniciar sesión en el panel de control cada vez que se incorpora un nuevo cliente. Acuña una clave maestra una vez, luego crea proyectos, actualízalos, elimínalos y lee datos de Core Web Vitals en todos ellos con esa única credencial.

¿Buscas la API por proyecto en su lugar? La página de CoreDash API cubre un solo proyecto con una clave de ámbito de proyecto. Mismas herramientas de datos, alcance más reducido, configuración más sencilla.

La Agency API hace dos cosas:

  1. CRUD de proyectos: una pequeña superficie REST en /api/agency/projects para crear, enumerar, actualizar y eliminar proyectos.
  2. Lecturas de datos entre proyectos: las mismas herramientas JSON-RPC que la API por proyecto (get_metrics, get_timeseries, get_histogram) en /api/mcp. Con una clave maestra pasas el project_id en los argumentos para elegir qué proyecto quieres.

Dos tipos de claves de API

CoreDash emite dos niveles de claves. Cada uno tiene un trabajo diferente.

ClavePrefijoAlcanceQué hace
Clave de proyectocdk_Un proyectoLee datos RUM para ese proyecto a través del endpoint JSON-RPC. Consulta /api.
Clave maestracdk_master_Cada proyecto en la cuentaCrea, enumera, actualiza y elimina proyectos mediante REST. También lee datos para cualquier proyecto en la cuenta pasando project_id en las herramientas de datos.

Las claves maestras solo están disponibles en cuentas marcadas como agencia. Si no ves la pestaña Agency API que se describe a continuación, habla con soporte.

Obtener una clave maestra

Las claves maestras se acuñan desde la interfaz de usuario web, no desde la API.

  1. Inicia sesión en app.coredash.app.
  2. Abre My Account y haz clic en la pestaña Agency API.
  3. Haz clic en Generate master key, dale un nombre y copia el valor. Se muestra una sola vez.

Las claves comienzan con cdk_master_. Permiten al titular gestionar cada proyecto que pertenece a tu cuenta de usuario y leer datos de cualquiera de ellos. Trátalas como contraseñas. Puedes revocar cualquier clave maestra desde la misma pestaña.

Autenticación

Cada solicitud a la Agency API necesita una clave maestra en el encabezado Authorization:

Authorization: Bearer cdk_master_YOUR_MASTER_KEY

El mismo encabezado funciona tanto para los endpoints CRUD de proyectos REST como para el endpoint de datos JSON-RPC. Nada más cambia.

CRUD de proyectos: la superficie REST

URL base para la gestión de proyectos:

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

Estas son llamadas REST simples. No JSON-RPC.

POST /api/agency/projects: crear un proyecto

Crea un nuevo proyecto propiedad del usuario de la clave maestra. Por defecto, el proyecto comienza como una prueba de 10 días. Pasa agencyplan para iniciarlo en un plan de pago en su lugar, con un período de facturación de 33 días.

CampoTipoRequeridoDescripción
namestringsíNombre del proyecto que se muestra en el panel de control.
urlstringnoLa URL del sitio que el proyecto rastrea.
agencyplanstringnoID del plan (por ejemplo, starter). Cuando se establece, el proyecto comienza en el plan de pago correspondiente en lugar de una prueba.
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"
  }'

La respuesta en caso de éxito es 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" }
  }
}

El _id es lo que pones en el fragmento de seguimiento en el sitio del cliente. También es el project_id que pasas a las herramientas de datos a continuación.

GET /api/agency/projects: enumerar proyectos

Devuelve los proyectos que posee tu usuario, ordenados por fecha de creación (los más recientes primero). Paginado con limit (máximo 500, predeterminado 100) y 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: obtener un proyecto

Devuelve un solo documento de proyecto. Devuelve 404 si tu usuario no es el propietario del proyecto. Deliberadamente no diferenciamos "no encontrado" de "no es tuyo" para que los ID de los proyectos no se puedan enumerar entre cuentas.

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

PATCH /api/agency/projects/:id: actualizar nombre o URL

Actualiza el name y/o la url. Ambos campos son opcionales. Los campos omitidos se dejan como estaban. Cualquier otra cosa en el cuerpo de la solicitud se ignora. El estado, la facturación, el vencimiento y las alertas se gestionan a través del panel de control.

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: eliminar un proyecto de forma permanente

Elimina el proyecto y todo lo que esté adjunto a él: ejecuciones de Lighthouse, datos de CrUX, alertas, snapshots y configuraciones de snapshots.

Los datos RUM en el almacén de datos de respaldo no se eliminan en esta llamada. Permanecen vinculados al antiguo ID del proyecto pero quedan huérfanos. No hay una vía de recuperación. El ID del proyecto se retira.

curl -X DELETE https://app.coredash.app/api/agency/projects/655f1f77bcf86cd799439011 \
  -H "Authorization: Bearer cdk_master_YOUR_MASTER_KEY"
{ "status": 200, "deleted": true }

Leer datos con una clave maestra

Para extraer datos de Core Web Vitals de uno de tus proyectos, accede al mismo endpoint JSON-RPC que utiliza la API por proyecto:

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

Las tres herramientas se mantienen sin cambios: get_metrics, get_timeseries, get_histogram. La única diferencia en comparación con el flujo por proyecto es que pasas project_id en arguments para que la llamada sepa qué proyecto consultar. Las claves de proyecto no necesitan esto porque cada clave de proyecto ya está delimitada a un proyecto en específico. Las claves maestras cubren muchos proyectos, por lo que la solicitud debe nombrar uno.

Ejemplo: get_metrics para un proyecto 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"
      }
    }
  }'

La respuesta es el mismo envoltorio JSON-RPC que la API por proyecto, con el payload analizado en result.content[0].text. La forma del JSON interno, el objeto distribution, el campo summary en las series temporales, la estructura de los buckets en los histogramas, todo se comporta de la misma manera que con una clave de proyecto. El único requisito adicional es el argumento project_id.

Lo mismo se aplica a get_timeseries y get_histogram. Pasa project_id, y luego los argumentos habituales.

Todos los demás parámetros funcionan de la misma manera: filters, group, percentile, date, granularity, y así sucesivamente. La referencia de dimensiones (d, cc, ff, lcpel, inpel, todas ellas), los umbrales de las métricas y la semántica de los percentiles están documentados en la página de CoreDash API. Lee esa sección para conocer toda la superficie de parámetros y dimensiones. Esta página solo cubre lo que es diferente cuando te autenticas con una clave maestra.

Incorporación de un nuevo proyecto de cliente

El flujo típico para una agencia que añade un nuevo cliente:

  1. Acuña una clave maestra una vez en My Account → pestaña Agency API y guárdala de forma segura.
  2. Haz un POST /api/agency/projects con el nombre y la URL del cliente. La respuesta contiene el nuevo _id.
  3. Incrusta el fragmento de seguimiento en el sitio del cliente con ese _id.
  4. Lee los datos RUM de ese proyecto en cualquier momento mediante POST /api/mcp con la misma clave maestra y "project_id": "<el _id>" en los argumentos. No se necesita una clave de proyecto por separado.

Ese es todo el ciclo de incorporación. Una clave, un POST, una incrustación de fragmento, y ya puedes consultar datos del nuevo proyecto.

Errores

Los endpoints CRUD de proyectos devuelven códigos de estado REST simples:

EstadoSignificado
400Falta un campo obligatorio en la creación, o el ID del plan es desconocido.
401Falta la clave maestra, es incorrecta o ha sido revocada.
404Proyecto no encontrado, o no es propiedad de tu usuario.
500Error en la base de datos.

Las lecturas de datos en /api/mcp devuelven objetos de error JSON-RPC, igual que con una clave de proyecto. La tabla de códigos de error se encuentra en la página de CoreDash API. Si obtienes -32001, comprueba que tu clave empiece por cdk_master_ y que hayas incluido project_id en los argumentos.

Límites de tasa

Los límites diarios por proyecto se siguen aplicando cuando lees datos: una clave maestra que llama a get_metrics para el proyecto A se descuenta de la cuota diaria del proyecto A, y una llamada para el proyecto B se descuenta de la del proyecto B. Consulta la tabla de límites de tasa en la página de CoreDash API. Las llamadas CRUD de proyectos no tienen límite de tasa de la misma manera.


CoreDash Agency API: Gestiona proyectos y extrae datos de varias cuentasCore Web Vitals CoreDash Agency API: Gestiona proyectos y extrae datos de varias cuentas