CoreDash Agency API: Beheer projecten en haal data op over accounts heen

Eén sleutel voor elk project op je account

De Agency API is voor accounts die veel projecten beheren. Bureaus, in-house teams die een tiental merken runnen, of iedereen die niet telkens in het dashboard wil inloggen wanneer er een nieuwe klant bij komt. Genereer eenmalig een master key, waarna je projecten kunt aanmaken, updaten, verwijderen en Core Web Vitals data over al deze projecten kunt lezen met dat ene credential.

Op zoek naar de per-project API in plaats hiervan? De CoreDash API pagina behandelt een enkel project met een project-gebonden sleutel. Dezelfde data tools, smallere scope, eenvoudigere setup.

De Agency API doet twee dingen:

1. Project CRUD: een klein REST-oppervlak op /api/agency/projects voor het aanmaken, oplijsten, updaten en verwijderen van projecten.
2. Cross-project data reads: dezelfde JSON-RPC tools als de per-project API (get_metrics, get_timeseries, get_histogram) op /api/mcp. Met een master key geef je project_id mee in de argumenten om te kiezen welk project je wilt.

Twee soorten API sleutels

CoreDash geeft twee niveaus van sleutels uit. Elk heeft een andere taak.

Master keys zijn alleen beschikbaar op accounts die gemarkeerd zijn als agency. Als je het Agency API tabblad hieronder niet ziet, neem dan contact op met support.

Verkrijg een master key

Master keys worden gegenereerd vanuit de web UI, niet via de API.

1. Log in op app.coredash.app.
2. Open My Account en klik op het Agency API tabblad.
3. Klik op Generate master key, geef het een naam en kopieer de waarde. Deze wordt eenmalig getoond.

Sleutels beginnen met cdk_master_. Ze geven de houder de mogelijkheid om elk project dat bij je gebruikersaccount hoort te beheren, en data voor al deze projecten te lezen. Behandel ze als wachtwoorden. Je kunt elke master key intrekken via hetzelfde tabblad.

Authenticatie

Elke Agency API request heeft een master key nodig in de Authorization header:

Authorization: Bearer cdk_master_YOUR_MASTER_KEY

Dezelfde header werkt voor zowel de REST project CRUD endpoints als het JSON-RPC data endpoint. Verder verandert er niets.

Project CRUD: het REST-oppervlak

Base URL voor projectbeheer:

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

Dit zijn reguliere REST calls. Geen JSON-RPC.

POST /api/agency/projects: maak een project aan

Maakt een nieuw project aan dat eigendom is van de gebruiker van de master key. Standaard start het project als een 10-daagse proefperiode. Geef agencyplan mee om het in plaats daarvan op een betaald plan te starten, met een factureringsperiode van 33 dagen.

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"
  }'

Response bij succes is 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" }
  }
}

De _id is wat je in de tracking snippet op de site van de klant plaatst. Het is ook de project_id die je meegeeft aan de data tools hieronder.

GET /api/agency/projects: toon projecten

Retourneert de projecten waarvan je gebruiker de eigenaar is, gesorteerd op aanmaakdatum (nieuwste eerst). Gepagineerd met limit (max 500, standaard 100) en 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: haal één project op

Retourneert een enkel projectdocument. Retourneert 404 als je gebruiker het project niet bezit. We maken bewust geen onderscheid tussen "niet gevonden" en "niet van jou", zodat project-ID's niet over accounts heen geënumereerd kunnen worden.

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

PATCH /api/agency/projects/:id: update naam of URL

Updatet name en/of url. Beide velden zijn optioneel. Weggelaten velden blijven zoals ze waren. Alles wat verder in de body staat, wordt genegeerd. Status, facturering, verloopdatum en alerts worden beheerd via het 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: hard-delete een project

Verwijdert het project en alles wat eraan gekoppeld is: Lighthouse runs, CrUX data, alerts, snapshots en snapshot configs.

RUM data in de achterliggende data store wordt niet verwijderd bij deze aanroep. Deze blijft gekoppeld aan de oude project ID, maar raakt verweesd (orphaned). Er is geen herstelpad. De project ID wordt buiten gebruik gesteld.

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

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

Data lezen met een master key

Om Core Web Vitals data voor één van je projecten op te halen, benader je hetzelfde JSON-RPC endpoint dat de per-project API gebruikt:

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

De drie tools zijn ongewijzigd: get_metrics, get_timeseries, get_histogram. Het enige verschil in vergelijking met de per-project flow is dat je project_id doorgeeft in de arguments zodat de aanroep weet naar welk project er gekeken moet worden. Project keys hebben dit niet nodig omdat elke project key al is gekoppeld aan één project. Master keys dekken veel projecten, dus het verzoek moet er één benoemen.

Voorbeeld: get_metrics voor een specifiek project

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"
      }
    }
  }'

De response is dezelfde JSON-RPC wrapper als de per-project API, met de geparste payload in result.content[0].text. De vorm van de binnenste JSON, het distribution object, het summary veld op timeseries, de bucket structuur op histogrammen, gedragen zich allemaal op dezelfde manier als met een project key. De enige extra vereiste is het project_id argument.

Hetzelfde geldt voor get_timeseries en get_histogram. Geef project_id mee, gevolgd door de gebruikelijke argumenten.

Alle andere parameters werken op dezelfde manier: filters, group, percentile, date, granularity, enzovoort. De dimensiereferentie (d, cc, ff, lcpel, inpel, allemaal), de metrics drempelwaarden en de percentiel semantiek zijn allemaal gedocumenteerd op de CoreDash API pagina. Lees die voor het volledige parameter- en dimensie-oppervlak. Deze pagina behandelt alleen wat er anders is wanneer je authenticeert met een master key.

Een nieuw klantproject onboarden

De typische flow voor een agency die een nieuwe klant toevoegt:

1. Genereer eenmalig een master key bij My Account → Agency API tab en bewaar deze veilig.
2. POST /api/agency/projects met de naam en URL van de klant. De response bevat de nieuwe _id.
3. Plaats de tracking snippet op de site van de klant met die _id.
4. Lees RUM data voor dat project op elk gewenst moment via POST /api/mcp met dezelfde master key en "project_id": "<de _id>" in de argumenten. Geen aparte project key nodig.

Dat is de hele onboarding loop. Eén sleutel, één POST, één snippet implementatie, en je kunt direct data voor het nieuwe project bevragen.

Fouten

Project CRUD endpoints retourneren standaard REST statuscodes:

Data reads op /api/mcp retourneren JSON-RPC foutobjecten, hetzelfde als bij een project key. De foutcode tabel staat op de CoreDash API pagina. Als je -32001 krijgt, controleer dan dubbel of je sleutel begint met cdk_master_ en of je project_id in de argumenten hebt opgenomen.

Rate limits

Dagelijkse limieten per project zijn nog steeds van toepassing wanneer je data leest: een master key die get_metrics aanroept voor project A telt mee voor het dagelijkse quotum van project A, en een aanroep voor project B telt mee voor dat van project B. Zie de rate limits tabel op de CoreDash API pagina. Project CRUD calls worden niet op dezelfde manier gelimiteerd.