Brave Search API Schlüssel erhalten und erste Suchanfrage ausführen

Ein Brave API-Schlüssel bietet Ihnen programmatischen Zugriff auf Braves unabhängigen Web-Index: dieselben Ergebnisse, die Brave Search im Browser liefert, zurückgegeben als JSON, das Sie in Skripte, Dashboards oder KI-Agenten einspeisen können. Die Brave Search API ist zu einer gängigen Wahl geworden, um Agenten Live-Webzugriff zu ermöglichen; wenn das Ihr Endziel ist, zeigt der Brave Search MCP Server-Leitfaden, wie der Schlüssel in Claude und andere MCP-Clients integriert wird. Dieser Beitrag behandelt den Teil davor: die Erstellung des Kontos, die Auswahl eines Plans, die Generierung des Schlüssels und das Senden einer echten Abfrage mit curl, Python und Apidog.

Alles unten Genannte stammt aus Braves eigener Dashboard-Dokumentation vom September 2026. Preise und Limits ändern sich, daher sind die Zahlen als Momentaufnahme zu betrachten und die verlinkten Seiten vor der Budgetplanung zu prüfen.

Was Sie vor dem Start benötigen

• Eine E-Mail-Adresse für das Dashboard-Konto.
• Eine Kreditkarte. Brave benötigt sie für jeden Plan, einschließlich der Stufe mit kostenlosem Guthaben, als Betrugsschutzprüfung. Die FAQ auf der Pläne-Seite besagt, dass die Karte bei kostenlosen Plänen nur zur Bestätigung Ihrer Identität verwendet wird.
• curl oder Python 3 mit dem requests-Paket für die Befehlszeilenbeispiele.
• Apidog, wenn Sie den Schlüssel sicher speichern und die Anfrage in einen wiederholbaren Test umwandeln möchten. Für den ersten Aufruf ist es optional.

Schritt 1: Erstellen Sie ein Brave Search API-Konto

Gehen Sie zum Brave Search API-Dashboard und registrieren Sie sich mit einer E-Mail-Adresse und einem Passwort. Brave sendet einen Bestätigungslink; klicken Sie darauf, um die Adresse zu verifizieren. Bis dahin können Sie keinen Plan aktivieren.

Das Dashboard ist von jedem Brave-Browser- oder Brave Rewards-Login getrennt, sodass ein bestehendes Browser-Konto nicht übernommen wird. Registrieren Sie sich neu.

Schritt 2: Wählen Sie einen Plan (die kostenlose Stufe hat einen Haken)

Öffnen Sie die Seite „Pläne“ im Dashboard. Mit Stand September 2026 listet Braves Preisseite diese Optionen auf:

Wählen Sie für die Websuche „Search“. Das monatliche Guthaben von 5 $ deckt ungefähr 1.000 Web-Suchanfragen ab, bevor Sie etwas bezahlen müssen, was für die Entwicklung und kleine Agenten-Workloads ausreicht. Die Abrechnung erfolgt im Voraus: Sie kaufen Guthaben im Voraus, und das monatliche kostenlose Guthaben wird automatisch angewendet.

Der Haken ist die Karte. Sie können keinen Plan aktivieren, auch nicht mit kostenlosem Guthaben, ohne eine einzugeben. Wenn Sie ältere Anleitungen gesehen haben, die einen kostenlosen Plan ohne Karte mit einem festen monatlichen Abfragekontingent beschreiben, beschreiben diese eine frühere Generation von Braves Preisgestaltung. Neue Konten erhalten das oben genannte Guthabenmodell.

Wählen Sie den Plan aus und geben Sie Ihre Kartendetails ein. Der Plan wird sofort als aktiv im Dashboard angezeigt.

Schritt 3: Erstellen Sie den API-Schlüssel

Wenn ein Plan aktiv ist, öffnen Sie den Abschnitt „API Keys“, klicken Sie auf „Add API Key“ und geben Sie dem Schlüssel einen aussagekräftigen Namen. Braves Quickstart schlägt Namen wie „Production App“ oder „Development“ vor. Ein Schlüssel pro Umgebung zahlt sich später aus, wenn Sie einen einzelnen Schlüssel widerrufen müssen, ohne die anderen zu beeinflussen.

Kopieren Sie den Schlüssel und speichern Sie ihn sofort an einem sicheren Ort. Braves Authentifizierungsleitfaden ist sehr deutlich, wo er nicht hingehen darf: Client-seitiger Code, öffentliche Repositories oder jeder öffentliche Ort. Wenn Sie neu darin sind, wie diese Anmeldeinformationen funktionieren, erklärt der Primer zu was ein API-Schlüssel ist das Modell in wenigen Minuten.

