API Agency CoreDash : gérez vos projets et extrayez des données multi-comptes

Une seule clé pour tous les projets de votre compte

L'API Agency s'adresse aux comptes qui gèrent de nombreux projets. Agences, équipes internes gérant une douzaine de marques, ou toute personne souhaitant éviter de se connecter au tableau de bord à chaque nouveau client. Générez une clé master une seule fois, puis créez, modifiez, supprimez des projets et lisez leurs données Core Web Vitals avec cet unique identifiant.

Vous cherchez plutôt l'API par projet ? La page de l'CoreDash API détaille la gestion d'un projet unique avec une clé limitée à ce projet. Mêmes outils de données, portée plus étroite, configuration plus simple.

L'API Agency permet deux choses :

1. CRUD de projet : une interface REST simplifiée sur /api/agency/projects pour créer, lister, modifier et supprimer des projets.
2. Lecture de données multi-projets : les mêmes outils JSON-RPC que l'API par projet (get_metrics, get_timeseries, get_histogram) sur /api/mcp. Avec une clé master, passez project_id dans les arguments pour cibler le projet de votre choix.

Deux types de clés API

CoreDash propose deux niveaux de clés. Chacun a un rôle bien distinct.

Les clés master sont uniquement disponibles pour les comptes configurés en mode agence. Si vous ne voyez pas l'onglet API Agency décrit ci-dessous, contactez le support.

Obtenir une clé master

Les clés master sont générées depuis l'interface web, pas via l'API.

1. Connectez-vous sur app.coredash.app.
2. Ouvrez Mon compte et cliquez sur l'onglet API Agency.
3. Cliquez sur Générer une clé master, nommez-la et copiez sa valeur. Elle ne s'affiche qu'une seule fois.

Les clés commencent par cdk_master_. Elles permettent de gérer tous les projets associés à votre compte utilisateur et de lire leurs données. Traitez-les comme des mots de passe. Vous pouvez révoquer n'importe quelle clé master depuis ce même onglet.

Authentification

Chaque requête adressée à l'API Agency requiert une clé master dans l'en-tête Authorization :

Authorization: Bearer cdk_master_YOUR_MASTER_KEY

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

CRUD de projet : l'interface REST

URL de base pour la gestion des projets :

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

Il s'agit de simples appels REST, pas de JSON-RPC.

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

Crée un projet appartenant à l'utilisateur de la clé master. Par défaut, le projet démarre avec une période d'essai de 10 jours. Transmettez agencyplan pour le démarrer directement avec un forfait payant, 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" }
  }
}

L'_id correspond à la valeur à intégrer dans le script de suivi sur le site du client. C'est également le project_id à transmettre aux outils de données ci-dessous.

GET /api/agency/projects : lister les projets

Retourne les projets appartenant à votre utilisateur, triés par date de création (les plus récents en premier). La pagination s'effectue via limit (maximum 500, valeur par 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

Retourne le document d'un projet unique. Renvoie une erreur 404 si l'utilisateur ne possède pas le projet. Nous ne faisons volontairement aucune différence entre « introuvable » et « ne vous appartient pas » afin d'éviter l'énumération des identifiants de projet entre les comptes.

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

PATCH /api/agency/projects/:id : modifier le nom ou l'URL

Modifie le name et/ou l'url. Ces deux champs sont facultatifs. Les champs omis conservent leur valeur d'origine. Tout autre élément présent dans le corps de la requête est ignoré. Le statut, la facturation, l'expiration et les alertes se gèrent depuis 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 ainsi que tous les éléments associés : analyses Lighthouse, données CrUX, alertes, snapshots et configurations de snapshot.

Les données RUM stockées dans la base de données sous-jacente ne sont pas supprimées par cet appel. Elles restent liées à l'ancien identifiant de projet mais deviennent orphelines. Aucune récupération n'est possible. L'identifiant de projet est définitivement retiré.

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

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

Lire des données avec une clé master

Pour récupérer les données Core Web Vitals de l'un de vos projets, interrogez le même point de terminaison JSON-RPC que l'API par projet :

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

Les trois outils restent inchangés : get_metrics, get_timeseries et get_histogram. La seule différence par rapport au fonctionnement par projet est que vous devez passer project_id dans les arguments pour indiquer le projet ciblé. Les clés de projet n'en ont pas besoin car chacune est déjà limitée à un seul projet. Les clés master couvrant plusieurs projets, la requête doit obligatoirement en spécifier 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 utilise la même structure JSON-RPC que l'API par projet, avec le payload analysé dans result.content[0].text. La structure du JSON interne, l'objet distribution, le champ summary sur les séries temporelles, la structure des buckets pour les histogrammes : tout fonctionne exactement comme avec une clé de projet. La seule exigence supplémentaire est l'argument project_id.

La même règle s'applique à get_timeseries et get_histogram. Passez project_id, puis les arguments habituels.

Tous les autres paramètres fonctionnent à l'identique : filters, group, percentile, date, granularity, etc. La référence des dimensions (d, cc, ff, lcpel, inpel, toutes sans exception), les seuils des métriques et la sémantique des percentiles sont documentés sur la page de l'CoreDash API. Consultez-la pour connaître l'ensemble des paramètres et des dimensions. Cette page traite uniquement des différences lors de l'authentification avec une clé master.

Intégrer le projet d'un nouveau client

Le flux classique pour ajouter un client :

1. Générez une clé master une seule fois depuis Mon compte → onglet API Agency et stockez-la de manière sécurisée.
2. Envoyez une requête POST /api/agency/projects avec le nom et l'URL du client. La réponse contient le nouvel _id.
3. Intégrez le script de suivi sur le site du client avec cet _id.
4. Lisez à tout moment les données RUM de ce projet via POST /api/mcp avec la même clé master et "project_id": "<l'_id>" dans les arguments. Pas besoin de clé de projet distincte.

C'est tout le processus d'intégration. Une seule clé, un seul POST, un script à intégrer, et vous pouvez déjà interroger les données du nouveau projet.

Erreurs

Les points de terminaison de CRUD de projet renvoient des codes de statut REST classiques :

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

Limites de requêtes

Les limites quotidiennes par projet s'appliquent toujours lors de la lecture des données : un appel à get_metrics avec une clé master pour le projet A est décompté du quota quotidien du projet A, et un appel pour le projet B est décompté de celui du projet B. Consultez le tableau des limites de requêtes sur la page de l'CoreDash API. Les appels REST de CRUD de projet ne sont pas limités de cette manière.