API Agence CoreDash : Gérez les projets et extrayez les données sur plusieurs comptes

Une clé pour chaque projet sur votre compte

L'API Agence est destinée aux comptes qui gèrent de nombreux projets. Les agences, les équipes internes gérant une douzaine de marques, ou toute personne ne souhaitant pas se connecter au tableau de bord chaque fois qu'un nouveau client arrive. Générez une clé principale une fois, puis créez des projets, mettez-les à jour, supprimez-les et lisez les données Core Web Vitals sur l'ensemble de ces projets avec cet identifiant unique.

Vous recherchez plutôt l'API par projet ? La page de l'API CoreDash couvre un seul projet avec une clé étendue au projet. Mêmes outils de données, portée plus étroite, configuration plus simple.

L'API Agence fait deux choses :

1. CRUD de projet : une petite surface REST à /api/agency/projects pour créer, lister, mettre à jour et supprimer des projets.
2. Lectures de données inter-projets : les mêmes outils JSON-RPC que l'API par projet (get_metrics, get_timeseries, get_histogram) à /api/mcp. Avec une clé principale, vous passez project_id dans les arguments pour choisir le projet que vous souhaitez.

Deux types de clés API

CoreDash émet deux niveaux de clés. Chacun a un rôle différent.

Les clés principales ne sont disponibles que sur les comptes signalés comme agence. Si vous ne voyez pas l'onglet API Agence décrit ci-dessous, contactez le support.

Obtenir une clé principale

Les clés principales sont générées à partir de l'interface utilisateur web, et non depuis l'API.

1. Connectez-vous sur app.coredash.app.
2. Ouvrez Mon compte et cliquez sur l'onglet API Agence.
3. Cliquez sur Générer une clé principale, donnez-lui un nom et copiez la valeur. Elle n'est affichée qu'une seule fois.

Les clés commencent par cdk_master_. Elles permettent au titulaire de gérer chaque projet appartenant à votre compte utilisateur, et de lire les données de n'importe lequel d'entre eux. Traitez-les comme des mots de passe. Vous pouvez révoquer n'importe quelle clé principale depuis le même onglet.

Authentification

Chaque requête de l'API Agence nécessite une clé principale dans l'en-tête Authorization :

Authorization: Bearer cdk_master_YOUR_MASTER_KEY

Le même en-tête fonctionne à la fois pour les points de terminaison CRUD de projet REST et pour le point de terminaison de données JSON-RPC. Rien d'autre ne change.

CRUD de projet : la surface REST

URL de base pour la gestion de projet :

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

Ce sont de simples appels REST. Pas du JSON-RPC.

POST /api/agency/projects : créer un projet

Crée un nouveau projet appartenant à l'utilisateur de la clé principale. Par défaut, le projet commence comme un essai de 10 jours. Passez agencyplan pour le démarrer sur un plan payant à la place, avec une période de facturation de 33 jours.

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 réponse en cas de succès est 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" }
  }
}

Le _id est ce que vous placez dans l'extrait de suivi sur le site du client. C'est également le project_id que vous passez aux outils de données ci-dessous.

GET /api/agency/projects : lister les projets

Renvoie les projets que possède votre utilisateur, triés par date de création (les plus récents en premier). Paginé avec limit (max 500, défaut 100) et 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 : récupérer un projet

Renvoie un seul document de projet. Renvoie 404 si votre utilisateur ne possède pas le projet. Nous ne différencions délibérément pas "non trouvé" de "pas à vous" afin que les ID de projet ne puissent pas être énumérés d'un compte à l'autre.

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

PATCH /api/agency/projects/:id : mettre à jour le nom ou l'URL

Met à jour name et/ou url. Les deux champs sont facultatifs. Les champs omis sont laissés tels quels. Tout ce qui se trouve ailleurs dans le corps de la requête est ignoré. Le statut, la facturation, l'expiration et les alertes sont gérés via le tableau de bord.

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 : supprimer définitivement un projet

Supprime le projet et tout ce qui y est rattaché : les exécutions Lighthouse, les données CrUX, les alertes, les instantanés et les configurations d'instantanés.

Les données RUM dans le magasin de données sous-jacent ne sont pas supprimées lors de cet appel. Elles restent liées à l'ancien ID de projet mais deviennent orphelines. Il n'y a pas de chemin de récupération. L'ID de projet est retiré.

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

{ "status": 200, "deleted": true }

Lecture de données avec une clé principale

Pour extraire les données Core Web Vitals de l'un de vos projets, accédez au même point de terminaison JSON-RPC que celui utilisé par l'API par projet :

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

Les trois outils restent inchangés : get_metrics, get_timeseries, get_histogram. La seule différence par rapport au flux par projet est que vous passez project_id dans arguments pour que l'appel sache quel projet examiner. Les clés de projet n'en ont pas besoin car chaque clé de projet a déjà une portée limitée à un seul projet. Les clés principales couvrent de nombreux projets, la requête doit donc en désigner un.

Exemple : get_metrics pour un projet spécifique

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 réponse est la même enveloppe JSON-RPC que pour l'API par projet, avec le payload analysé dans result.content[0].text. La forme du JSON interne, l'objet distribution, le champ summary sur les séries chronologiques, la structure des compartiments sur les histogrammes, tout se comporte de la même manière qu'avec une clé de projet. La seule exigence supplémentaire est l'argument project_id.

Il en va de même pour get_timeseries et get_histogram. Passez project_id, puis les arguments habituels.

Tous les autres paramètres fonctionnent de la même manière : filters, group, percentile, date, granularity, etc. La référence des dimensions (d, cc, ff, lcpel, inpel, toutes celles-ci), les seuils de métriques et la sémantique des centiles sont tous documentés sur la page de l'API CoreDash. Lisez cela pour obtenir la surface complète des paramètres et des dimensions. Cette page ne couvre que ce qui est différent lorsque vous vous authentifiez avec une clé principale.

Intégration d'un nouveau projet client

Le flux typique pour une agence ajoutant un nouveau client :

1. Générez une clé principale une fois dans Mon compte → onglet API Agence et stockez-la en toute sécurité.
2. POST /api/agency/projects avec le nom et l'URL du client. La réponse contient le nouveau _id.
3. Intégrez l'extrait de suivi sur le site du client avec ce _id.
4. Lisez les données RUM pour ce projet à tout moment via POST /api/mcp avec la même clé principale et "project_id": "<the _id>" dans les arguments. Aucune clé de projet distincte n'est nécessaire.

C'est toute la boucle d'intégration. Une clé, un POST, une intégration d'extrait, et vous pouvez déjà interroger des données pour le nouveau projet.

Erreurs

Les points de terminaison CRUD de projet renvoient des codes d'état REST simples :

Les lectures de données à /api/mcp renvoient des objets d'erreur JSON-RPC, comme avec une clé de projet. Le tableau des codes d'erreur se trouve sur la page de l'API CoreDash. Si vous obtenez -32001, vérifiez que votre clé commence par cdk_master_ et que vous avez inclus project_id dans les arguments.

Limites de taux

Les limites quotidiennes par projet s'appliquent toujours lorsque vous lisez des données : une clé principale appelant get_metrics pour le projet A compte dans le quota quotidien du projet A, et un appel pour le projet B compte dans celui du projet B. Consultez le tableau des limites de taux sur la page de l'API CoreDash. Les appels CRUD de projet ne sont pas limités en taux de la même manière.