API ve MCP

serp.ac'teki verilerinizle uygulamanın dışından çalışmanın iki yolu vardır. REST API; betikler, bayi panelleri ve kendi araçlarınız içindir. MCP sunucusu ise Claude veya Cursor gibi yapay zeka asistanlarının sıralamalarınızı, yapay zeka görünürlüğünüzü ve linklerinizi okumasını, izin verirseniz bunlara ekleme yapmasını sağlar. İkisi de aynı API anahtarlarını, limitleri ve kotaları kullanır.

Bu rehber geliştiriciler, indeksleme hizmetini yeniden satan ajanslar ve SEO verileri hakkında bir yapay zeka asistanına soru sormak isteyen herkes için hazırlandı.

Nasıl çalışır

• API anahtarları Ayarlar → API sayfasında oluşturulur. Anahtarları yalnızca hesap sahibi ve yöneticiler yönetebilir. Ayrıntılar için Ekip ve roller rehberine bakın.
• Her anahtar sk_live_ ile başlar ve yalnızca bir kez, oluşturduğunuz anda gösterilir. serp.ac anahtarın yalnızca hash'ini saklar, bu yüzden kaybolan bir anahtar geri getirilemez. Eskisini iptal edip yenisini oluşturun.
• Bir anahtar, onu oluşturan hesabın tüm yetkileriyle çalışır. Anahtara sahip olan herkes projelerinizi ve kotalarınızı kullanabilir, bu yüzden anahtarı gizli tutun.
• Hesap başına en fazla 20 aktif anahtarınız olabilir. Her anahtar dakikada en fazla 120 istek gönderebilir.
• İstekler ve yanıtlar JSON biçimindedir. Anahtarı her istekte Authorization başlığında gönderin: Authorization: Bearer sk_live_....
• API, paketinize tıpkı panel gibi uyar: aynı anahtar kelime, prompt ve link limitleri, aynı yapay zeka motorları ve aylık kotalar geçerlidir. Aktif bir paket veya ücretsiz deneme gerekir.

Temel URL, Ayarlar → API sayfasındaki API referansı bölümünün başında yazar (serp.ac adresiniz ve ardından /api/v1).

Adım adım anahtar oluşturun

1. Ayarlar → API sayfasını açın.
2. API anahtarları bölümüne daha sonra tanıyacağınız bir ad yazın, örneğin "Bayi paneli".
3. Anahtar oluştur düğmesine tıklayın.
4. Anahtarı hemen kopyalayın. Mesajda "Şimdi kopyalayın — bir daha gösterilmeyecek." yazar.
5. Anahtarı bir şifre yöneticisinde veya sunucunuzun gizli ayarlarında saklayın, asla herkese açık kodda tutmayın.
6. Kısa bir çağrıyla test edin:

curl https://serp.ac/api/v1/usage \
  -H "Authorization: Bearer sk_live_..."

7. Anahtar listesini daha sonra kontrol edin: her anahtarın başlangıcı (sk_live_xxxx…), Oluşturulma, Son kullanım ve Durum bilgileri görünür.
8. Bir anahtar sızarsa veya artık gerekmiyorsa İptal et düğmesine tıklayın. Bu anahtarı kullanan uygulamalar hemen çalışmayı durdurur.

Uç noktalar

Metot	Yol	Ne yapar
GET	/api/v1/usage	Paket, abonelik durumu ve aylık indeksleyici kotaları
GET	/api/v1/projects	Projeleriniz (id, ad, alan adı, ülke, dil)
POST	/api/v1/index/submit	URL'leri indeksleyiciye gönderir
POST	/api/v1/index/check	URL'lerin indekslenip indekslenmediğini kontrol eder
GET	/api/v1/index/jobs/:id	Bir işin durumu ve her URL'nin durumu
POST	/api/v1/keywords	Bir projede SERP anahtar kelimelerini takibe başlar
GET	/api/v1/prompts	İzin verilen yapay zeka motorları ve her projenin marka adları, rakipleri, takip edilen promptları
POST	/api/v1/prompts	Bir projeye yapay zeka promptları ekler
GET	/api/v1/links?source_domain=…	Bir yayıncının alan adında takip ettiğiniz satın alınan linkler
POST	/api/v1/links	Link yönetimine satın alınan bir link ekler
GET	/api/v1/maps/campaigns	Maps kampanyaları ve son tarama sonuçları
GET	/api/v1/maps/scans?campaign_id=…	Bir Maps kampanyasının tarama geçmişi ve ızgara sonuçları
GET	/api/v1/keyword-data	Bu ayki anahtar kelime sorgu kotası
POST	/api/v1/keyword-data	Arama hacmi, TBM (CPC), rekabet, zorluk, arama amacı ve 12 aylık trend

GET /api/v1/balance eski entegrasyonlar için hâlâ çalışır ancak kullanımdan kaldırılmıştır. Bunun yerine /api/v1/usage kullanın.

Bilmeniz gereken birkaç ayrıntı:

