CoreDash Agency API: Zarządzaj projektami i pobieraj dane z wielu kont

Jeden klucz do każdego projektu na Twoim koncie

Agency API jest przeznaczone dla kont, które zarządzają wieloma projektami. Agencje, wewnętrzne zespoły obsługujące kilkanaście marek, każdy, kto nie chce logować się do panelu za każdym razem, gdy pojawia się nowy klient. Wygeneruj klucz master raz, a następnie twórz projekty, aktualizuj je, usuwaj i odczytuj dane Core Web Vitals ze wszystkich z nich za pomocą tych samych poświadczeń.

Szukasz API dla pojedynczego projektu? Strona CoreDash API obejmuje pojedynczy projekt z kluczem przypisanym do tego projektu. Te same narzędzia do danych, węższy zakres, prostsza konfiguracja.

Agency API robi dwie rzeczy:

1. CRUD dla projektów: niewielki interfejs REST pod /api/agency/projects do tworzenia, wyświetlania list, aktualizowania i usuwania projektów.
2. Odczyt danych między projektami: te same narzędzia JSON-RPC co w API dla pojedynczego projektu (get_metrics, get_timeseries, get_histogram) pod /api/mcp. Mając klucz master, przekazujesz project_id w argumentach, aby wybrać odpowiedni projekt.

Dwa rodzaje kluczy API

CoreDash wydaje dwa poziomy kluczy. Każdy z nich ma inne zadanie.

Klucze master są dostępne tylko dla kont oznaczonych jako agencyjne. Jeśli nie widzisz zakładki Agency API opisanej poniżej, skontaktuj się ze wsparciem.

Zdobądź klucz master

Klucze master są generowane z poziomu interfejsu webowego, a nie przez API.

1. Zaloguj się na app.coredash.app.
2. Otwórz My Account (Moje konto) i kliknij zakładkę Agency API.
3. Kliknij Generate master key, nadaj mu nazwę i skopiuj wartość. Jest ona wyświetlana tylko raz.

Klucze zaczynają się od cdk_master_. Pozwalają one posiadaczowi zarządzać każdym projektem, który należy do Twojego konta użytkownika, oraz odczytywać dane z dowolnego z nich. Traktuj je jak hasła. Każdy klucz master możesz unieważnić z poziomu tej samej zakładki.

Uwierzytelnianie

Każde żądanie do Agency API wymaga klucza master w nagłówku Authorization:

Authorization: Bearer cdk_master_YOUR_MASTER_KEY

Ten sam nagłówek działa zarówno dla punktów końcowych CRUD dla projektów w REST, jak i dla punktu końcowego danych JSON-RPC. Nic innego się nie zmienia.

CRUD dla projektów: powierzchnia REST

Bazowy adres URL do zarządzania projektami:

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

Są to zwykłe wywołania REST. Nie JSON-RPC.

POST /api/agency/projects: utwórz projekt

Tworzy nowy projekt należący do użytkownika klucza master. Domyślnie projekt rozpoczyna się jako 10-dniowa wersja próbna. Przekaż agencyplan, aby zamiast tego rozpocząć go w ramach płatnego planu z 33-dniowym okresem rozliczeniowym.

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

Odpowiedź w przypadku sukcesu to 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" }
  }
}

Wartość _id to ta, którą umieszczasz w kodzie śledzącym na stronie klienta. Jest to również project_id, które przekazujesz do narzędzi danych poniżej.

GET /api/agency/projects: wyświetl listę projektów

Zwraca projekty należące do Twojego użytkownika, posortowane według daty utworzenia (od najnowszych). Paginowane za pomocą parametrów limit (maksymalnie 500, domyślnie 100) i 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: pobierz jeden projekt

Zwraca dokument pojedynczego projektu. Zwraca błąd 404, jeśli Twój użytkownik nie jest właścicielem projektu. Celowo nie rozróżniamy komunikatów „nie znaleziono” od „nie jest twój”, aby nie można było wyliczyć identyfikatorów projektów na różnych kontach.

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

PATCH /api/agency/projects/:id: zaktualizuj nazwę lub URL

