CoreDash Agency API: Projekte verwalten und Daten kontoübergreifend abrufen

Ein Key für jedes Projekt in Ihrem Konto

Die Agency API ist für Konten gedacht, die viele Projekte verwalten. Agenturen, Inhouse-Teams, die ein Dutzend Marken betreuen, oder jeder, der sich nicht jedes Mal ins Dashboard einloggen möchte, wenn ein neuer Kunde hinzukommt. Erstellen Sie einmalig einen Master Key und nutzen Sie diesen, um Projekte zu erstellen, zu aktualisieren, zu löschen und Core Web Vitals-Daten über alle hinweg mit diesen einen Zugangsdaten auszulesen.

Suchen Sie stattdessen nach der pro-Projekt-API? Die CoreDash API-Seite behandelt ein einzelnes Projekt mit einem projektbezogenen Key. Gleiche Daten-Tools, engerer Geltungsbereich, einfachere Einrichtung.

Die Agency API erledigt zwei Dinge:

1. Projekt-CRUD: eine kleine REST-Schnittstelle unter /api/agency/projects zum Erstellen, Auflisten, Aktualisieren und Löschen von Projekten.
2. Projektübergreifende Datenabrufe: dieselben JSON-RPC-Tools wie bei der pro-Projekt-API (get_metrics, get_timeseries, get_histogram) unter /api/mcp. Mit einem Master Key übergeben Sie project_id in den Argumenten, um das gewünschte Projekt auszuwählen.

Zwei Arten von API-Keys

CoreDash stellt zwei Key-Stufen aus. Jede hat eine andere Aufgabe.

Master Keys sind nur auf Konten mit Agency-Markierung verfügbar. Wenn Sie den unten beschriebenen Tab "Agency API" nicht sehen, wenden Sie sich an den Support.

Einen Master Key erhalten

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

1. Loggen Sie sich unter app.coredash.app ein.
2. Öffnen Sie My Account und klicken Sie auf den Tab Agency API.
3. Klicken Sie auf Generate master key, vergeben Sie einen Namen und kopieren Sie den Wert. Er wird nur einmal angezeigt.

Keys beginnen mit cdk_master_. Sie ermöglichen es dem Inhaber, jedes Projekt zu verwalten, das zu Ihrem Benutzerkonto gehört, und Daten für alle davon zu lesen. Behandeln Sie sie wie Passwörter. Sie können jeden Master Key über denselben Tab widerrufen.

Authentifizierung

Jede Agency API-Anfrage 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. Nichts anderes ändert sich.

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: ein Projekt erstellen

Erstellt ein neues Projekt, das dem Benutzer des Master Keys gehört. Standardmäßig startet das Projekt als 10-tägige Testversion. Übergeben Sie agencyplan, um es stattdessen mit einem kostenpflichtigen Plan mit einem 33-tägigen Abrechnungszeitraum zu starten.

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 ist das, was Sie in das Tracking-Snippet auf der Website des Kunden einfügen. Es ist auch die project_id, die Sie an die untenstehenden Daten-Tools übergeben.

GET /api/agency/projects: Projekte auflisten

