CoreDash Agency API: Projekte verwalten und Daten über Accounts hinweg abrufen

Verwalte viele Projekte über einen einzigen Account. Generiere einmalig einen Master-Key, erstelle und lösche Projekte per REST und rufe Core Web Vitals-Daten für alle Projekte mit einem einzigen Key ab.

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

Trusted by market leaders · Client results

workivaaleteiawhowhatwearadevintaloopearplugscomparehappyhorizondpg mediaperionkpnmy work featured on web.devnina careebaysaturnmarktplaatserasmusmcharvardvpnnestlemonarchfotocasasnv

Ein Key für jedes Projekt in deinem Account

Die Agency API ist für Accounts, die viele Projekte verwalten. Agenturen, Inhouse-Teams mit einem Dutzend Marken oder alle, die sich nicht bei jedem neuen Kunden im Dashboard anmelden wollen. Generiere einmalig einen Master-Key. Danach kannst du mit diesem einen Zugangsschlüssel Projekte erstellen, aktualisieren, löschen und Core Web Vitals-Daten für alle Projekte abrufen.

Suchst du stattdessen nach der API für einzelne Projekte? Die Seite der CoreDash API beschreibt ein einzelnes Projekt mit einem projektbezogenen Key. Dieselben Daten-Tools, kleinerer Scope, einfacheres Setup.

Die Agency API erledigt zwei Aufgaben:

  1. Projekt-CRUD: Eine kleine REST-Schnittstelle unter /api/agency/projects zum Erstellen, Auflisten, Aktualisieren und Löschen von Projekten.
  2. Projektübergreifende Datenabfragen: Dieselben JSON-RPC-Tools wie bei der API für einzelne Projekte (get_metrics, get_timeseries, get_histogram) unter /api/mcp. Bei einem Master-Key übergibst du project_id in den Argumenten, um das gewünschte Projekt auszuwählen.

Zwei Arten von API-Keys

CoreDash bietet zwei Key-Stufen. Jede hat eine andere Aufgabe.

KeyPräfixScopeFunktion
Projekt-Keycdk_Ein ProjektLiest RUM-Daten für dieses Projekt über den JSON-RPC-Endpunkt. Siehe /api.
Master-Keycdk_master_Jedes Projekt im AccountErstellt, listet, aktualisiert und löscht Projekte über REST. Liest zudem Daten für jedes Projekt im Account, indem project_id in den Daten-Tools übergeben wird.

Master-Keys sind nur für Accounts mit Agency-Flag verfügbar. Wenn du den unten beschriebenen Tab „Agency API“ nicht siehst, wende dich an den Support.

Master-Key erstellen

Master-Keys werden über das Web-UI erstellt, nicht über die API.

  1. Melde dich unter app.coredash.app an.
  2. Öffne My Account und klicke auf den Tab Agency API.
  3. Klicke auf Generate master key, gib ihm einen Namen und kopiere den Wert. Er wird nur einmal angezeigt.

Keys beginnen mit cdk_master_. Sie erlauben es dem Inhaber, jedes Projekt deines Nutzerkontos zu verwalten und die Daten aller Projekte zu lesen. Behandle sie wie Passwörter. Du kannst jeden Master-Key im selben Tab widerrufen.

Authentifizierung

Jeder Request an die Agency API benötigt einen Master-Key im Authorization-Header:

Authorization: Bearer cdk_master_YOUR_MASTER_KEY

Derselbe Header funktioniert sowohl für die REST-Projekt-CRUD-Endpunkte als auch für den JSON-RPC-Datenendpunkt. Sonst ändert sich nichts.

Projekt-CRUD: die REST-Schnittstelle

Basis-URL für die Projektverwaltung:

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

Dies sind einfache REST-Aufrufe. Kein JSON-RPC.

POST /api/agency/projects: Projekt erstellen

Erstellt ein neues Projekt im Besitz des Master-Key-Nutzers. Standardmäßig startet das Projekt als 10-Tage-Testversion. Übergib agencyplan, um es stattdessen in einem kostenpflichtigen Tarif mit einem 33-tägigen Abrechnungszeitraum zu starten.

FeldTypErforderlichBeschreibung
namestringjaDer im Dashboard angezeigte Projektname.
urlstringneinDie vom Projekt überwachte Website-URL.
agencyplanstringneinTarif-ID (zum Beispiel starter). Wenn angegeben, startet das Projekt im entsprechenden kostenpflichtigen Tarif statt als Testversion.
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"
  }'

Die Antwort bei Erfolg ist 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" }
  }
}

Die _id fügst du in das Tracking-Snippet auf der Website des Kunden ein. Sie ist auch die project_id, die du unten an die Daten-Tools übergibst.

GET /api/agency/projects: Projekte auflisten

Gibt die Projekte deines Nutzers zurück, sortiert nach Erstellungsdatum (neueste zuerst). Paginierung erfolgt über limit (maximal 500, Standard 100) und 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: Einzelnes Projekt abrufen

