Brave Search API Anahtarı Nasıl Alınır ve İlk Arama Sorgunuzu Çalıştırın

Bir Brave API anahtarı size Brave'in bağımsız web dizinine programatik erişim sağlar: Brave Search'ün tarayıcıda sunduğu aynı sonuçlar, komut dosyalarınıza, kontrol panellerinize veya yapay zeka aracınıza besleyebileceğiniz JSON formatında döndürülür. Brave Search API, aracılara canlı web erişimi sağlamak için yaygın bir seçenek haline geldi; eğer son hedefiniz buysa, Brave Search MCP sunucusu rehberi anahtarın Claude ve diğer MCP istemcilerine nasıl entegre edildiğini gösterir. Bu gönderi, bundan önceki kısmı kapsıyor: hesap oluşturma, plan seçme, anahtarı oluşturma ve curl, Python ve Apidog ile gerçek bir sorgu gönderme.

Aşağıdaki her şey Eylül 2026 itibarıyla Brave'in kendi kontrol paneli belgelerinden alınmıştır. Fiyatlandırma ve limitler değişebilir, bu nedenle sayıları anlık bir görüntü olarak kabul edin ve bütçeleme yapmadan önce bağlantılı sayfaları kontrol edin.

Başlamadan Önce İhtiyacınız Olanlar

• Kontrol paneli hesabı için bir e-posta adresi.
• Bir kredi kartı. Brave, dolandırıcılık karşıtı bir kontrol olarak, ücretsiz kredi katmanı da dahil olmak üzere her planda bir kart gerektirir. Planlar sayfasındaki SSS, ücretsiz planlar için kartın yalnızca kimliğinizi doğrulamak için kullanıldığını belirtir.
• Komut satırı örnekleri için curl veya `requests` paketi yüklü Python 3.
• Anahtarı güvenli bir şekilde saklamak ve isteği tekrarlanabilir bir teste dönüştürmek isterseniz Apidog. İlk çağrı için isteğe bağlıdır.

Adım 1: Bir Brave Search API hesabı oluşturun

Brave Search API kontrol paneline gidin ve bir e-posta adresi ve şifre ile kaydolun. Brave bir onay bağlantısı gönderir; adresi doğrulamak için tıklayın. Bunu yapana kadar bir planı etkinleştiremezsiniz.

Kontrol paneli, herhangi bir Brave tarayıcısından veya Brave Rewards girişinden ayrıdır, bu nedenle mevcut bir tarayıcı hesabı taşınmaz. Yeniden kaydolun.

Adım 2: Bir plan seçin (ücretsiz kademenin bir püf noktası var)

Kontrol panelindeki Planlar sayfasını açın. Eylül 2026 itibarıyla, Brave'in fiyatlandırma sayfası şu seçenekleri listeler:

Web araması için Search'ü seçin. Aylık 5 dolarlık kredi, herhangi bir ödeme yapmadan önce yaklaşık 1.000 web arama isteğini karşılar ki bu, geliştirme ve küçük aracı iş yükleri için yeterlidir. Faturalandırma ön ödemelidir: kredileri önceden satın alırsınız ve aylık ücretsiz kredi otomatik olarak uygulanır.

Püf noktası karttır. Ücretsiz kredi dahil, bir kart girmeden hiçbir planı etkinleştiremezsiniz. Sabit aylık sorgu kotası olan kartsız bir ücretsiz planı açıklayan eski rehberler görmüşseniz, bunlar Brave'in önceki fiyatlandırma neslini tanımlamaktadır. Yeni hesaplar yukarıdaki kredi modelini alır.

Planı seçin ve kart bilgilerinizi girin. Plan, kontrol panelinde hemen aktif olarak görünür.

Adım 3: API anahtarını oluşturun

Aktif bir planla, API Anahtarları bölümünü açın, "API Anahtarı Ekle"ye tıklayın ve anahtara açıklayıcı bir ad verin. Brave'in hızlı başlangıcı "Üretim Uygulaması" veya "Geliştirme" gibi adlar önerir. Her ortam için bir anahtar, diğerlerini etkilemeden tek bir anahtarı iptal etmeniz gerektiğinde daha sonra işe yarar.

Anahtarı kopyalayın ve hemen güvenli bir yere saklayın. Brave'in kimlik doğrulama rehberi, anahtarın nereye gitmemesi gerektiği konusunda açık sözlüdür: istemci tarafı kodu, herkese açık depolar veya herhangi bir herkese açık konum. Bu kimlik bilgilerinin nasıl çalıştığına yeniyseniz, API anahtarının ne olduğuna dair ön bilgi, modeli birkaç dakikada açıklar.

Adım 4: İlk arama isteğinizi gönderin

Web arama uç noktası `https://api.search.brave.com/res/v1/web/search` şeklindedir. Her istek, anahtarı bir `X-Subscription-Token` başlığında gerektirir. Başlık adına dikkat edin: bu `Authorization: Bearer` değildir ve anahtarı bu şekilde göndermek başarısız olur.