Gibt die Projekte zurück, die Ihrem Benutzer gehören, sortiert nach Erstellungsdatum (neueste zuerst). Paginierung mit limit (max. 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: ein Projekt abrufen

Gibt ein einzelnes Projekt-Dokument zurück. Gibt 404 zurück, wenn Ihr Benutzer nicht Eigentümer des Projekts ist. Wir unterscheiden absichtlich nicht zwischen "nicht gefunden" und "gehört nicht Ihnen", damit Projekt-IDs nicht über Konten hinweg aufgezählt (enumeriert) 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. Weggelassene Felder bleiben unverändert. Alles andere im Body wird ignoriert. Status, Abrechnung, Ablaufdatum und Benachrichtigungen 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: ein Projekt endgültig löschen

Löscht das Projekt und alles, was damit verbunden ist: Lighthouse-Durchläufe, CrUX-Daten, Alerts, Snapshots und Snapshot-Konfigurationen.

RUM-Daten im zugrundeliegenden Datenspeicher werden bei diesem Aufruf nicht gelöscht. Sie bleiben an die alte Projekt-ID gebunden, werden jedoch verwaist. Es gibt keinen Wiederherstellungsweg. Die Projekt-ID wird ausgemustert.

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 lesen

Um Core Web Vitals-Daten für eines Ihrer Projekte abzurufen, rufen Sie denselben JSON-RPC-Endpunkt auf, den die pro-Projekt-API verwendet:

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

Die drei Tools bleiben unverändert: get_metrics, get_timeseries, get_histogram. Der einzige Unterschied im Vergleich zum pro-Projekt-Ablauf besteht darin, dass Sie project_id in arguments übergeben, damit der Aufruf weiß, welches Projekt betrachtet werden soll. Projekt-Keys benötigen dies nicht, da jeder Projekt-Key bereits auf ein Projekt beschränkt ist. Master Keys decken viele Projekte ab, daher muss in der Anfrage eines benannt werden.

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 pro-Projekt-API, mit der geparsten Payload in result.content[0].text. Die Form des inneren JSON, das distribution-Objekt, das summary-Feld bei Zeitreihen, die Bucket-Struktur bei Histogrammen, all das verhält sich genauso wie bei einem Projekt-Key. Die einzige zusätzliche Anforderung ist das Argument project_id.

Gleiches gilt für get_timeseries und get_histogram. Übergeben Sie project_id und dann die üblichen Argumente.

Alle anderen Parameter funktionieren auf dieselbe Weise: filters, group, percentile, date, granularity und so weiter. Die Dimensionsreferenz (d, cc, ff, lcpel, inpel, alle davon), die Metrik-Grenzwerte und die Perzentil-Semantik sind alle auf der CoreDash API-Seite dokumentiert. Lesen Sie dort, um den vollständigen Umfang der Parameter und Dimensionen zu erfahren. Diese Seite behandelt nur das, was anders ist, wenn Sie sich mit einem Master Key authentifizieren.

Onboarding eines neuen Kundenprojekts

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

1. Generieren Sie einmalig einen Master Key unter My Account → Agency API Tab und bewahren Sie ihn sicher auf.
2. POST /api/agency/projects mit dem Namen und der URL des Kunden. Die Antwort enthält die neue _id.
3. Binden Sie das Tracking-Snippet auf der Website des Kunden mit dieser _id ein.
4. Lesen Sie RUM-Daten für dieses Projekt jederzeit über POST /api/mcp mit demselben Master Key und "project_id": "<die _id>" in den Argumenten. Es wird kein separater Projekt-Key benötigt.

Das ist die gesamte Onboarding-Schleife. Ein Key, ein POST, eine Snippet-Einbindung, und schon können Sie Daten für das neue Projekt abfragen.

Fehler

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

Datenabrufe unter /api/mcp geben JSON-RPC-Fehlerobjekte zurück, genau wie bei einem Projekt-Key. Die Fehlercode-Tabelle befindet sich auf der CoreDash API-Seite. Wenn Sie -32001 erhalten, überprüfen Sie, ob Ihr Key mit cdk_master_ beginnt und ob Sie project_id in den Argumenten eingefügt haben.

Rate Limits

Tägliche Limits pro Projekt gelten weiterhin, wenn Sie Daten lesen: Ein Master Key, der get_metrics für Projekt A aufruft, wird auf das tägliche Kontingent von Projekt A angerechnet, und ein Aufruf für Projekt B auf das von Projekt B. Siehe die Tabelle der Rate Limits auf der CoreDash API-Seite. Projekt-CRUD-Aufrufe sind nicht auf dieselbe Weise rate-limitiert.