Aktualizuje pole name i/lub url. Oba pola są opcjonalne. Pominięte pola pozostają bez zmian. Wszystko inne w treści żądania jest ignorowane. Status, rozliczenia, wygaśnięcie i alerty są zarządzane poprzez panel.

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: trwale usuń projekt

Usuwa projekt i wszystko z nim związane: przebiegi Lighthouse, dane CrUX, alerty, migawki oraz konfiguracje migawek.

Dane RUM w zapleczowej bazie danych nie są usuwane podczas tego wywołania. Pozostają przypisane do starego identyfikatora projektu, ale stają się osierocone. Nie ma możliwości ich przywrócenia. Identyfikator projektu zostaje wycofany.

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

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

Odczytywanie danych za pomocą klucza master

Aby pobrać dane Core Web Vitals dla jednego ze swoich projektów, odwołaj się do tego samego punktu końcowego JSON-RPC, z którego korzysta API dla pojedynczego projektu:

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

Trzy narzędzia pozostają bez zmian: get_metrics, get_timeseries, get_histogram. Jedyną różnicą w stosunku do przepływu na poziomie projektu jest to, że przekazujesz project_id w arguments, aby wywołanie wiedziało, na który projekt ma patrzeć. Klucze projektu tego nie potrzebują, ponieważ każdy klucz projektu jest już ograniczony do jednego projektu. Klucze master obejmują wiele projektów, więc w żądaniu musisz wskazać jeden z nich.

Przykład: get_metrics dla określonego projektu

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

Odpowiedź jest tym samym opakowaniem JSON-RPC co w API dla pojedynczego projektu, ze sparsowanym ładunkiem w result.content[0].text. Kształt wewnętrznego JSON-a, obiekt distribution, pole summary w szeregach czasowych, struktura przedziałów w histogramach zachowują się tak samo, jak w przypadku klucza projektu. Jedynym dodatkowym wymogiem jest argument project_id.

To samo dotyczy get_timeseries i get_histogram. Przekaż project_id, a następnie zwykłe argumenty.

Wszystkie inne parametry działają w ten sam sposób: filters, group, percentile, date, granularity i tak dalej. Odniesienie do wymiarów (d, cc, ff, lcpel, inpel, wszystkie z nich), progi dla metryk oraz semantyka percentyli są w całości udokumentowane na stronie CoreDash API. Przeczytaj ją, aby zapoznać się z pełną powierzchnią parametrów i wymiarów. Ta strona obejmuje tylko to, co się różni podczas uwierzytelniania za pomocą klucza master.

Wdrażanie nowego projektu klienta

Typowy przepływ dla agencji dodającej nowego klienta:

1. Wygeneruj klucz master jednorazowo w My Account → zakładka Agency API i przechowuj go w bezpieczny sposób.
2. Wykonaj POST /api/agency/projects z nazwą i adresem URL klienta. Odpowiedź zawiera nowe _id.
3. Osadź kod śledzący na stronie klienta z tym _id.
4. Odczytuj dane RUM dla tego projektu w dowolnym momencie przez POST /api/mcp z tym samym kluczem master i "project_id": "<the _id>" w argumentach. Oddzielny klucz projektu nie jest potrzebny.

To jest cała pętla wdrożeniowa. Jeden klucz, jeden POST, jedno wdrożenie kodu śledzącego, i już możesz odpytywać dane dla nowego projektu.

Błędy

Punkty końcowe CRUD dla projektów zwracają zwykłe kody statusu REST:

Odczyty danych pod adresem /api/mcp zwracają obiekty błędów JSON-RPC, tak samo jak w przypadku klucza projektu. Tabela kodów błędów znajduje się na stronie CoreDash API. Jeśli otrzymasz -32001, sprawdź dwa razy, czy Twój klucz zaczyna się od cdk_master_ i czy uwzględniłeś project_id w argumentach.

Limity zapytań (Rate limits)

Dzienne limity na projekt nadal obowiązują podczas odczytywania danych: wywołanie get_metrics przez klucz master dla projektu A obciąża dzienny limit projektu A, a wywołanie dla projektu B obciąża limit projektu B. Zobacz tabelę limitów zapytań na stronie CoreDash API. Wywołania CRUD dla projektów nie podlegają takim samym limitom zapytań.