CoreDash Agency API: Gestisci progetti ed estrai dati da più account

Una chiave per ogni progetto sul tuo account

L'Agency API è per gli account che gestiscono molti progetti. Agenzie, team interni che gestiscono decine di brand, chiunque non voglia accedere alla dashboard ogni volta che arriva un nuovo cliente. Genera una master key una volta sola, poi crea progetti, aggiornali, eliminali e leggi i dati Core Web Vitals su tutti quanti con quella singola credenziale.

Cerchi invece l'API per singolo progetto? La pagina CoreDash API copre un singolo progetto con una chiave limitata al progetto. Stessi strumenti per i dati, ambito più ristretto, configurazione più semplice.

L'Agency API fa due cose:

1. CRUD dei progetti: una piccola superficie REST su /api/agency/projects per creare, elencare, aggiornare ed eliminare progetti.
2. Letture dei dati trasversali ai progetti: gli stessi strumenti JSON-RPC dell'API per singolo progetto (get_metrics, get_timeseries, get_histogram) su /api/mcp. Con una master key passi project_id negli argomenti per scegliere quale progetto desideri.

Due tipi di chiavi API

CoreDash emette due livelli di chiavi. Ognuno ha un compito diverso.

Le master key sono disponibili solo sugli account contrassegnati come agenzia. Se non vedi la scheda Agency API descritta di seguito, contatta il supporto.

Ottieni una master key

Le master key vengono generate dall'interfaccia utente web, non dall'API.

1. Accedi su app.coredash.app.
2. Apri My Account e fai clic sulla scheda Agency API.
3. Fai clic su Generate master key, dalle un nome e copia il valore. Viene mostrato una sola volta.

Le chiavi iniziano con cdk_master_. Permettono al titolare di gestire ogni progetto che appartiene al tuo account utente e di leggere i dati per ognuno di essi. Trattale come password. Puoi revocare qualsiasi master key dalla stessa scheda.

Autenticazione

Ogni richiesta Agency API necessita di una master key nell'header Authorization:

Authorization: Bearer cdk_master_YOUR_MASTER_KEY

Lo stesso header funziona sia per gli endpoint REST CRUD dei progetti sia per l'endpoint dati JSON-RPC. Non cambia nient'altro.

CRUD dei progetti: la superficie REST

URL di base per la gestione dei progetti:

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

Queste sono semplici chiamate REST. Non JSON-RPC.

POST /api/agency/projects: crea un progetto

Crea un nuovo progetto di proprietà dell'utente della master key. Per impostazione predefinita, il progetto inizia come una prova di 10 giorni. Passa agencyplan per avviarlo invece su un piano a pagamento, con un periodo di fatturazione di 33 giorni.

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

La risposta in caso di successo è 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" }
  }
}

L'_id è ciò che inserisci nello snippet di tracciamento sul sito del cliente. È anche il project_id che passi agli strumenti dati qui sotto.

GET /api/agency/projects: elenca i progetti

Restituisce i progetti di proprietà del tuo utente, ordinati per data di creazione (dal più recente). Impaginato con limit (massimo 500, predefinito 100) e 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: recupera un singolo progetto

Restituisce un singolo documento di progetto. Restituisce 404 se il tuo utente non è proprietario del progetto. Deliberatamente non facciamo distinzione tra "non trovato" e "non tuo", in modo che gli ID dei progetti non possano essere enumerati tra gli account.

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

PATCH /api/agency/projects/:id: aggiorna nome o URL

Aggiorna name e/o url. Entrambi i campi sono opzionali. I campi omessi vengono lasciati come erano. Qualsiasi altra cosa nel body viene ignorata. Stato, fatturazione, scadenza e avvisi sono gestiti tramite la dashboard.

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: elimina definitivamente un progetto

Elimina il progetto e tutto ciò che vi è collegato: esecuzioni di Lighthouse, dati CrUX, avvisi, snapshot e configurazioni degli snapshot.

I dati RUM nel datastore sottostante non vengono eliminati in questa chiamata. Rimangono associati al vecchio ID del progetto ma diventano orfani. Non esiste alcun percorso di ripristino. L'ID del progetto viene ritirato.

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

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

Lettura dei dati con una master key

Per estrarre i dati Core Web Vitals per uno dei tuoi progetti, chiama lo stesso endpoint JSON-RPC utilizzato dall'API per singolo progetto:

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

I tre strumenti rimangono invariati: get_metrics, get_timeseries, get_histogram. L'unica differenza rispetto al flusso per singolo progetto è che passi project_id negli arguments in modo che la chiamata sappia quale progetto guardare. Le chiavi di progetto non ne hanno bisogno perché ogni chiave di progetto è già limitata a un progetto. Le master key coprono molti progetti, quindi la richiesta deve nominarne uno.

Esempio: get_metrics per un progetto specifico

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

La risposta è lo stesso wrapper JSON-RPC dell'API per singolo progetto, con il payload parsato in result.content[0].text. La struttura del JSON interno, l'oggetto distribution, il campo summary sulle serie temporali, la struttura dei bucket sugli istogrammi, si comportano tutti allo stesso modo rispetto a una chiave di progetto. L'unico requisito aggiuntivo è l'argomento project_id.

Lo stesso vale per get_timeseries e get_histogram. Passa project_id, poi i soliti argomenti.

Tutti gli altri parametri funzionano allo stesso modo: filters, group, percentile, date, granularity e così via. Il riferimento delle dimensioni (d, cc, ff, lcpel, inpel, tutti quanti), le soglie delle metriche e la semantica dei percentili sono tutti documentati sulla pagina CoreDash API. Leggila per l'intera superficie dei parametri e delle dimensioni. Questa pagina copre solo ciò che è diverso quando ti autentichi con una master key.

Onboarding di un nuovo progetto cliente

Il flusso tipico per un'agenzia che aggiunge un nuovo cliente:

1. Genera una master key una sola volta in My Account → Agency API tab e conservala in modo sicuro.
2. POST /api/agency/projects con il nome e l'URL del cliente. La risposta contiene il nuovo _id.
3. Incorpora lo snippet di tracciamento sul sito del cliente con quell'_id.
4. Leggi i dati RUM per quel progetto in qualsiasi momento tramite POST /api/mcp con la stessa master key e "project_id": "<the _id>" negli argomenti. Nessuna chiave di progetto separata necessaria.

Questo è l'intero ciclo di onboarding. Una chiave, un POST, l'incorporamento di uno snippet e puoi già interrogare i dati per il nuovo progetto.

Errori

Gli endpoint CRUD dei progetti restituiscono normali codici di stato REST:

Le letture dei dati su /api/mcp restituiscono oggetti di errore JSON-RPC, come avviene con una chiave di progetto. La tabella dei codici di errore si trova sulla pagina CoreDash API. Se ottieni -32001, ricontrolla che la tua chiave inizi con cdk_master_ e di aver incluso project_id negli argomenti.

Limiti di velocità

I limiti giornalieri per singolo progetto si applicano ancora quando leggi i dati: una master key che chiama get_metrics per il progetto A conta nel limite giornaliero del progetto A, e una chiamata per il progetto B conta nel limite del progetto B. Consulta la tabella dei rate limit sulla pagina CoreDash API. Le chiamate CRUD ai progetti non sono limitate allo stesso modo.