CoreDash Agency API: Projeleri Yönetin ve Hesaplar Arasında Veri Çekin

Hesabınızdaki her proje için tek bir anahtar

Agency API, birçok projeyi yöneten hesaplar içindir. Ajanslar, bir düzine markayı yöneten kurum içi ekipler, yeni bir müşteri her geldiğinde dashboard'a giriş yapmak istemeyen herkes. Bir kez master key oluşturun, ardından projeler oluşturun, güncelleyin, silin ve o tek kimlik bilgisiyle tüm projelerdeki Core Web Vitals verilerini okuyun.

Bunun yerine proje bazlı API'yi mi arıyorsunuz? CoreDash API sayfası, proje kapsamlı bir anahtara sahip tek bir projeyi kapsar. Aynı veri araçları, daha dar kapsam, daha basit kurulum.

Agency API iki şey yapar:

1. Proje CRUD: projeler oluşturmak, listelemek, güncellemek ve silmek için /api/agency/projects adresinde küçük bir REST yüzeyi.
2. Projeler arası veri okumaları: /api/mcp adresinde proje bazlı API ile aynı JSON-RPC araçları (get_metrics, get_timeseries, get_histogram). Bir master key ile, hangi projeyi istediğinizi seçmek için argümanlarda project_id iletirsiniz.

İki tür API anahtarı

CoreDash iki anahtar katmanı yayınlar. Her birinin farklı bir görevi vardır.

Master key'ler yalnızca agency olarak işaretlenmiş hesaplarda kullanılabilir. Aşağıda açıklanan Agency API sekmesini görmüyorsanız, destek ekibiyle iletişime geçin.

Bir master key edinin

Master key'ler API'den değil, web kullanıcı arayüzünden oluşturulur.

1. app.coredash.app adresinden giriş yapın.
2. My Account (Hesabım) bölümünü açın ve Agency API sekmesine tıklayın.
3. Generate master key (Master key oluştur) düğmesine tıklayın, bir isim verin ve değeri kopyalayın. Sadece bir kez gösterilir.

Anahtarlar cdk_master_ ile başlar. Sahibinin kullanıcı hesabınıza ait her projeyi yönetmesine ve herhangi biri için veri okumasına izin verirler. Onlara şifre gibi davranın. Herhangi bir master key'i aynı sekmeden iptal edebilirsiniz.

Kimlik Doğrulama (Authentication)

Her Agency API isteği, Authorization başlığında bir master key'e ihtiyaç duyar:

Authorization: Bearer cdk_master_YOUR_MASTER_KEY

Aynı başlık, hem REST proje CRUD uç noktaları hem de JSON-RPC veri uç noktası için çalışır. Başka hiçbir şey değişmez.

Proje CRUD: REST yüzeyi

Proje yönetimi için temel URL (Base URL):

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

Bunlar düz REST çağrılarıdır. JSON-RPC değildir.

POST /api/agency/projects: bir proje oluştur

Master key'in kullanıcısına ait yeni bir proje oluşturur. Varsayılan olarak proje 10 günlük bir deneme olarak başlar. 33 günlük faturalandırma dönemi ile bunun yerine ücretli bir planda başlatmak için agencyplan değerini iletin.

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

Başarı durumunda yanıt 201'dir:

