Comment obtenir une clé API Brave Search et lancer votre première recherche

Une clé API Brave vous donne un accès programmatique à l'index web indépendant de Brave : les mêmes résultats que Brave Search fournit dans le navigateur, renvoyés sous forme de JSON que vous pouvez intégrer dans des scripts, des tableaux de bord ou des agents IA. L'API Brave Search est devenue un choix courant pour donner aux agents un accès web en direct ; si c'est votre objectif final, le guide du serveur MCP de Brave Search montre comment la clé s'intègre à Claude et à d'autres clients MCP. Ce billet couvre la partie précédente : la création du compte, le choix d'un plan, la génération de la clé et l'envoi d'une requête réelle avec curl, Python et Apidog.

Tout ce qui suit provient de la documentation du tableau de bord de Brave, en date de septembre 2026. Les prix et les limites changent, considérez donc les chiffres comme un instantané et consultez les pages liées avant d'établir votre budget.

Ce dont vous avez besoin avant de commencer

Une adresse e-mail pour le compte du tableau de bord.
Une carte de crédit. Brave en exige une pour chaque plan, y compris le niveau de crédits gratuits, comme mesure anti-fraude. La FAQ sur la page des plans stipule que pour les plans gratuits, la carte est uniquement utilisée pour confirmer votre identité.
curl, ou Python 3 avec le package `requests`, pour les exemples en ligne de commande.
Apidog, si vous souhaitez stocker la clé en toute sécurité et transformer la requête en un test reproductible. C'est facultatif pour le premier appel.

Étape 1 : Créer un compte API Brave Search

Rendez-vous sur le tableau de bord de l'API Brave Search et inscrivez-vous avec une adresse e-mail et un mot de passe. Brave enverra un lien de confirmation ; cliquez dessus pour vérifier l'adresse. Tant que vous ne le faites pas, vous ne pourrez pas activer de plan.

Le tableau de bord est distinct de tout navigateur Brave ou connexion Brave Rewards, donc un compte de navigateur existant ne sera pas transféré. Inscrivez-vous de nouveau.

Étape 2 : Choisir un plan (le niveau gratuit a un inconvénient)

Ouvrez la page Plans dans le tableau de bord. En septembre 2026, la page des tarifs de Brave liste les options suivantes :

Plan	Prix	Crédit gratuit	Limite de débit
Recherche	5,00 $ par 1 000 requêtes	5 $ en crédits chaque mois	50 requêtes par seconde
Réponses	4,00 $ par 1 000 requêtes, plus 5,00 $ par 1 000 000 de jetons d'entrée et 5,00 $ par 1 000 000 de jetons de sortie	5 $ en crédits chaque mois	2 requêtes par seconde
Correction orthographique	5,00 $ par 10 000 requêtes	5 $ en crédits chaque mois	100 requêtes par seconde
Suggestions automatiques	5,00 $ par 10 000 requêtes	5 $ en crédits chaque mois	100 requêtes par seconde
Entreprise	Personnalisé	Contacter les ventes	Personnalisé

Pour la recherche web, choisissez "Recherche". Le crédit mensuel de 5 $ couvre environ 1 000 requêtes de recherche web avant que vous ne payiez quoi que ce soit, ce qui est suffisant pour le développement et les petites charges de travail d'agents. La facturation est prépayée : vous achetez des crédits à l'avance, et le crédit gratuit mensuel est appliqué automatiquement.

L'inconvénient est la carte. Vous ne pouvez activer aucun plan, crédit gratuit inclus, sans en saisir une. Si vous avez vu d'anciens guides décrivant un plan gratuit sans carte avec un quota de requêtes mensuel fixe, ils décrivent une génération précédente des tarifs de Brave. Les nouveaux comptes bénéficient du modèle de crédit ci-dessus.

Sélectionnez le plan et saisissez les détails de votre carte. Le plan s'affiche comme actif dans le tableau de bord immédiatement.

Étape 3 : Créer la clé API

Une fois qu'un plan est actif, ouvrez la section Clés API, cliquez sur « Ajouter une clé API » et donnez un nom descriptif à la clé. Le guide de démarrage rapide de Brave suggère des noms comme « Application de production » ou « Développement ». Une clé par environnement est rentable plus tard, lorsque vous devez révoquer une seule clé sans toucher aux autres.

