CoreDash Agency API: Hallitse projekteja ja hae dataa tilien yli

Yksi avain jokaiselle tilisi projektille

Agency API on tarkoitettu tileille, jotka hallinnoivat useita projekteja. Toimistoille, sisäisille tiimeille, jotka ylläpitävät kymmeniä brändejä, ja kaikille, jotka eivät halua kirjautua ohjauspaneeliin joka kerta, kun uusi asiakas aloittaa. Luo master-avain kerran, jonka jälkeen voit luoda projekteja, päivittää ja poistaa niitä, sekä lukea Core Web Vitals -dataa niistä kaikista samoilla tunnuksilla.

Etsitkö ennemmin projektikohtaista APIa? CoreDash API -sivu kattaa yksittäisen projektin projektikohtaisella avaimella. Samat datatyökalut, kapeampi laajuus, yksinkertaisempi asennus.

Agency API tekee kaksi asiaa:

1. Projektien CRUD: pieni REST-pinta osoitteessa /api/agency/projects projektien luomiseen, listaamiseen, päivittämiseen ja poistamiseen.
2. Projektien välinen datan luku: samat JSON-RPC-työkalut kuin projektikohtaisessa APIssa (get_metrics, get_timeseries, get_histogram) osoitteessa /api/mcp. Master-avainta käyttämällä välität project_id-arvon argumenteissa valitaksesi haluamasi projektin.

Kaksi erilaista API-avainta

CoreDash myöntää kahden tasoisia avaimia. Kummallakin on oma tehtävänsä.

Master-avaimet ovat saatavilla vain toimistoiksi (agency) merkityillä tileillä. Jos et näe alla kuvattua Agency API -välilehteä, ota yhteyttä tukeen.

Hanki master-avain

Master-avaimet luodaan verkkokäyttöliittymästä, ei APIsta.

1. Kirjaudu sisään osoitteessa app.coredash.app.
2. Avaa My Account (Oma tili) ja napsauta Agency API -välilehteä.
3. Napsauta Generate master key, anna sille nimi ja kopioi arvo. Se näytetään vain kerran.

Avaimet alkavat cdk_master_. Niiden avulla haltija voi hallinnoida jokaista käyttäjätilillesi kuuluvaa projektia ja lukea dataa mistä tahansa niistä. Käsittele niitä kuin salasanoja. Voit perua minkä tahansa master-avaimen samalta välilehdeltä.

Todennus (Authentication)

Jokainen Agency API -pyyntö tarvitsee master-avaimen Authorization-otsikkoon:

Authorization: Bearer cdk_master_YOUR_MASTER_KEY

Sama otsikko toimii sekä RESTin projektien CRUD-päätepisteille että JSON-RPC-datapäätepisteelle. Mikään muu ei muutu.

Projektien CRUD: REST-pinta

Perus-URL projektinhallinnalle:

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

Nämä ovat tavallisia REST-kutsuja. Eivät JSON-RPC:tä.

POST /api/agency/projects: luo projekti

Luo uuden projektin, jonka omistaa master-avaimen käyttäjä. Oletuksena projekti alkaa 10 päivän kokeilujaksona. Välitä agencyplan aloittaaksesi sen sen sijaan maksullisella tilauksella ja 33 päivän laskutusjaksolla.

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

Vastaus onnistuessa on 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" }
  }
}

_id on se, minkä asetat seurantakoodiin asiakkaan sivustolla. Se on myös project_id, jonka välität alla oleville datatyökaluille.

GET /api/agency/projects: listaa projektit

Palauttaa käyttäjäsi omistamat projektit lajiteltuna luomispäivän mukaan (uusin ensin). Sivutettu limit- (enintään 500, oletus 100) ja offset-arvoilla.

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: hae yksi projekti

Palauttaa yksittäisen projektidokumentin. Palauttaa 404, jos käyttäjäsi ei omista projektia. Emme tarkoituksella tee eroa virheiden "ei löydy" (not found) ja "ei sinun" (not yours) välillä, jotta projektien ID-tunnuksia ei voida luetella tilien välillä.

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

PATCH /api/agency/projects/:id: päivitä nimi tai URL

Päivittää kentän name ja/tai url. Molemmat kentät ovat valinnaisia. Pois jätetyt kentät pysyvät ennallaan. Kaikki muu rungon sisältö jätetään huomiotta. Tilaa, laskutusta, vanhenemista ja hälytyksiä hallitaan ohjauspaneelin kautta.

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: poista projekti kokonaan

