CoreDash Agency API: Projeleri Yönetin ve Hesaplar Arası 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 şirket içi ekipler, yeni bir müşteri geldiğinde her seferinde panele giriş yapmak istemeyen herkes. Bir kez master anahtarı oluşturun, ardından projeler yaratın, güncelleyin, silin ve bu tek kimlik belgesiyle tüm projelerinizdeki Core Web Vitals verilerini okuyun.

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

Agency API iki şey yapar:

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

İki tür API anahtarı

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

Master anahtarları yalnızca agency işaretli hesaplarda kullanılabilir. Aşağıda açıklanan Agency API sekmesini görmüyorsanız desteğe başvurun.

Bir master anahtarı alın

Master anahtarları 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 anahtarı oluştur) düğmesine tıklayın, bir ad verin ve değeri kopyalayın. Yalnızca bir kez gösterilir.

Anahtarlar cdk_master_ ile başlar. Sahibinin kullanıcı hesabınıza ait her projeyi yönetmesine ve herhangi birinin verilerini okumasına olanak tanırlar. Onlara şifre gibi davranın. Herhangi bir master anahtarını aynı sekmeden iptal edebilirsiniz.

Kimlik Doğrulama

Her Agency API isteği, Authorization başlığında bir master anahtarına 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:

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şturun

Master anahtarının 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 bir faturalandırma dönemi ile bunun yerine ücretli bir planda başlatmak için agencyplan değerini geçin.

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ılı olduğunda 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, müşterinin sitesindeki izleme parçacığına (tracking snippet) koyduğunuz şeydir. Ayrıca aşağıdaki veri araçlarına geçireceğiniz project_id'dir.

GET /api/agency/projects: projeleri listele

Kullanıcınızın sahip olduğu projeleri oluşturulma tarihine göre (en yeni ilk sırada) sıralanmış olarak 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: tek bir projeyi getir

Tek bir proje dokümanı döndürür. Kullanıcınız projeye sahip değilse 404 döndürür. Proje kimliklerinin hesaplar arasında sıralanamaması için bilinçli olarak "bulunamadı" ile "size ait değil" durumlarını birbirinden 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ğerlerini günceller. Her iki alan da isteğe bağlıdır. Atlanan alanlar olduğu gibi bırakılır. Gövdedeki diğer her şey yoksayılır. Durum, faturalandırma, son kullanma tarihi ve uyarılar panel ü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 (hard-delete)

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ı.

Destek veri deposundaki RUM verileri bu çağrıda silinmez (not). Eski proje kimliği üzerinde anahtarlanmış olarak kalır ancak sahipsiz (orphaned) hale gelir. Kurtarma yolu yoktur. Proje kimliği emekliye ayrı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 anahtarı ile veri okuma

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

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

Üç araç değişmedi: 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 değerini geçirmenizdir. Proje anahtarlarının buna ihtiyacı yoktur çünkü her proje anahtarı zaten tek bir projeye göre kapsamlandırılmıştır. Master anahtarları birçok projeyi kapsar, bu nedenle isteğin birini adlandırması 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, çözümlenmiş yükü (payload) result.content[0].text içinde olan proje bazlı API ile aynı JSON-RPC sarmalayıcısıdır. İç JSON'ın şekli, distribution nesnesi, zaman serilerindeki summary alanı, histogramlardaki kova (bucket) yapısı, hepsi bir proje anahtarıyla 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 değerini, ardından her zamanki argümanları geçirin.

Diğer tüm parametreler aynı şekilde çalışır: filters, group, percentile, date, granularity vb. Boyut referansları (d, cc, ff, lcpel, inpel, hepsi), metrik eşikleri ve yüzdelik dilim anlambilimi (percentile semantics) CoreDash API sayfasında belgelenmiştir. Tam parametre ve boyut yüzeyi için bunu okuyun. Bu sayfa yalnızca bir master anahtarı ile kimlik doğrulaması yaptığınızda nelerin farklı olduğunu kapsar.

Yeni bir müşteri projesini dahil etme

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

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

Tüm dahil etme döngüsü budur. Bir anahtar, bir POST, bir parçacık yerleştirme ve yeni proje için verileri hemen sorgulayabilirsiniz.

Hatalar

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

/api/mcp adresindeki veri okumaları, proje anahtarıyla aynı şekilde JSON-RPC hata nesneleri döndürür. Hata kodu tablosu CoreDash API sayfasındadır. -32001 alırsanız, anahtarınızın cdk_master_ ile başladığından ve argümanlara project_id eklediğinizden emin olun.

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

Veri okuduğunuzda proje bazlı günlük sınırlar uygulanmaya devam eder: proje A için get_metrics çağıran bir master anahtarı proje A'nın günlük kotasından düşer ve proje B için yapılan bir çağrı proje B'ninkinden düşer. CoreDash API sayfasındaki hız sınırları (rate limits) tablosuna bakın. Proje CRUD çağrıları aynı şekilde hız sınırlandırmasına tabi tutulmaz.