CoreDash Agency API: Hallitse projekteja ja hae dataa tilien yli

Yksi avain jokaiselle tilisi projektille

Agency API on tarkoitettu tileille, jotka hallitsevat useita projekteja. Toimistoille, sisäisille tiimeille, jotka pyörittävät kymmeniä brändejä, ja kaikille, jotka eivät halua kirjautua sisään hallintapaneeliin aina, kun uusi asiakas tulee mukaan. Luo master key kerran ja voit sen jälkeen luoda projekteja, päivittää niitä, poistaa niitä ja lukea Core Web Vitals -dataa niistä kaikista tällä yhdellä tunnuksella.

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

Agency API tekee kaksi asiaa:

1. Project CRUD: pieni REST-rajapinta osoitteessa /api/agency/projects projektien luomiseen, listaamiseen, päivittämiseen ja poistamiseen.
2. Projektien rajat ylittävät datahaut: samat JSON-RPC-työkalut kuin projektikohtaisessa APIssa (get_metrics, get_timeseries, get_histogram) osoitteessa /api/mcp. Master keyn avulla välität project_id-arvon argumenteissa valitaksesi haluamasi projektin.

Kaksi erilaista API-avainta

CoreDash myöntää kahden tason avaimia. Kummallakin on eri tehtävä.

Master keyt ovat saatavilla vain agency-tunnisteella varustetuilla tileillä. Jos et näe alla kuvattua Agency API -välilehteä, ota yhteyttä tukeen.

Hanki master key

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

1. Kirjaudu sisään osoitteessa app.coredash.app.
2. Avaa My Account 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 merkkijonolla cdk_master_. Ne antavat haltijalleen mahdollisuuden hallita jokaista käyttäjätilillesi kuuluvaa projektia ja lukea niiden dataa. Käsittele niitä kuin salasanoja. Voit peruuttaa minkä tahansa master keyn samalta välilehdeltä.

Tunnistautuminen

Jokainen Agency API -pyyntö tarvitsee master keyn Authorization-otsakkeessa:

Authorization: Bearer cdk_master_YOUR_MASTER_KEY

Sama otsake toimii sekä REST project CRUD -päätepisteille että JSON-RPC-datapäätepisteelle. Mikään muu ei muutu.

Project CRUD: REST-rajapinta

Projektinhallinnan perus-URL (Base URL):

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 keyn käyttäjä. Oletuksena projekti alkaa 10 päivän kokeilujaksona. Välitä agencyplan aloittaaksesi sen kokeilun sijaan maksullisella sopimuksella, jossa on 33 päivän laskutuskausi.

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

Arvo _id on se, jonka lisäät seurantakoodiin asiakkaan sivustolle. Se on myös se project_id, jonka välität alla oleville datatyökaluille.

GET /api/agency/projects: listaa projektit

Palauttaa käyttäjäsi omistamat projektit luontipäivämäärän mukaan lajiteltuna (uusin ensin). Sivutettu arvoilla limit (maksimi 500, oletus 100) ja 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: hae yksi projekti

Palauttaa yksittäisen projektidokumentin. Palauttaa 404, jos käyttäjäsi ei omista projektia. Emme tarkoituksella erota "ei löydy" ja "ei sinun" -tilanteita toisistaan, jotta projektien ID-tunnuksia ei voi 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ää name- ja/tai url-kentän. Molemmat kentät ovat valinnaisia. Pois jätetyt kentät säilytetään ennallaan. Kaikki muu pyynnön rungossa ohitetaan. Tila, laskutus, vanhentuminen ja hälytykset hallitaan hallintapaneelin 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 lopullisesti (hard-delete)

Poistaa projektin ja kaiken siihen liittyvän: Lighthouse-ajot, CrUX-datan, hälytykset, snapshotit ja snapshot-määritykset.

Taustatietokannassa olevaa RUM-dataa ei poisteta tässä kutsussa. Se pysyy linkitettynä vanhaan projektin ID:hen, mutta muuttuu 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 keyn avulla

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

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

Kolme työkalua ovat ennallaan: 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. Project keyt eivät tarvitse tätä, koska jokainen project key on jo rajattu yhteen projektiin. Master keyt 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, jäsenneltynä sisältönä kentässä result.content[0].text. Sisäisen JSONin muoto, distribution-objekti, aikasarjojen summary-kenttä, histogrammien ämpärirakenne, kaikki käyttäytyvät samalla tavalla kuin project keyllä. Ainoa ylimääräinen vaatimus on project_id-argumentti.

Sama pätee myös get_timeseries ja get_histogram -työkaluihin. Välitä project_id ja sen jälkeen tavalliset argumentit.

Kaikki muut parametrit toimivat samalla tavalla: filters, group, percentile, date, granularity ja niin edelleen. Dimensioviittaukset (d, cc, ff, lcpel, inpel, kaikki niistä), metriikoiden kynnysarvot sekä persentiilien semantiikka on kaikki dokumentoitu CoreDash API -sivulla. Lue sieltä koko parametri- ja dimensiorajapinta. Tämä sivu käsittelee vain asioita, jotka eroavat silloin, kun tunnistaudut master keyn avulla.

Uuden asiakasprojektin käyttöönotto

Tyypillinen työnkulku toimistolle uuden asiakkaan lisäämisessä:

1. Luo master key kerran kohdassa My Account → Agency API tab ja säilytä se turvallisesti.
2. POST /api/agency/projects asiakkaan nimellä ja URL-osoitteella. Vastaus sisältää uuden _id-arvon.
3. Upota seurantakoodi asiakkaan sivustolle tuolla _id-arvolla.
4. Lue RUM-dataa kyseiselle projektille milloin tahansa tekemällä POST /api/mcp samalla master keyllä ja "project_id": "<the _id>" argumenteissa. Erillistä project keytä ei tarvita.

Siinä on koko käyttöönottosykli. Yksi avain, yksi POST, yksi seurantakoodin upotus, ja voit jo hakea dataa uutta projektia varten.

Virheet

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

Datahaut osoitteessa /api/mcp palauttavat JSON-RPC-virheobjekteja aivan kuten project keyllä. Virhekooditaulukko on CoreDash API -sivulla. Jos saat koodin -32001, tarkista vielä, että avaimesi alkaa merkkijonolla cdk_master_ ja että sisällytit project_id-arvon argumentteihin.

Kutsurajoitukset

Projektikohtaiset päivittäiset rajoitukset ovat edelleen voimassa dataa luettaessa: master keyn tekemä get_metrics-kutsu projektille A lasketaan mukaan projektin A päivittäiseen kiintiöön, ja kutsu projektille B lasketaan projektin B kiintiöön. Katso kutsurajoitustaulukko CoreDash API -sivulta. Project CRUD -kutsuja ei ole rajoitettu samalla tavalla.