Copiez la clé et stockez-la en lieu sûr immédiatement. Le guide d'authentification de Brave est catégorique sur les endroits où elle ne doit pas aller : code côté client, dépôts publics ou tout emplacement public. Si vous débutez dans le fonctionnement de ces identifiants, l'introduction sur ce qu'est une clé API couvre le modèle en quelques minutes.

Étape 4 : Envoyer votre première requête de recherche

Le point de terminaison de la recherche web est `https://api.search.brave.com/res/v1/web/search`. Chaque requête nécessite la clé dans un en-tête `X-Subscription-Token`. Notez le nom de l'en-tête : ce n'est pas `Authorization: Bearer`, et l'envoi de la clé de cette manière échouera.

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 limite les résultats par page (max 20, par défaut 20), offset permet de paginer (base 0, max 9), et freshness filtre par âge : pd, pw, pm ou py pour le dernier jour, semaine, mois ou année. D'autres paramètres utiles sont country (code à deux lettres), search_lang et safesearch (off, moderate ou strict ; moderate est la valeur par défaut).

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

La réponse contient un objet `query` (avec `original` et un booléen `more_results_available` pour la pagination) et un tableau `web.results`. Chaque résultat contient `title`, `url` et `description` ; définissez `extra_snippets=true` et vous obtiendrez jusqu'à cinq extraits supplémentaires par résultat, ce qui est utile pour créer un contexte pour un modèle.

Brave versionne l'API avec un en-tête `Api-Version` facultatif sous la forme `AAAA-MM-JJ`. Omettez-le et vous obtiendrez la dernière version ; fixez-le une fois votre intégration en production afin qu'un futur changement potentiellement destructeur n'arrive pas sans préavis.

Étape 5 : Tester la clé dans Apidog

Coller une clé dans une commande curl en une ligne est acceptable pour un premier essai. Ce n'est pas un bon endroit pour la laisser. Dans Apidog, vous stockez la clé une fois comme variable, la référencez partout, et gardez le secret lui-même en dehors du projet partagé.

Ouvrez la gestion de l'environnement en haut à droite de votre projet Apidog et ajoutez un environnement appelé `Brave`. Créez une variable nommée `brave_api_key` et placez la vraie clé dans le champ de valeur locale, pas la valeur partagée. Les valeurs locales restent sur votre machine et ne sont jamais synchronisées avec vos coéquipiers ; la référence des variables explique le modèle à deux valeurs, et le flux de travail complet pour les environnements et variables secrètes dans Apidog couvre les configurations de développement, de staging et de production si vous avez besoin de plus d'une.
Créez une nouvelle requête GET vers `https://api.search.brave.com/res/v1/web/search`. Dans l'onglet Headers, ajoutez `X-Subscription-Token` avec la valeur `{{brave_api_key}}`. Dans Params, ajoutez `q`, `count` et `freshness`.
Cliquez sur Envoyer. Le panneau de réponse affiche le corps JSON, et le panneau des en-têtes affiche `X-RateLimit-Remaining` et `X-RateLimit-Reset`, ce qui vous permet de surveiller votre quota sans rien imprimer.
Ajoutez des assertions : le code de statut est égal à 200, `$.web.results` existe et contient au moins un élément, et `$.query.original` correspond à la requête que vous avez envoyée. Enregistrez la requête dans un scénario de test. Désormais, une rotation de clé ou un changement côté Brave apparaîtra comme un échec (une "course rouge") au lieu d'un agent défaillant à 2 heures du matin.

Téléchargez Apidog pour suivre ; le plan gratuit couvre quatre utilisateurs et inclut les environnements et les scénarios de test.

Limites de débit et comment Brave les signale

Chaque réponse contient quatre en-têtes, documentés dans le guide des limites de débit de Brave :

