API de Agencia de CoreDash: Gestiona Proyectos y Extrae Datos entre Cuentas

Gestiona múltiples proyectos desde una sola cuenta. Genera una clave maestra una vez, crea y elimina proyectos mediante REST, y extrae datos de Core Web Vitals en 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

comparewhowhatwearkpnperionmy work featured on web.devnina careebaynestlehappyhorizonloopearplugsfotocasasaturnerasmusmcdpg mediaadevintamonarchworkivamarktplaatsvpnsnvharvardaleteia

Una clave para cada proyecto en tu cuenta

La API de Agencia es para cuentas que gestionan muchos proyectos. Agencias, equipos internos que manejan docenas de marcas, o cualquiera que no quiera iniciar sesión en el panel cada vez que se incorpora un nuevo cliente. Genera 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 la API de CoreDash cubre un solo proyecto con una clave de ámbito de proyecto. Las mismas herramientas de datos, un alcance más reducido, una configuración más sencilla.

La API de Agencia hace dos cosas:

  1. CRUD de Proyectos: una pequeña superficie REST en /api/agency/projects para crear, listar, 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 deseas.

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 de RUM para ese proyecto a través del endpoint JSON-RPC. Ver /api.
Clave maestracdk_master_Todos los proyectos en la cuentaCrea, lista, actualiza y elimina proyectos mediante REST. También lee datos para cualquier proyecto en la cuenta pasando el project_id en las herramientas de datos.

Las claves maestras solo están disponibles en cuentas marcadas como agencias. Si no ves la pestaña de la API de Agencia descrita a continuación, habla con soporte.

Obtener una clave maestra

Las claves maestras se generan desde la interfaz 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, ponle un nombre y copia el valor. Solo se muestra una vez.

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

Autenticación

Cada petición a la API de Agencia necesita una clave maestra en el encabezado Authorization:

Authorization: Bearer cdk_master_YOUR_MASTER_KEY

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

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 mostrado en el panel.
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 colocas en el fragmento de seguimiento del sitio del cliente. También es el project_id que pasas a las herramientas de datos a continuación.

GET /api/agency/projects: listar proyectos

Devuelve los proyectos que posee tu usuario, ordenados por fecha de creación (los más nuevos 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: recuperar un proyecto

Devuelve un solo documento de proyecto. Retorna 404 si tu usuario no es propietario del proyecto. Deliberadamente no diferenciamos "no encontrado" de "no es tuyo" para que los ID de los proyectos no puedan ser enumerados 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 mantienen tal y como estaban. Cualquier otra cosa en el cuerpo se ignora. El estado, la facturación, la expiración y las alertas se gestionan a través del panel.

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 definitivamente un proyecto

Elimina el proyecto y todo lo asociado a él: ejecuciones de Lighthouse, datos de CrUX, alertas, instantáneas, y configuraciones de instantáneas.

Los datos de 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 forma de recuperarlos. 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 }

Lectura de datos con una clave maestra

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

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

Las tres herramientas no cambian: get_metrics, get_timeseries, get_histogram. La única diferencia con respecto al flujo por proyecto es que pasas project_id en los arguments para que la llamada sepa a qué proyecto debe mirar. Las claves de proyecto no necesitan esto porque cada clave de proyecto ya tiene el ámbito de un solo proyecto. Las claves maestras cubren muchos proyectos, por lo que la petición 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 el de 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 el project_id, seguido de los argumentos habituales.

Todos los demás parámetros funcionan de la misma manera: filters, group, percentile, date, granularity, y demás. 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 la API de CoreDash. Léela para conocer la superficie completa 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. Genera 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 de RUM para ese proyecto en cualquier momento mediante un 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, la incrustación de un fragmento, y ya puedes consultar datos para el nuevo proyecto.

Errores

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

EstadoSignificado
400Falta un campo requerido al crear, 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 la API de CoreDash. Si recibes un -32001, verifica que tu clave comience con 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 cuenta contra la cuota diaria del proyecto A, y una llamada para el proyecto B cuenta contra la del proyecto B. Consulta la tabla de límites de tasa en la página de la API de CoreDash. Las llamadas al CRUD de proyectos no tienen los mismos límites de tasa.


API de Agencia de CoreDash: Gestiona Proyectos y Extrae Datos entre CuentasCore Web Vitals API de Agencia de CoreDash: Gestiona Proyectos y Extrae Datos entre Cuentas