curl

curl "https://api.search.brave.com/res/v1/web/search?q=openapi+3.1+breaking+changes&count=5&freshness=py" \
  -H "Accept: application/json" \
  -H "Accept-Encoding: gzip" \
  -H "X-Subscription-Token: $BRAVE_API_KEY"

`count` sayfa başına sonuçları sınırlar (maks. 20, varsayılan 20), `offset` bunlar arasında sayfalar (0 tabanlı, maks. 9) ve `freshness` yaşa göre filtreler: son gün, hafta, ay veya yıl için `pd`, `pw`, `pm` veya `py`. Diğer kullanışlı parametreler `country` (iki harfli kod), `search_lang` ve `safesearch` (`off`, `moderate` veya `strict`; `moderate` varsayılandır).

Python

import os
import requests

url = "https://api.search.brave.com/res/v1/web/search"
headers = {
    "Accept": "application/json",
    "Accept-Encoding": "gzip",
    "X-Subscription-Token": os.environ["BRAVE_API_KEY"],
}
params = {"q": "openapi 3.1 breaking changes", "count": 5, "freshness": "py"}

resp = requests.get(url, headers=headers, params=params, timeout=10)
resp.raise_for_status()
data = resp.json()

for hit in data["web"]["results"]:
    print(hit["title"])
    print(hit["url"])
    print(hit["description"][:120], "\n")

Yanıt bir `query` nesnesi ( `original` ve sayfalama için `more_results_available` boolean ile) ve bir `web.results` dizisi içerir. Her sonuç `title`, `url` ve `description` içerir; `extra_snippets=true` olarak ayarlarsanız, sonuç başına beş adede kadar ekstra alıntı elde edersiniz, bu da bir model için bağlam oluştururken yardımcı olur.

Brave, API'yi `YYYY-MM-DD` biçiminde isteğe bağlı bir `Api-Version` başlığıyla sürümlemeyi sağlar. Bunu çıkarırsanız en son sürümü alırsınız; entegrasyonunuz üretime girdiğinde onu sabitleyin, böylece gelecekteki olası bir kırıcı değişiklik davetsizce gelmez.

Adım 5: Anahtarı Apidog'da test edin

Bir curl tek satırına anahtar yapıştırmak ilk deneme için iyidir. Ama orada bırakmak kötü bir fikirdir. Apidog'da anahtarı bir kez bir değişken olarak saklarsınız, her yerde ona referans verirsiniz ve sırrı paylaşılan projeden uzak tutarsınız.

1. Apidog projenizin sağ üstündeki ortam yönetimine girin ve `Brave` adında bir ortam ekleyin. `brave_api_key` adında bir değişken oluşturun ve gerçek anahtarı paylaşılan değere değil, yerel değer alanına koyun. Yerel değerler makinenizde kalır ve ekip arkadaşlarınızla asla senkronize olmaz; değişkenler referansı iki değer modelini açıklar ve Apidog'daki ortamlar ve gizli değişkenler için tam iş akışı, birden fazlasına ihtiyacınız olursa geliştirme, hazırlık ve üretim düzenlerini kapsar.
2. `https://api.search.brave.com/res/v1/web/search` adresine yeni bir GET isteği oluşturun. Başlıklar sekmesinde, `X-Subscription-Token` başlığını `{{brave_api_key}}` değeriyle ekleyin. Parametrelerde `q`, `count` ve `freshness` ekleyin.
3. Gönder'e tıklayın. Yanıt bölmesi JSON gövdesini gösterir ve başlıklar bölmesi `X-RateLimit-Remaining` ve `X-RateLimit-Reset` değerlerini gösterir, böylece herhangi bir şey yazdırmadan kotanızı izleyebilirsiniz.
4. Onaylar ekleyin: durum kodu 200'e eşit, `$.web.results` mevcut ve en az bir öğeye sahip ve `$.query.original` gönderdiğiniz sorguyla eşleşiyor. İsteği bir test senaryosuna kaydedin. Artık bir anahtar değişimi veya Brave tarafındaki bir değişiklik, sabah 2'de bozuk bir aracı yerine kırmızı bir çalıştırma olarak görünür.

Apidog'u indirin ve takip edin; ücretsiz plan dört kullanıcıyı kapsar ve ortamlar ile test senaryolarını içerir.

Oran Limitleri ve Brave'in Bunları Nasıl Raporladığı

Her yanıt, Brave'in oran sınırlama rehberinde belgelenen dört başlık taşır:

• `X-RateLimit-Limit`: planınıza eklenen limitler, örneğin `1, 15000`.
• `X-RateLimit-Policy`: pencere boyutlarıyla aynı limitler saniye cinsinden, örneğin `1;w=1, 15000;w=2592000` (bir saniyelik pencere ve 30 günlük pencere).
• `X-RateLimit-Remaining`: her pencerede kalan miktar.
• `X-RateLimit-Reset`: her pencerenin sıfırlanmasına kadar kalan saniye.

