CoreDash Agency API: Zarządzaj projektami i pobieraj dane między kontami

Jeden klucz dla każdego projektu na Twoim koncie

Agency API jest przeznaczone dla kont zarządzających wieloma projektami. Agencje, wewnętrzne zespoły prowadzące kilkanaście marek i każdy, kto nie chce logować się do panelu kontrolnego (dashboard) za każdym razem, gdy pojawia się nowy klient. Wygeneruj klucz główny jeden raz, a następnie twórz, aktualizuj i usuwaj projekty oraz odczytuj dane Core Web Vitals dla nich wszystkich za pomocą jednych poświadczeń.

Szukasz API dla pojedynczego projektu? Strona CoreDash API opisuje API dla jednego projektu z kluczem o ograniczonym zakresie. Te same narzędzia danych, węższy zakres, prostsza konfiguracja.

Agency API realizuje dwie funkcje:

1. CRUD projektów: niewielki interfejs REST pod adresem /api/agency/projects do tworzenia, wyświetlania listy, aktualizacji i usuwania projektów.
2. Odczyty danych między projektami: te same narzędzia JSON-RPC co w przypadku API dla pojedynczego projektu (get_metrics, get_timeseries, get_histogram) pod adresem /api/mcp. Z kluczem głównym 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 główne są dostępne tylko dla kont oznaczonych jako agencja. Jeśli nie widzisz zakładki Agency API opisanej poniżej, skontaktuj się z pomocą techniczną.

Uzyskaj klucz główny

Klucze główne generuje się w interfejsie przeglądarkowym (web UI), a nie z poziomu 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ść. Będzie pokazana tylko raz.

Klucze zaczynają się od cdk_master_. Pozwalają one posiadaczowi na zarządzanie każdym projektem przypisanym do Twojego konta użytkownika oraz odczyt danych dla każdego z nich. Traktuj je jak hasła. Każdy klucz główny można unieważnić w tej samej zakładce.

Uwierzytelnianie

Każde żądanie do Agency API wymaga klucza głównego 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 projektów REST, jak i punktu końcowego danych JSON-RPC. Poza tym nic się nie zmienia.

CRUD projektów: interfejs REST

Bazowy URL (Base 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, którego właścicielem jest użytkownik klucza głównego. Domyślnie projekt startuje jako 10-dniowy okres próbny (trial). Przekaż agencyplan, aby zamiast tego uruchomić go na płatnym planie 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 jest tym, co umieszczasz w kodzie śledzącym (tracking snippet) na stronie klienta. Jest to również project_id przekazywany do narzędzi analitycznych poniżej.

GET /api/agency/projects: wylistuj projekty

Zwraca projekty, których właścicielem jest Twój użytkownik, posortowane według daty utworzenia (od najnowszych). Paginacja za pomocą limit (maksymalnie 500, domyślnie 100) oraz 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 pojedynczy projekt

Zwraca pojedynczy dokument projektu. Zwraca błąd 404, jeśli użytkownik nie jest właścicielem tego projektu. Celowo nie rozróżniamy komunikatów „nie znaleziono” i „to nie Twoje”, aby identyfikatory projektów nie mogły być listowane pomiędzy kontami.

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 parametry name i/lub url. Oba pola są opcjonalne. Pominięte pola pozostają bez zmian. Wszystkie inne parametry w ciele żądania (body) są ignorowane. Status, rozliczenia, data ważności i alerty są zarządzane z poziomu panelu.

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 oraz wszystko, co jest z nim powiązane: uruchomienia Lighthouse, dane CrUX, alerty, migawki (snapshots) oraz konfiguracje migawek.

Dane RUM w docelowym magazynie danych nie są usuwane podczas tego wywołania. Pozostają przypisane do starego identyfikatora projektu, ale stają się osierocone (orphaned). Nie ma ścieżki ich odzyskiwania. 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 głównego

Aby pobrać dane Core Web Vitals dla jednego ze swoich projektów, uderz w ten sam punkt końcowy JSON-RPC, którego używa API przypisane do konkretnego projektu (per-project API):

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

Te trzy narzędzia pozostają bez zmian: get_metrics, get_timeseries, get_histogram. Jedyną różnicą w stosunku do przepływu danych per-project jest to, że musisz przekazać project_id w parametrze arguments, aby wywołanie wiedziało, którego projektu ma dotyczyć. Klucze projektu tego nie wymagają, ponieważ każdy klucz projektu jest już ograniczony do jednego konkretnego projektu. Klucze główne obejmują wiele projektów, więc żądanie musi wskazywać konkretny z nich.

Przykład: get_metrics dla konkretnego 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"
      }
    }
  }'

Odpowiedzią jest to samo opakowanie (wrapper) JSON-RPC, co w przypadku API dla pojedynczego projektu, ze sparsowanym payloadem w result.content[0].text. Kształt wewnętrznego obiektu JSON, obiekt distribution, pole summary na osiach czasu (timeseries), struktura przedziałów (bucket) w histogramach – wszystkie zachowują się tak samo jak przy użyciu klucza projektu. Jedynym dodatkowym wymogiem jest argument project_id.

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

Wszystkie inne parametry działają w ten sam sposób: filters, group, percentile, date, granularity i tak dalej. Referencje wymiarów (d, cc, ff, lcpel, inpel, czyli wszystkie), progi wskaźników i semantyka percentyli są w pełni opisane na stronie CoreDash API. Zapoznaj się z tym dokumentem, aby poznać pełną gamę parametrów i wymiarów. Ta strona obejmuje wyłącznie to, co różni się podczas uwierzytelniania za pomocą klucza głównego.

Onboarding projektu nowego klienta

Typowy proces dodawania nowego klienta przez agencję wygląda następująco:

1. Wygeneruj raz klucz główny w sekcji My Account → Agency API i przechowuj go bezpiecznie.
2. Wykonaj POST /api/agency/projects podając nazwę oraz URL klienta. Odpowiedź zawiera nowe _id.
3. Zagnieźdź kod śledzący (tracking snippet) na stronie klienta z tym _id.
4. Odczytuj dane RUM dla tego projektu w dowolnym momencie używając POST /api/mcp wraz z tym samym kluczem głównym i podając w argumentach "project_id": "<the _id>". Osobny klucz projektu nie jest wymagany.

Na tym polega cały cykl wdrożeniowy (onboarding). Jeden klucz, jeden POST, jedno zagnieżdżenie skryptu – a Ty możesz od razu zapytywać o dane z nowego projektu.

Błędy (Errors)

Punkty końcowe operacji CRUD projektów zwracają standardowe kody statusu REST:

Odczyty danych w punkcie końcowym /api/mcp zwracają obiekty błędów JSON-RPC, identycznie jak w przypadku klucza projektu. Tabela kodów błędów znajduje się na stronie CoreDash API. Jeżeli otrzymasz błąd -32001, upewnij się, że Twój klucz zaczyna się od cdk_master_ i czy umieściłeś project_id w argumentach.

Limity zapytań (Rate limits)

Dzienne limity poszczególnych projektów mają nadal zastosowanie podczas odczytu danych: użycie klucza głównego do wywołania get_metrics dla projektu A zużywa dzienny limit przydzielony dla projektu A, a wywołanie dla projektu B wlicza się do limitu dla projektu B. Zobacz tabelę limitów zapytań na stronie CoreDash API. Wywołania CRUD projektów nie są limitowane w ten sam sposób.