Como Obter a Chave API do Brave Search e Fazer Sua Primeira Consulta

Uma chave de API Brave oferece acesso programático ao índice web independente da Brave: os mesmos resultados que o Brave Search serve no navegador, retornados como JSON que você pode alimentar em scripts, dashboards ou agentes de IA. A API Brave Search tornou-se uma escolha comum para dar acesso à web em tempo real a agentes; se esse é seu objetivo final, o guia do servidor MCP do Brave Search mostra como a chave se conecta ao Claude e outros clientes MCP. Este post cobre a parte anterior a isso: criar a conta, escolher um plano, gerar a chave e enviar uma consulta real com curl, Python e Apidog.

Tudo abaixo vem da própria documentação do painel da Brave a partir de setembro de 2026. Preços e limites mudam, então trate os números como um instantâneo e verifique as páginas linkadas antes de orçar.

O que você precisa antes de começar

• Um endereço de e-mail para a conta do painel.
• Um cartão de crédito. A Brave exige um em todos os planos, incluindo o nível de crédito gratuito, como uma verificação antifraude. O FAQ na página de planos afirma que, para planos gratuitos, o cartão é usado apenas para confirmar sua identidade.
• curl, ou Python 3 com o pacote `requests`, para os exemplos de linha de comando.
• Apidog, se você quiser armazenar a chave com segurança e transformar a solicitação em um teste repetível. É opcional para a primeira chamada.

Passo 1: Crie uma conta da API Brave Search

Vá para o painel da API Brave Search e registre-se com um endereço de e-mail e senha. A Brave envia um link de confirmação; clique nele para verificar o endereço. Até que você o faça, não poderá ativar um plano.

O painel é separado de qualquer navegador Brave ou login do Brave Rewards, então uma conta de navegador existente não será transferida. Registre-se do zero.

Passo 2: Escolha um plano (a camada gratuita tem uma pegadinha)

Abra a página de Planos no painel. A partir de setembro de 2026, a página de preços da Brave lista estas opções:

Para pesquisa na web, escolha Search. O crédito mensal de US$ 5 cobre aproximadamente 1.000 requisições de busca na web antes que você pague algo, o que é suficiente para desenvolvimento e pequenas cargas de trabalho de agentes. A cobrança é pré-paga: você compra créditos antecipadamente, e o crédito gratuito mensal é aplicado automaticamente.

A pegadinha é o cartão. Você não pode ativar nenhum plano, incluindo o crédito gratuito, sem inserir um. Se você viu guias mais antigos descrevendo um plano gratuito sem cartão com uma cota de consulta mensal fixa, eles descrevem uma geração anterior dos preços da Brave. Novas contas obtêm o modelo de crédito acima.

Selecione o plano e insira os detalhes do seu cartão. O plano aparece como ativo no painel imediatamente.

Passo 3: Crie a chave de API

Com um plano ativo, abra a seção Chaves de API, clique em “Adicionar Chave de API” e dê à chave um nome descritivo. O guia de início rápido da Brave sugere nomes como “Aplicativo de Produção” ou “Desenvolvimento”. Uma chave por ambiente compensa mais tarde, quando você precisar revogar uma única chave sem tocar nas outras.

Copie a chave e armazene-a em um local seguro imediatamente. O guia de autenticação da Brave é direto sobre onde ela não deve ir: código do lado do cliente, repositórios públicos ou qualquer local público. Se você é novo em como essas credenciais funcionam, o guia sobre o que é uma chave de API aborda o modelo em poucos minutos.

Passo 4: Envie sua primeira solicitação de pesquisa

O endpoint de busca na web é https://api.search.brave.com/res/v1/web/search. Toda solicitação precisa da chave em um cabeçalho X-Subscription-Token. Observe o nome do cabeçalho: não é Authorization: Bearer, e enviar a chave dessa forma falha.

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 limita os resultados por página (máx. 20, padrão 20), offset pagina por eles (base 0, máx. 9) e freshness filtra por idade: pd, pw, pm ou py para o último dia, semana, mês ou ano. Outros parâmetros úteis são country (código de duas letras), search_lang e safesearch (off, moderate ou strict; moderate é o padrão).

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

A resposta contém um objeto query (com original e um booleano more_results_available para paginação) e um array web.results. Cada resultado tem title, url e description; defina extra_snippets=true e você obterá até cinco trechos extras por resultado, o que ajuda ao construir contexto para um modelo.

A Brave versiona a API com um cabeçalho opcional Api-Version no formato AAAA-MM-DD. Deixe-o de fora e você obterá a versão mais recente; fixe-o depois que sua integração estiver em produção para que uma futura alteração que quebre a compatibilidade não chegue sem aviso.

Passo 5: Teste a chave no Apidog

Colar uma chave em um comando curl de uma linha é bom para um primeiro uso. É um péssimo lugar para deixá-la. No Apidog, você armazena a chave uma vez como uma variável, a referencia em todos os lugares e mantém o segredo fora do projeto compartilhado.

