CoreDash Agency API: Gestisci progetti ed estrai dati tra gli account

Una chiave per ogni progetto sul tuo account

L'Agency API è per gli account che gestiscono molti progetti. Agenzie, team interni che gestiscono una dozzina di brand, chiunque non voglia accedere alla dashboard ogni volta che arriva un nuovo cliente. Genera una master key una volta, poi crea progetti, aggiornali, eliminali e leggi i dati Core Web Vitals su tutti i progetti con quell'unica 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 tra i 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 vuoi.

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 l'assistenza.

Ottieni una master key

Le master key vengono generate dalla UI web, non dall'API.

1. Accedi su app.coredash.app.
2. Apri My Account e clicca sulla scheda Agency API.
3. Clicca 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 dell'Agency API necessita di una master key nell'intestazione Authorization:

Authorization: Bearer cdk_master_YOUR_MASTER_KEY

La stessa intestazione funziona sia per gli endpoint REST per il 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 normali 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 con 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 per i dati qui sotto.

GET /api/agency/projects: elenca i progetti

Restituisce i progetti di cui il tuo utente è proprietario, ordinati per data di creazione (dal più recente). Paginato con limit (max 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 progetto

Restituisce il documento di un singolo progetto. Restituisce 404 se il tuo utente non è proprietario del progetto. Abbiamo deliberatamente scelto di non differenziare "non trovato" da "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 facoltativi. I campi omessi vengono lasciati inalterati. Qualsiasi altra cosa nel corpo 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 nell'archivio dati di base 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 }

Leggere i 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 in arguments in modo che la chiamata sappia quale progetto guardare. Le chiavi del progetto non ne hanno bisogno perché ogni chiave del 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 analizzato in result.content[0].text. La forma del JSON interno, l'oggetto distribution, il campo summary nelle serie temporali, la struttura dei bucket negli istogrammi, si comportano tutti allo stesso modo che con una chiave del progetto. L'unico requisito extra è 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 alle dimensioni (d, cc, ff, lcpel, inpel, tutti), le soglie delle metriche e la semantica dei percentili sono tutti documentati nella pagina CoreDash API. Leggi quella pagina per l'intera superficie di parametri e 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 volta su My Account → scheda Agency API 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 quel _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. Non è necessaria una chiave del progetto separata.

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

Errori

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

Le letture dei dati su /api/mcp restituiscono oggetti di errore JSON-RPC, allo stesso modo che con una chiave del progetto. La tabella dei codici di errore si trova nella pagina CoreDash API. Se ottieni -32001, ricontrolla che la tua chiave inizi con cdk_master_ e che tu abbia incluso project_id negli argomenti.

Limiti di frequenza

I limiti giornalieri per progetto si applicano ancora quando leggi i dati: una master key che chiama get_metrics per il progetto A viene conteggiata nella quota giornaliera del progetto A, e una chiamata per il progetto B viene conteggiata in quella del progetto B. Consulta la tabella dei limiti di frequenza nella pagina CoreDash API. Le chiamate per il CRUD dei progetti non sono limitate nella frequenza allo stesso modo.