Poistaa projektin ja kaiken siihen liittyvän: Lighthouse-ajot, CrUX-datan, hälytykset, tilannevedokset (snapshots) ja tilannevedoskonfiguraatiot.

Taustalla olevassa tietovarastossa olevaa RUM-dataa ei poisteta tässä kutsussa. Se pysyy linkitettynä vanhaan projektin ID:hen, mutta jää orvoksi. Palautusmahdollisuutta ei ole. Projektin ID poistetaan käytöstä.

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

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

Datan lukeminen master-avaimella

Hakeaksesi Core Web Vitals -dataa jollekin projekteistasi, kutsu samaa JSON-RPC-päätepistettä, jota projektikohtainen API käyttää:

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

Kolme työkalua pysyvät muuttumattomina: get_metrics, get_timeseries, get_histogram. Ainoa ero projektikohtaiseen kulkuun verrattuna on, että välität project_id-arvon arguments-osiossa, jotta kutsu tietää, mitä projektia tarkastella. Projektiavaimet eivät tarvitse tätä, koska jokainen projektiavain on jo rajattu yhteen projektiin. Master-avaimet kattavat useita projekteja, joten pyynnössä on nimettävä yksi.

Esimerkki: get_metrics tietylle projektille

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

Vastaus on sama JSON-RPC-kääre kuin projektikohtaisessa APIssa, ja jäsennelty hyötykuorma (payload) on kohdassa result.content[0].text. Sisäisen JSONin muoto, distribution-objekti, aikasarjojen summary-kenttä ja histogrammien lokerorakenne toimivat kaikki samalla tavalla kuin projektiavaimella. Ainoa ylimääräinen vaatimus on project_id-argumentti.

Sama koskee get_timeseries- ja get_histogram-työkaluja. Välitä project_id, sitten tavanomaiset argumentit.

Kaikki muut parametrit toimivat samalla tavalla: filters, group, percentile, date, granularity ja niin edelleen. Dimensioiden viitteet (d, cc, ff, lcpel, inpel, kaikki nämä), metriikoiden raja-arvot ja persentiilien semantiikka on kaikki dokumentoitu CoreDash API -sivulla. Lue se nähdäksesi parametrien ja dimensioiden täyden pinta-alan. Tämä sivu kattaa vain sen, mikä on erilaista, kun todennat master-avaimella.

Uuden asiakasprojektin käyttöönotto

Tyypillinen kulku toimistolle uutta asiakasta lisättäessä:

1. Luo master-avain kerran kohdassa My Account → Agency API tab (Agency API -välilehti) ja säilytä se turvallisesti.
2. Tee POST /api/agency/projects asiakkaan nimellä ja URL-osoitteella. Vastaus sisältää uuden _id-arvon.
3. Upota seurantakoodi asiakkaan sivustolle kyseisellä _id-arvolla.
4. Lue RUM-dataa kyseiselle projektille milloin tahansa osoitteesta POST /api/mcp käyttämällä samaa master-avainta ja "project_id": "<the _id>" -arvoa argumenteissa. Erillistä projektiavainta ei tarvita.

Siinä on koko käyttöönottosilmukka. Yksi avain, yksi POST, yksi koodinpätkän upotus, ja voit jo kysellä dataa uutta projektia varten.

Virheet

Projektien CRUD-päätepisteet palauttavat tavallisia REST-tilakoodeja:

Datan luvut osoitteessa /api/mcp palauttavat JSON-RPC-virheobjekteja, samoin kuin projektiavaimella. Virhekooditaulukko on CoreDash API -sivulla. Jos saat koodin -32001, tarkista vielä kerran, että avaimesi alkaa cdk_master_ ja että sisällytit project_id-arvon argumentteihin.

Kyselyrajoitukset (Rate limits)

Projektikohtaiset päivittäiset rajoitukset ovat edelleen voimassa dataa lukiessasi: kun master-avain kutsuu get_metrics projektille A, se kuluttaa projektin A päivittäistä kiintiötä, ja kutsu projektille B kuluttaa projektin B kiintiötä. Katso kyselyrajoitusten taulukko CoreDash API -sivulta. Projektien CRUD-kutsuja ei ole rajoitettu samalla tavalla.