Kosto API belgeleri:
alan adı otoritesi, kendi araçlarında.

Başlarken

Hızlı başlangıç

Anahtar almaktan ilk yanıta üç adım.

1. 1

   Anahtar alın

   Aşağıdan bir anahtar oluştur. Anahtar yalnızca oluşturulduğu anda görünür; kopyalayıp güvenli bir yere kaydet.
2. 2

   İlk isteği gönder

   Anahtarı Authorization başlığında yollayın. Sağdaki örnek seçtiğin dilde hazır; YOUR_API_KEY yerine kendi anahtarını yaz.

3. 3

   Yanıtı okuyun

   authority_score alanı 0–100 arası puandır. found false ise alan adı link endeksinde yoktur; bu bir hata değildir, 200 döner. score_source puanın türünü söyler: data veriye dayalı, standard ve calibrated yaklaşık puandır.

Her uç noktanın altındaki Dene panelinden isteği doğrudan tarayıcıdan gönderebilirsin. Anahtarı yalnızca bu sekmenin belleği tutar, hiçbir yere kaydedilmez ve istek sen düğmeye basmadan gitmez.

Başlarken

Kimlik doğrulama

/api/v1/openapi.json dışındaki her uç nokta bir API anahtarı ister. Anahtar op_ ile başlar ve toplam 35 karakterdir. Aşağıdaki iki başlıktan birini kullan; ikisi de aynı işi görür.

Anahtarı korumak

• Sunucu anahtarın kendisini değil SHA-256 özetini saklar. Kaybedersen yeni anahtar üretin; eskisini iptal et.
• Anahtarı ortam değişkeninde ya da gizli anahtar kasanda tut. Kaynak koduna, herkese açık depolara ve tarayıcıda çalışan koda koymayın.
• İptal edilen anahtar 403 key_revoked alır. Anahtar yok ya da biçimi yanlışsa 401 döner.
• CORS başlığı gönderilmez; başka bir sitenin tarayıcı kodu bu API'yi okuyamaz (cross_site_forbidden). Betikler, komut satırı ve sunucu tarafı kod sorunsuz çalışır.
• Hesap modunda anahtar bir hesaba aittir ve o hesabın planına göre sayılır; hesabı askıdaki ya da hiçbir hesaba bağlı olmayan anahtar 403 alır.

Başlarken

Hız sınırları ve kotalar

İki ayrı sınır vardır: dakikalık hız sınırı bütün anahtarlar için aynıdır; aylık ve günlük kotalar planına bağlıdır.

Hız sınırı: dakikada 120 istek

Her anahtar 60 saniyelik sabit bir pencerede 120 istek yapabilir. Pencere anahtarın ilk isteğiyle açılır, 60 saniye sonra kapanır ve sayaç sıfırlanır. Geçerli anahtar göndermeyen istekler istemci adresi başına ortak bir pencerede sayılır. Reddedilen (401, 400 gibi) istekler de pencereye yazılır. Her /api/v1 yanıtında şu başlıklar bulunur:

Sınır aşılınca 429 rate_limited döner. Retry-After başlığındaki süre kadar bekleyip yeniden dene; beklemeden tekrar denemek pencereyi daha da doldurur.

Plan kotaları

Hesap modunda her çağrı API isteği sayacından bir düşer. Toplu sorgu satır sayısı kadar toplu sorgu satırı, spam denetimi ise bir spam denetimi hakkı harcar. Başarısız bir çağrı harcadığı hakkı geri verir. Aynı alan adının aynı günkü spam denetimi tekrar sayılmaz (fresh=1 hariç).

Günlük kotalar ve aylık kotalar Türkiye saatiyle (UTC+3) gece yarısı ve ay başında yenilenir. Kota dolunca 429 quota_exceeded döner; mesaj hangi sayacın dolduğunu, kullanımını ve planını söyler. Fiyatlar için plan sayfasına bak.

Başlarken

Hata kodları

Hatalar HTTP durum koduyla ve hep aynı gövdeyle gelir. code sabittir; programın ona göre dallanmalıdır. message insanlar için yazılmış bir açıklamadır ve değişebilir; varsayılan olarak İngilizcedir, Accept-Language ya da X-Kosto-Lang başlığıyla başka bir dil seçilir.

• 5xx ve 429 yanıtlarında Retry-After başlığı varsa o süre kadar bekle; 4xx yanıtlarını aynı istekle yinelemeyin, isteği düzeltin.
• 405 yanıtında Allow başlığı uç noktanın desteklediği yöntemi söyler. HEAD, GET gibi işlenir.
• Link endeksi yüklenirken referans sorguları 503 graph_unavailable verebilir; Retry-After: 15 sonrası yeniden dene.

Başlarken

Sayfalama ve toplu istek

API imleç (cursor) ya da sayfa numarası kullanmaz. Liste dönen uç noktalar tek yanıt verir ve boyutu parametrelerle sınırlanır.

Büyük listeleri bölmek

1000'den fazla alan adın varsa listeyi 1000'erlik parçalara bölüp ardışık gönder. Her parça bir istektir ve dakikalık sınıra sayılır; hesap modunda ayrıca satır sayısı kadar toplu sorgu kotası harcar.

Diğer

Sürümleme ve değişiklik günlüğü

Sürüm adresin içindedir: /api/v1. OpenAPI belgesinin info.version alanı bu sürümün belge sürümünü verir.

• Yeni uç noktalar ve yanıtlara yeni alanlar sürümü değiştirmeden eklenebilir. İstemcinin bilmediği alanları yok saymasını bekleriz.
• Var olan bir alanın türünü ya da anlamını değiştirmek, alan silmek gibi uyumsuz değişiklikler yeni bir sürümle (/api/v2) gelir.
• message metinleri değişebilir. code değerlerine ve HTTP durum kodlarına bak.

1. 1.0.0Güncel sürüm

   İlk sürüm. Yedi uç nokta: domain, backlinks, compare, bulk, spam, usage ve openapi.json.

   • Anahtar doğrulama: Authorization: Bearer ya da X-API-Key.
   • Dakikada 120 istek hız sınırı ve X-RateLimit-* başlıkları.
   • Hata biçimi { "error": { "code", "message" } }.