Schritt 4: Senden Sie Ihre erste Suchanfrage

Der Web-Such-Endpunkt ist https://api.search.brave.com/res/v1/web/search. Jede Anfrage benötigt den Schlüssel in einem X-Subscription-Token-Header. Beachten Sie den Header-Namen: Er ist nicht Authorization: Bearer, und das Senden des Schlüssels auf diese Weise schlägt fehl.

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 begrenzt die Ergebnisse pro Seite (max. 20, Standard 20), offset blättert durch sie (0-basiert, max. 9), und freshness filtert nach Alter: pd, pw, pm oder py für den letzten Tag, Woche, Monat oder Jahr. Andere nützliche Parameter sind country (zweistelliger Code), search_lang und safesearch (off, moderate oder strict; moderate ist der Standard).

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")

Die Antwort enthält ein query-Objekt (mit original und einem booleschen more_results_available für die Paginierung) und ein web.results-Array. Jedes Ergebnis hat title, url und description; setzen Sie extra_snippets=true, und Sie erhalten bis zu fünf zusätzliche Auszüge pro Ergebnis, was hilfreich ist, wenn Sie Kontext für ein Modell aufbauen.

Brave versioniert die API mit einem optionalen Api-Version-Header im Format JJJJ-MM-TT. Lassen Sie ihn weg, und Sie erhalten die neueste Version; fixieren Sie ihn, sobald Ihre Integration in Produktion ist, damit eine zukünftige breaking change nicht ungebeten auftaucht.

Schritt 5: Testen Sie den Schlüssel in Apidog

Das Einfügen eines Schlüssels in eine einzelne curl-Zeile ist für einen ersten Treffer in Ordnung. Es ist jedoch ein schlechter Ort, ihn zu belassen. In Apidog speichern Sie den Schlüssel einmal als Variable, referenzieren ihn überall und halten das Geheimnis selbst vom gemeinsamen Projekt fern.

1. Öffnen Sie die Umgebungsverwaltung oben rechts in Ihrem Apidog-Projekt und fügen Sie eine Umgebung namens Brave hinzu. Erstellen Sie eine Variable namens brave_api_key und tragen Sie den echten Schlüssel in das Feld für den lokalen Wert ein, nicht in den geteilten Wert. Lokale Werte bleiben auf Ihrem Computer und werden niemals mit Teamkollegen synchronisiert; die Variablenreferenz erklärt das Zwei-Werte-Modell, und der vollständige Workflow für Umgebungen und geheime Variablen in Apidog behandelt Entwicklungs-, Staging- und Produktionslayouts, falls Sie mehr als eines benötigen.
2. Erstellen Sie eine neue GET-Anfrage an https://api.search.brave.com/res/v1/web/search. Fügen Sie im Tab „Headers“ X-Subscription-Token mit dem Wert {{brave_api_key}} hinzu. Fügen Sie in „Params“ q, count und freshness hinzu.
3. Klicken Sie auf „Senden“. Der Antwortbereich zeigt den JSON-Body, und der Header-Bereich zeigt X-RateLimit-Remaining und X-RateLimit-Reset, sodass Sie Ihr Kontingent überwachen können, ohne etwas auszugeben.
4. Fügen Sie Assertions hinzu: Statuscode gleich 200, $.web.results existiert und hat mindestens ein Element, und $.query.original stimmt mit der von Ihnen gesendeten Abfrage überein. Speichern Sie die Anfrage in einem Testszenario. Nun wird eine Schlüsselrotation oder eine Brave-seitige Änderung als fehlgeschlagener Testlauf angezeigt, anstatt eines defekten Agenten um 2 Uhr morgens.

Laden Sie Apidog herunter, um mitzumachen; der kostenlose Plan deckt vier Benutzer ab und beinhaltet Umgebungen und Testszenarien.

Ratenlimits und wie Brave sie meldet

Jede Antwort enthält vier Header, die in Braves Ratenlimit-Leitfaden dokumentiert sind:

• X-RateLimit-Limit: die Ihrem Plan zugeordneten Limits, zum Beispiel 1, 15000.
• X-RateLimit-Policy: dieselben Limits mit Fenstergrößen in Sekunden, zum Beispiel 1;w=1, 15000;w=2592000 (ein Ein-Sekunden-Fenster und ein 30-Tage-Fenster).
• X-RateLimit-Remaining: was in jedem Fenster übrig ist.
• X-RateLimit-Reset: Sekunden, bis jedes Fenster zurückgesetzt wird.