`X-RateLimit-Limit` : les limites associées à votre plan, par exemple `1, 15000`.
`X-RateLimit-Policy` : les mêmes limites avec des tailles de fenêtre en secondes, par exemple `1;w=1, 15000;w=2592000` (une fenêtre d'une seconde et une fenêtre de 30 jours).
`X-RateLimit-Remaining` : ce qui reste dans chaque fenêtre.
`X-RateLimit-Reset` : secondes avant que chaque fenêtre ne se réinitialise.

Deux détails sont importants pour la budgétisation. Premièrement, le guide indique que seules les réponses réussies et sans erreur sont comptabilisées dans le quota, donc une rafale de 422 provenant d'une faute de frappe ne consomme pas de crédits. Deuxièmement, le chiffre par seconde dans ces en-têtes d'exemple (1 requête par seconde) est une illustration de la documentation, et non les 50 requêtes par seconde annoncées pour le plan de recherche. Lisez vos propres en-têtes au lieu de faire des suppositions.

Erreurs courantes et que faire

Échec d'authentification sur une nouvelle clé. Le guide d'authentification de Brave indique que chaque requête doit contenir `X-Subscription-Token`, et qu'une valeur manquante ou invalide est rejetée. Cela se manifeste généralement par un code d'état HTTP 401 avec un code d'erreur "jeton invalide", bien que la référence API de Brave ne précise pas le statut. Vérifiez trois choses : le nom de l'en-tête est exact (pas `Authorization`), la clé a été copiée sans espace de fin, et un plan est actif sur le compte. Si vous n'êtes pas sûr de la raison pour laquelle ce schéma diffère de l'authentification par jeton de porteur, consultez Clé API vs jeton de porteur.

422 Entité non traitable (Unprocessable Entity). Un paramètre est hors limites ou mal formé : `count` supérieur à 20, `offset` supérieur à 9, une valeur `freshness` non reconnue, ou un `q` vide. Le corps suit le schéma d'erreur de Brave :

{
  "type": "ErrorResponse",
  "error": {
    "id": "<identifiant unique de l'occurrence>",
    "status": 422,
    "code": "<code d'erreur de l'application>",
    "detail": "<ce qui n'a pas fonctionné>",
    "meta": {}
  },
  "time": 0
}

Lisez `error.detail` ; il indique le champ concerné.

429 Trop de requêtes (Too Many Requests). Vous avez atteint la fenêtre par seconde ou vous avez épuisé vos crédits. Brave documente à la fois `RATE_LIMITED` et `QUOTA_LIMITED` comme codes d'erreur, alors vérifiez lequel vous avez obtenu : attendre le nombre de secondes dans `X-RateLimit-Reset` et réessayer avec une temporisation exponentielle (Brave suggère 1s, 2s, 4s) corrige le premier, et seul le rechargement de crédits ou l'attente de la réinitialisation mensuelle corrige le second.

FAQ

L'API Brave Search est-elle gratuite ?

En partie. Chaque plan reçoit 5 $ de crédits chaque mois, ce qui correspond à environ 1 000 requêtes de recherche. Au-delà, vous payez 5,00 $ par tranche de 1 000 requêtes. Il n'est pas possible d'activer un plan sans carte de crédit, même si vous ne dépassez jamais le crédit.

Ai-je besoin de clés séparées pour la recherche web et le point de terminaison du contexte LLM ?

La référence API de Brave décrit le jeton comme étant généré "pour le produit", ce qui suggère qu'une clé est liée à l'abonnement sous lequel elle a été créée. Si une clé qui fonctionne sur `/web/search` échoue sur `/llm/context` ou le point de terminaison Answers, vérifiez à quel plan la clé appartient dans le tableau de bord avant de supposer que la clé est cassée.

Que se passe-t-il si ma clé API Brave est divulguée ?

Révoquez-la dans la section Clés API, générez un remplacement et mettez à jour la variable dans Apidog afin que chaque requête enregistrée reprenne la nouvelle valeur immédiatement. Ensuite, découvrez comment elle a été divulguée : exécuter un scanner de secrets pour les clés API divulguées sur vos dépôts et vos journaux CI est le moyen le plus rapide de confirmer que rien d'autre n'est exposé.

Puis-je essayer des requêtes sans écrire de code ?

Oui. Le tableau de bord inclut une page "Aire de jeux" pour les requêtes ad hoc, et le constructeur de requêtes d'Apidog fait de même avec l'avantage supplémentaire que la requête est enregistrée et testable par la suite.

Étape suivante

Vous avez un compte, un plan actif, une clé nommée et une requête qui renvoie des résultats réels depuis trois clients. À partir de là, vous pouvez soit connecter la clé à un agent via le serveur MCP, soit élaborer le scénario de test Apidog afin que la rotation des clés et l'épuisement des quotas soient détectés avant que vos utilisateurs ne le remarquent. Les deux commencent par le même en-tête `X-Subscription-Token` que vous avez configuré aujourd'hui.