Gibt ein einzelnes Projektdokument zurück. Liefert 404, wenn das Projekt nicht diesem Nutzer gehört. Wir unterscheiden bewusst nicht zwischen „nicht gefunden“ und „nicht deins“, damit Projekt-IDs nicht accountübergreifend ermittelt werden können.

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

PATCH /api/agency/projects/:id: Name oder URL aktualisieren

Aktualisiert name und/oder url. Beide Felder sind optional. Ausgelassene Felder bleiben unverändert. Alle anderen Angaben im Request-Body werden ignoriert. Status, Abrechnung, Ablaufdatum und Alerts werden über das Dashboard verwaltet.

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: Projekt endgültig löschen

Löscht das Projekt und alle verknüpften Daten: Lighthouse-Läufe, CrUX-Daten, Alerts, Snapshots und Snapshot-Konfigurationen.

RUM-Daten im zugrundeliegenden Datenspeicher werden durch diesen Aufruf nicht gelöscht. Sie bleiben der alten Projekt-ID zugeordnet, sind aber verwaist. Es gibt keinen Wiederherstellungsweg. Die Projekt-ID wird stillgelegt.

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

Daten mit einem Master-Key auslesen

Um Core Web Vitals-Daten für eines deiner Projekte abzurufen, sprich denselben JSON-RPC-Endpunkt an, den auch die projektbezogene API nutzt:

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

Die drei Tools sind unverändert: get_metrics, get_timeseries und get_histogram. Der einzige Unterschied zum projektbezogenen Ablauf besteht darin, dass du project_id in den arguments übergibst, damit der Aufruf weiß, welches Projekt gemeint ist. Projekt-Keys benötigen dies nicht, da jeder Projekt-Key bereits auf ein einziges Projekt beschränkt ist. Master-Keys decken viele Projekte ab. Der Request muss daher ein bestimmtes Projekt angeben.

Beispiel: get_metrics für ein bestimmtes Projekt

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

Die Antwort ist derselbe JSON-RPC-Wrapper wie bei der projektbezogenen API, wobei sich der geparste Payload in result.content[0].text befindet. Der Aufbau des inneren JSON, das distribution-Objekt, das summary-Feld bei Timeseries und die Bucket-Struktur bei Histogrammen verhalten sich genauso wie bei einem Projekt-Key. Die einzige zusätzliche Voraussetzung ist das Argument project_id.

Dasselbe gilt für get_timeseries und get_histogram. Übergib project_id und danach die üblichen Argumente.

Alle anderen Parameter funktionieren genauso: filters, group, percentile, date, granularity und so weiter. Die Dimensionsreferenz (d, cc, ff, lcpel, inpel, alle davon), die Schwellenwerte für Metriken und die Semantik der Perzentile sind auf der Seite der CoreDash API dokumentiert. Lies diese für die vollständige Parameter- und Dimensionsreferenz. Diese Seite beschreibt nur die Unterschiede bei der Authentifizierung mit einem Master-Key.

Ein neues Kundenprojekt anlegen

Der typische Ablauf für eine Agentur, die einen neuen Kunden hinzufügt:

  1. Erstelle einmalig einen Master-Key unter My Account → Tab Agency API und bewahre ihn sicher auf.
  2. Sende einen POST /api/agency/projects mit dem Namen und der URL des Kunden. Die Antwort enthält die neue _id.
  3. Füge das Tracking-Snippet mit dieser _id auf der Website des Kunden ein.
  4. Lies RUM-Daten für dieses Projekt jederzeit über POST /api/mcp mit demselben Master-Key und "project_id": "<die _id>" in den Argumenten aus. Kein separater Projekt-Key erforderlich.

Das ist der gesamte Ablauf. Ein Key, ein POST, eine Snippet-Einbindung und du kannst bereits Daten für das neue Projekt abfragen.

Fehler

Projekt-CRUD-Endpunkte geben einfache REST-Statuscodes zurück:

StatusBedeutung
400Fehlendes Pflichtfeld beim Erstellen oder unbekannte Tarif-ID.
401Fehlender, ungültiger oder widerrufener Master-Key.
404Projekt nicht gefunden oder gehört nicht deinem Nutzer.
500Datenbankfehler.

Datenabfragen unter /api/mcp geben JSON-RPC-Fehlerobjekte zurück, genau wie bei einem Projekt-Key. Die Tabelle der Fehlercodes findest du auf der Seite der CoreDash API. Wenn du den Fehler -32001 erhältst, prüfe noch einmal, ob dein Key mit cdk_master_ beginnt und ob du project_id in den Argumenten angegeben hast.

Rate-Limits

Tägliche Limits pro Projekt gelten auch beim Auslesen von Daten: Wenn ein Master-Key get_metrics für Projekt A aufruft, zählt dies gegen das tägliche Kontingent von Projekt A. Ein Aufruf für Projekt B zählt gegen das von Projekt B. Siehe die Tabelle der Rate-Limits auf der Seite der CoreDash API. Projekt-CRUD-Aufrufe unterliegen nicht denselben Limits.


CoreDash Agency API: Projekte verwalten und Daten über Accounts hinweg abrufenCore Web Vitals CoreDash Agency API: Projekte verwalten und Daten über Accounts hinweg abrufen