{
  "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, istemcinin sitesindeki izleme koduna (tracking snippet) koyduğunuz değerdir. Aynı zamanda aşağıdaki veri araçlarına ilettiğiniz project_id'dir.

GET /api/agency/projects: projeleri listele

Kullanıcınızın sahip olduğu projeleri oluşturulma tarihine göre sıralanmış olarak (en yeni ilk sırada) döndürür. limit (maksimum 500, varsayılan 100) ve offset ile sayfalandırılır.

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: bir proje getir

Tek bir proje belgesi döndürür. Kullanıcınız projeye sahip değilse 404 döndürür. Proje ID'lerinin hesaplar arasında numaralandırılamaması için "bulunamadı" ile "sizin değil" durumlarını kasıtlı olarak ayırmıyoruz.

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

PATCH /api/agency/projects/:id: adı veya URL'yi güncelle

name ve/veya url değerini günceller. Her iki alan da isteğe bağlıdır. Çıkarılan alanlar olduğu gibi bırakılır. Gövdedeki (body) diğer her şey yok sayılır. Durum, faturalandırma, süre sonu ve uyarılar dashboard üzerinden yönetilir.

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: bir projeyi kalıcı olarak sil

Projeyi ve ona bağlı her şeyi siler: Lighthouse çalışmaları, CrUX verileri, uyarılar, anlık görüntüler (snapshots) ve anlık görüntü yapılandırmaları.

Destekleyici veri deposundaki RUM verileri bu çağrıda silinmez. Eski proje ID'sine anahtarlanmış olarak kalır ancak yetim kalır (orphaned). Geri kurtarma yolu yoktur. Proje ID'si kullanımdan kaldırılır.

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

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

Bir master key ile veri okuma

Projelerinizden biri için Core Web Vitals verilerini çekmek için, proje bazlı API'nin kullandığı aynı JSON-RPC uç noktasına istek yapın:

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

Üç araç değişmemiştir: get_metrics, get_timeseries, get_histogram. Proje bazlı akışa kıyasla tek fark, çağrının hangi projeye bakacağını bilmesi için arguments içinde project_id iletmenizdir. Proje anahtarlarının (Project keys) buna ihtiyacı yoktur çünkü her proje anahtarı zaten tek bir projeye göre kapsamlandırılmıştır. Master key'ler birçok projeyi kapsar, bu nedenle isteğin birini isimlendirmesi gerekir.

Örnek: Belirli bir proje için get_metrics

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

Yanıt, ayrıştırılmış payload'un result.content[0].text içinde olduğu, proje bazlı API ile aynı JSON-RPC sarmalayıcısıdır (wrapper). İç JSON'ın şekli, distribution nesnesi, timeseries'deki summary alanı, histogramlardaki kova (bucket) yapısı, hepsi bir proje anahtarındakiyle aynı şekilde davranır. Tek ekstra gereksinim project_id argümanıdır.

Aynı durum get_timeseries ve get_histogram için de geçerlidir. project_id'yi iletin, ardından normal argümanları ekleyin.

Diğer tüm parametreler aynı şekilde çalışır: filters, group, percentile, date, granularity vb. Boyutlar referansı (d, cc, ff, lcpel, inpel, tamamı), metrik eşikleri ve persentil semantiği tamamen CoreDash API sayfasında belgelenmiştir. Tam parametre ve boyut yüzeyi için orayı okuyun. Bu sayfa yalnızca bir master key ile kimlik doğrulaması yaptığınızda neyin farklı olduğunu kapsar.

Yeni bir müşteri projesini dahil etme (Onboarding)

Yeni bir müşteri ekleyen bir ajans için tipik akış:

1. My Account → Agency API sekmesinde bir kez bir master key oluşturun ve güvenli bir şekilde saklayın.
2. Müşterinin adı ve URL'si ile POST /api/agency/projects isteği yapın. Yanıt, yeni _id değerini içerir.
3. Müşterinin sitesine, bu _id ile izleme kodunu (tracking snippet) gömün.
4. Aynı master key ve argümanlarda "project_id": "<the _id>" kullanarak POST /api/mcp aracılığıyla o proje için RUM verilerini istediğiniz zaman okuyun. Ayrı bir proje anahtarına gerek yoktur.

Bu, tüm katılım (onboarding) döngüsüdür. Bir anahtar, bir POST, bir snippet yerleştirme ile yeni proje için verileri hemen sorgulayabilirsiniz.

Hatalar (Errors)

Proje CRUD uç noktaları düz REST durum kodları (status codes) döndürür:

/api/mcp adresindeki veri okumaları, proje anahtarında olduğu gibi JSON-RPC hata nesneleri döndürür. Hata kodu tablosu CoreDash API sayfasındadır. -32001 hatası alırsanız, anahtarınızın cdk_master_ ile başladığından ve argümanlara project_id'yi dahil ettiğinizden emin olun.

Hız sınırları (Rate limits)

Veri okuduğunuzda proje bazlı günlük sınırlar geçerliliğini korur: A projesi için get_metrics çağıran bir master key, A projesinin günlük kotasından düşer ve B projesi için bir çağrı B projesinin kotasından düşer. CoreDash API sayfasındaki hız sınırları tablosuna bakın. Proje CRUD çağrıları aynı şekilde hız sınırına tabi değildir.