1. Abra o gerenciamento de ambiente no canto superior direito do seu projeto Apidog e adicione um ambiente chamado Brave. Crie uma variável chamada brave_api_key e coloque a chave real no campo de valor local, não no valor compartilhado. Valores locais permanecem na sua máquina e nunca sincronizam com colegas de equipe; a referência de variáveis explica o modelo de dois valores, e o fluxo de trabalho completo para ambientes e variáveis secretas no Apidog cobre layouts de desenvolvimento, staging e produção se você precisar de mais de um.
2. Crie uma nova solicitação GET para https://api.search.brave.com/res/v1/web/search. Na aba Cabeçalhos, adicione X-Subscription-Token com o valor {{brave_api_key}}. Em Parâmetros, adicione q, count e freshness.
3. Clique em Enviar. O painel de resposta mostra o corpo JSON, e o painel de cabeçalhos mostra X-RateLimit-Remaining e X-RateLimit-Reset, para que você possa monitorar sua cota sem imprimir nada.
4. Adicione asserções: o código de status é igual a 200, $.web.results existe e tem pelo menos um elemento, e $.query.original corresponde à consulta que você enviou. Salve a solicitação em um cenário de teste. Agora, uma rotação de chave ou uma alteração no lado da Brave aparece como uma execução vermelha em vez de um agente quebrado às 2 da manhã.

Baixe o Apidog para acompanhar; o plano gratuito cobre quatro usuários e inclui ambientes e cenários de teste.

Limites de taxa e como a Brave os reporta

Toda resposta carrega quatro cabeçalhos, documentados no guia de limitação de taxa da Brave:

• X-RateLimit-Limit: os limites anexados ao seu plano, por exemplo 1, 15000.
• X-RateLimit-Policy: os mesmos limites com tamanhos de janela em segundos, por exemplo 1;w=1, 15000;w=2592000 (uma janela de um segundo e uma janela de 30 dias).
• X-RateLimit-Remaining: o que resta em cada janela.
• X-RateLimit-Reset: segundos até que cada janela seja redefinida.

Dois detalhes são importantes para o orçamento. Primeiro, o guia afirma que apenas respostas bem-sucedidas e sem erro contam contra a cota, então uma explosão de 422s devido a um erro de digitação não consome créditos. Segundo, o valor por segundo nesses cabeçalhos de exemplo (1 requisição por segundo) é a ilustração da documentação, não as 50 requisições por segundo anunciadas no plano Search. Leia seus próprios cabeçalhos em vez de presumir.

Erros comuns e o que fazer

Falha de autenticação em uma chave nova. O guia de autenticação da Brave diz que toda solicitação deve conter X-Subscription-Token, e um valor ausente ou inválido é rejeitado. Isso geralmente se manifesta como HTTP 401 com um código de erro de token inválido, embora a referência da API da Brave não detalhe o status. Verifique três coisas: o nome do cabeçalho está exato (não Authorization), a chave foi copiada sem espaços em branco à direita e um plano está ativo na conta. Se você não tem certeza por que esse esquema difere da autenticação bearer, consulte Chave de API vs. Token Bearer.

422 Unprocessable Entity. Um parâmetro está fora do intervalo ou malformado: count acima de 20, offset acima de 9, um valor freshness não reconhecido ou um q vazio. O corpo segue o esquema de erro da Brave:

{
  "type": "ErrorResponse",
  "error": {
    "id": "<ID de ocorrência único>",
    "status": 422,
    "code": "<código de erro da aplicação>",
    "detail": "<o que deu errado>",
    "meta": {}
  },
  "time": 0
}

Leia error.detail; ele nomeia o campo.

429 Too Many Requests. Você atingiu a janela por segundo ou ficou sem créditos. A Brave documenta tanto RATE_LIMITED quanto QUOTA_LIMITED como códigos de erro, então verifique qual você obteve: esperar o número de segundos em X-RateLimit-Reset e tentar novamente com backoff (a Brave sugere 1s, 2s, 4s) resolve o primeiro, e apenas recarregar créditos ou esperar a redefinição mensal resolve o segundo.

FAQ

A API Brave Search é gratuita?

Parcialmente. Todo plano recebe US$ 5 em créditos por mês, o que equivale a cerca de 1.000 requisições de pesquisa. Além disso, você paga US$ 5,00 por 1.000 requisições. Não há como ativar um plano sem um cartão de crédito, mesmo que você nunca exceda o crédito.

Preciso de chaves separadas para busca na web e o endpoint de Contexto LLM?

A referência da API da Brave descreve o token como gerado “para o produto”, o que sugere que uma chave está vinculada à assinatura sob a qual foi criada. Se uma chave que funciona em /web/search falhar em /llm/context ou no endpoint Answers, verifique a qual plano a chave pertence no painel antes de assumir que a chave está quebrada.

E se minha chave de API Brave vazar?

Revogue-a na seção Chaves de API, gere um substituto e atualize a variável no Apidog para que todas as solicitações salvas usem o novo valor de uma vez. Depois, descubra como ela vazou: executar um scanner de segredos para chaves de API vazadas em seus repositórios e logs de CI é a maneira mais rápida de confirmar que nada mais está exposto.

Posso tentar consultas sem escrever código?

Sim. O painel inclui uma página de Playground para consultas ad-hoc, e o construtor de solicitações do Apidog faz o mesmo com o benefício adicional de que a solicitação é salva e testável posteriormente.

Próximo passo

Você tem uma conta, um plano ativo, uma chave nomeada e uma solicitação que retorna resultados reais de três clientes. A partir daqui, você pode conectar a chave a um agente por meio do servidor MCP, ou construir o cenário de teste do Apidog para que a rotação de chaves e o esgotamento de cotas sejam detectados antes que seus usuários percebam. Ambos começam com o mesmo cabeçalho X-Subscription-Token que você configurou hoje.