Zwei Details sind für die Budgetplanung wichtig. Erstens besagt der Leitfaden, dass nur erfolgreiche, fehlerfreie Antworten auf das Kontingent angerechnet werden, sodass eine Reihe von 422ern durch einen Tippfehler keine Guthaben verbraucht. Zweitens ist die Pro-Sekunden-Angabe in diesen Beispiel-Headern (1 Anfrage pro Sekunde) eine Illustration der Dokumentation und nicht die beworbenen 50 Anfragen pro Sekunde des Suchplans. Lesen Sie Ihre eigenen Header, anstatt Annahmen zu treffen.

Häufige Fehler und was zu tun ist

Authentifizierungsfehler bei einem neuen Schlüssel. Braves Authentifizierungsleitfaden besagt, dass jede Anfrage X-Subscription-Token enthalten muss, und ein fehlender oder ungültiger Wert wird abgelehnt. Dies äußert sich normalerweise als HTTP 401 mit einem Token-Invalid-Fehlercode, obwohl Braves API-Referenz den Status nicht explizit angibt. Überprüfen Sie drei Dinge: Der Header-Name ist exakt (nicht Authorization), der Schlüssel wurde ohne nachgestellte Leerzeichen kopiert und ein Plan ist auf dem Konto aktiv. Wenn Sie unsicher sind, warum dieses Schema von der Bearer-Authentifizierung abweicht, lesen Sie API-Schlüssel vs. Bearer-Token.

422 Unprocessable Entity. Ein Parameter liegt außerhalb des Bereichs oder ist fehlerhaft: count über 20, offset über 9, ein unbekannter freshness-Wert oder ein leeres q. Der Body folgt Braves Fehlerschema:

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

Lesen Sie error.detail; es benennt das Feld.

429 Too Many Requests. Sie haben das Pro-Sekunden-Fenster erreicht oder Ihr Guthaben ist aufgebraucht. Brave dokumentiert sowohl RATE_LIMITED als auch QUOTA_LIMITED als Fehlercodes, überprüfen Sie also, welchen Sie erhalten haben: Das Warten der in X-RateLimit-Reset angegebenen Sekunden und ein erneuter Versuch mit Backoff (Brave schlägt 1s, 2s, 4s vor) behebt den ersten Fall, und nur das Aufladen des Guthabens oder das Warten auf die monatliche Rücksetzung behebt den zweiten.

FAQ

Ist die Brave Search API kostenlos?

Teilweise. Jeder Plan erhält monatlich 5 $ Guthaben, was etwa 1.000 Suchanfragen entspricht. Darüber hinaus zahlen Sie 5,00 $ pro 1.000 Anfragen. Es gibt keine Möglichkeit, einen Plan ohne Kreditkarte zu aktivieren, selbst wenn Sie das Guthaben nie überschreiten.

Benötige ich separate Schlüssel für die Websuche und den LLM-Kontext-Endpunkt?

Brave's API-Referenz beschreibt den Token als "für das Produkt" generiert, was darauf hindeutet, dass ein Schlüssel an das Abonnement gebunden ist, unter dem er erstellt wurde. Wenn ein Schlüssel, der auf /web/search funktioniert, bei /llm/context oder dem Answers-Endpunkt fehlschlägt, überprüfen Sie, welchem Plan der Schlüssel im Dashboard angehört, bevor Sie davon ausgehen, dass der Schlüssel defekt ist.

Was, wenn mein Brave API-Schlüssel leckt?

Widerrufen Sie ihn im Abschnitt „API Keys“, generieren Sie einen Ersatz und aktualisieren Sie die Variable in Apidog, damit jede gespeicherte Anfrage sofort den neuen Wert übernimmt. Finden Sie dann heraus, wie er durchgesickert ist: Das Ausführen eines Secret-Scanners für geleakte API-Schlüssel über Ihre Repos und CI-Logs ist der schnellste Weg, um zu bestätigen, dass nichts anderes exponiert ist.

Kann ich Abfragen testen, ohne Code zu schreiben?

Ja. Das Dashboard enthält eine „Playground“-Seite für Ad-hoc-Abfragen, und der Anfrage-Builder von Apidog macht dasselbe mit dem zusätzlichen Vorteil, dass die Anfrage gespeichert und danach testbar ist.

Nächster Schritt

Sie haben ein Konto, einen aktiven Plan, einen benannten Schlüssel und eine Anfrage, die von drei Clients echte Ergebnisse zurückliefert. Von hier aus können Sie den Schlüssel entweder über den MCP-Server in einen Agenten integrieren oder das Apidog-Testszenario ausbauen, damit Schlüsselrotation und Quotenerschöpfung abgefangen werden, bevor Ihre Benutzer es bemerken. Beides beginnt mit demselben X-Subscription-Token-Header, den Sie heute eingerichtet haben.