Bütçeleme için iki detay önemlidir. Birincisi, rehber sadece başarılı, hatasız yanıtların kotaya dahil olduğunu belirtir, bu nedenle bir yazım hatasından kaynaklanan bir dizi 422 hatası kredileri tüketmez. İkincisi, bu örnek başlıklardaki saniye başına rakam (saniyede 1 istek), Search planının reklamı yapılan saniyede 50 isteği değil, belgedeki bir illüstrasyondur. Varsayım yapmak yerine kendi başlıklarınızı okuyun.

Yaygın Hatalar ve Yapılması Gerekenler

Yeni bir anahtarda kimlik doğrulama hatası. Brave'in kimlik doğrulama rehberi, her isteğin `X-Subscription-Token` taşıması gerektiğini ve eksik veya geçersiz bir değerin reddedildiğini söyler. Bu genellikle, Brave'in API referansı durumu açıkça belirtmese de, belirteç geçersiz hatası koduyla HTTP 401 olarak ortaya çıkar. Üç şeyi kontrol edin: başlık adı tam ( `Authorization` değil), anahtar sondaki boşluklar olmadan kopyalandı ve hesapta aktif bir plan var. Bu şemanın taşıyıcı kimlik doğrulamasından neden farklı olduğundan emin değilseniz, API anahtarı ve taşıyıcı belirteç konusuna bakın.

422 İşlenemeyen Varlık (Unprocessable Entity). Bir parametre aralık dışındadır veya hatalı biçimlendirilmiştir: 20'nin üzerindeki `count`, 9'un üzerindeki `offset`, tanınmayan bir `freshness` değeri veya boş bir `q`. Gövde, Brave'in hata şemasına uyar:

{
  "type": "ErrorResponse",
  "error": {
    "id": "<unique occurrence id>",
    "status": 422,
    "code": "<application error code>",
    "detail": "<what went wrong>",
    "meta": {}
  },
  "time": 0
}

`error.detail`'i okuyun; alanı belirtir.

429 Çok Fazla İstek (Too Many Requests). Saniye başına limitle karşılaştınız veya krediniz bitti. Brave hem `RATE_LIMITED` hem de `QUOTA_LIMITED` hata kodlarını belgeler, bu yüzden hangisini aldığınızı kontrol edin: `X-RateLimit-Reset` içindeki saniye sayısını bekleyip geri çekilmeli bir şekilde yeniden denemek (Brave 1s, 2s, 4s önerir) ilkini düzeltir, ikincisini ise sadece kredi yüklemek veya aylık sıfırlamayı beklemek düzeltir.

SSS

Brave Search API ücretsiz mi?

Kısmen. Her plan aylık 5 dolarlık kredi alır, bu da yaklaşık 1.000 Arama isteği demektir. Bunun ötesinde, 1.000 istek başına 5.00 ABD doları ödersiniz. Krediyi asla aşmasanız bile, bir kredi kartı olmadan bir planı etkinleştirmenin bir yolu yoktur.

Web araması ve LLM Bağlamı uç noktası için ayrı anahtarlara ihtiyacım var mı?

Brave'in API referansı, belirtecin "ürün için" oluşturulduğunu belirtir, bu da bir anahtarın oluşturulduğu aboneliğe bağlı olduğunu düşündürür. Eğer `/web/search` üzerinde çalışan bir anahtar `/llm/context` veya Answers uç noktasında başarısız olursa, anahtarın bozuk olduğunu varsaymadan önce kontrol panelinde anahtarın hangi plana ait olduğunu kontrol edin.

Brave API anahtarım sızarsa ne olur?

API Anahtarları bölümünde iptal edin, yerine yenisini oluşturun ve Apidog'daki değişkeni güncelleyin, böylece kaydedilen her istek yeni değeri hemen alır. Sonra nasıl sızdığını öğrenin: depolarınızda ve CI günlüklerinizde sızmış API anahtarları için bir sır tarayıcısı çalıştırmak, başka hiçbir şeyin açığa çıkmadığını teyit etmenin en hızlı yoludur.

Kod yazmadan sorguları deneyebilir miyim?

Evet. Kontrol paneli, anlık sorgular için bir Playground sayfası içerir ve Apidog'un istek oluşturucusu, isteğin kaydedilmesi ve daha sonra test edilebilir olması ek avantajıyla aynı şeyi yapar.

Sonraki Adım

Bir hesabınız, aktif bir planınız, adlandırılmış bir anahtarınız ve üç istemciden gerçek sonuçlar döndüren bir isteğiniz var. Buradan, ya anahtarı MCP sunucusu aracılığıyla bir aracıya bağlayın ya da Apidog test senaryosunu oluşturun, böylece anahtar değişimi ve kota tükenmesi kullanıcılarınız fark etmeden önce yakalanır. Her ikisi de bugün ayarladığınız aynı `X-Subscription-Token` başlığıyla başlar.