• İndeksleme: İstek başına en fazla 10.000 URL içeren {"urls": [...]} gönderin. project_id isteğe bağlıdır, tekrarlanan URL'ler çıkarılır. Her URL, önce aylık kotadan, ardından kullanım paketlerinden 1 indeksleyici URL'si (submit) veya 1 indeks kontrolü (check) kullanır. Yeterli kota yoksa hiçbir şey düşülmez. İşin durumu done olana kadar işi sorgulayın. Ayrıntılar için İndeksleme rehberine bakın.
• Anahtar kelimeler: project_id ile birlikte keywords (en fazla 100) veya tek bir keyword gönderin. device (desktop veya mobile) ve location isteğe bağlıdır; konum varsayılan olarak projenin ülkesidir.
• Promptlar: project_id ile birlikte prompts (en fazla 50) veya tek bir prompt gönderin. engines isteğe bağlıdır (chatgpt, perplexity, gemini, claude, ai_mode) ve varsayılan olarak paketinizin içerdiği motorları kullanır. Zaten takip edilen promptlar yanıtta belirtilir ve değiştirilmez.
• Linkler: project_id, source_url ve target_url zorunludur. Anchor, rel, fiyat, faturalandırma döngüsü, tarihler, satıcı, etiketler ve notlar isteğe bağlıdır. İlk kontrol yaklaşık bir dakika içinde yapılır.
• Anahtar kelime verisi: İstek başına en fazla 20 anahtar kelime. Önbellekteki anahtar kelimeler ücretsizdir; diğerleri aylık anahtar kelime sorgu kotanızdan düşer.

Hatalar

Hatalar her zaman aynı yapıdadır:

{"error": {"code": "quota_exceeded", "message": "…"}}

HTTP	Kod	Anlamı
400	invalid_json, invalid_urls, too_many_urls…	İstek gövdesi geçerli değil
401	unauthorized	API anahtarı eksik, geçersiz veya iptal edilmiş
402	quota_exceeded, limit_reached	Yeterli kota yok, bir paket limitine ulaşıldı veya aktif paket yok
403	account_suspended	Hesap askıya alınmış
404	not_found, project_not_found	İş, proje veya kampanya hesabınızda bulunmuyor
409	already_tracked	Bu satın alınan link projede zaten takip ediliyor
429	rate_limited	Bu anahtar için dakikada 120 istekten fazla

İndeksleyiciden gelen 402 quota_exceeded yanıtı, şu anda gönderebileceğiniz URL sayısını gösteren available alanını da içerir. Faturalandırma sayfasından bir kullanım paketi satın alın veya aylık sıfırlamayı bekleyin. 429 aldığınızda bekleyip tekrar deneyin; yanıtta bir Retry-After başlığı bulunur.

Yapay zeka asistanları için MCP sunucusu

serp.ac, serp.ac adresinizdeki /api/mcp yolunda uzak bir Model Context Protocol sunucusu çalıştırır. Bir kez bağladığınızda asistanınız "bu hafta hangi anahtar kelimeler düştü?" gibi soruları gerçek verilerinizle yanıtlayabilir. İzin verirseniz anahtar kelime, prompt ve link de ekleyebilir.

• Claude, Cursor, ChatGPT, VS Code, Windsurf ve Streamable HTTP aktarımını destekleyip Authorization başlığı gönderebilen diğer tüm istemcilerle çalışır.
• REST API ile aynı API anahtarlarını, istek sınırını ve kotaları kullanır.
• Veriyi değiştiren veya kota kullanan araçlar işaretlidir ve asistanlardan önce size sormaları istenir. Yalnızca okuma araçlarını açmak için sunucu URL'sine ?readonly=1 ekleyin. Salt okunur mod anahtarın değil, bağlantının bir ayarıdır.

Her istemci için adım adım kurulum ve araçların tam listesi MCP kurulum rehberinde yer alır.

İpuçları

• Her uygulama veya müşteri için ayrı bir anahtar oluşturun. Böylece birini iptal ettiğinizde diğerleri etkilenmez, Son kullanım sütunu da hangilerinin hâlâ kullanıldığını gösterir.
• Büyük bir indeksleme gönderiminden önce available değerini (kalan aylık kota + paketler) görmek için GET /api/v1/usage çağrısı yapın.
• Salt okuma amaçlı panolar veya asistanlar için MCP'yi ?readonly=1 ile bağlayın, böylece hesabınızda yanlışlıkla hiçbir şey değişmez.
• Kullanım paketlerinin süresi dolmaz ve yalnızca aylık kota bittikten sonra kullanılır. Ayrıntılar için Faturalandırma ve paketler rehberine bakın.

Sık sorulan sorular

API anahtarımı kaybettim. Tekrar görebilir miyim?

Hayır. serp.ac her anahtarın yalnızca hash'ini saklar, bu yüzden anahtar tekrar gösterilemez. Eski anahtarı iptal edip yeni bir tane oluşturun.

Editörler veya görüntüleyiciler API anahtarı oluşturabilir mi?

Hayır. Anahtarları yalnızca hesap sahibi ve yöneticiler oluşturabilir veya iptal edebilir. Bir anahtar, kimin oluşturduğundan bağımsız olarak her zaman hesabın tüm yetkilerini taşır.

API çağrıları uygulamayla aynı kotaları mı kullanır?

Evet. İndeksleme gönderimleri ve kontrolleri, anahtar kelime verisi sorguları ile anahtar kelime, prompt ve link limitleri uygulama, REST API ve MCP sunucusu arasında ortaktır.

Google gönderdiğim bir URL'yi indekslemezse kullanım iade edilir mi?

Hayır. Kullanım yalnızca bir iş bizim tarafımızdaki teknik bir sorun nedeniyle başarısız olursa iade edilir. Gönderimler yaklaşık 3 gün sonra doğrulanır.

MCP sunucusuyla hangi yapay zeka asistanları çalışır?

Streamable HTTP aktarımını destekleyen ve Authorization başlığı gönderebilen her MCP istemcisi çalışır; Claude, Cursor, ChatGPT, VS Code ve Windsurf bunlara dahildir. Yalnızca stdio destekleyen istemciler, MCP rehberinde anlatılan mcp-remote köprüsünü kullanabilir.

İlgili rehberler

• MCP sunucusu kurulumu ve araçları
• İndeksleme
• Chrome eklentisi
• Ekip ve roller