Una clave de API de Brave le brinda acceso programático al índice web independiente de Brave: los mismos resultados que Brave Search ofrece en el navegador, devueltos como JSON que puede usar en scripts, paneles o agentes de IA. La API de Brave Search se ha convertido en una opción común para dar acceso web en vivo a los agentes; si ese es su objetivo final, la guía del servidor MCP de Brave Search muestra cómo la clave se conecta a Claude y otros clientes MCP. Esta publicación cubre la parte anterior: crear la cuenta, elegir un plan, generar la clave y enviar una consulta real con curl, Python y Apidog.
Todo lo que se detalla a continuación proviene de la propia documentación del panel de Brave a partir de septiembre de 2026. Los precios y los límites cambian, así que considere los números como una instantánea y consulte las páginas vinculadas antes de presupuestar.
Lo que necesita antes de empezar
- Una dirección de correo electrónico para la cuenta del panel de control.
- Una tarjeta de crédito. Brave la requiere en todos los planes, incluido el nivel de crédito gratuito, como una verificación antifraude. Las Preguntas Frecuentes en la página de planes establecen que para los planes gratuitos la tarjeta solo se usa para confirmar su identidad.
- curl, o Python 3 con el paquete
requests, para los ejemplos de línea de comandos. - Apidog, si desea almacenar la clave de forma segura y convertir la solicitud en una prueba repetible. Es opcional para la primera llamada.
Paso 1: Cree una cuenta de API de Brave Search
Vaya al panel de control de la API de Brave Search y regístrese con una dirección de correo electrónico y una contraseña. Brave envía un enlace de confirmación; haga clic en él para verificar la dirección. Hasta que lo haga, no podrá activar un plan.
El panel es independiente de cualquier navegador Brave o inicio de sesión de Brave Rewards, por lo que una cuenta de navegador existente no se transferirá. Regístrese desde cero.
Paso 2: Elija un plan (el nivel gratuito tiene una trampa)
Abra la página de Planes en el panel de control. A partir de septiembre de 2026, la página de precios de Brave enumera estas opciones:
| Plan | Precio | Crédito gratuito | Límite de solicitudes |
|---|---|---|---|
| Búsqueda (Search) | $5.00 por 1,000 solicitudes | $5 en créditos cada mes | 50 solicitudes por segundo |
| Respuestas (Answers) | $4.00 por 1,000 consultas, más $5.00 por 1,000,000 de tokens de entrada y $5.00 por 1,000,000 de tokens de salida | $5 en créditos cada mes | 2 solicitudes por segundo |
| Corrector ortográfico (Spellcheck) | $5.00 por 10,000 solicitudes | $5 en créditos cada mes | 100 solicitudes por segundo |
| Autosugerencia (Autosuggest) | $5.00 por 10,000 solicitudes | $5 en créditos cada mes | 100 solicitudes por segundo |
| Empresarial (Enterprise) | Personalizado | Contactar a ventas | Personalizado |
Para la búsqueda web, elija Search. El crédito mensual de $5 cubre aproximadamente 1,000 solicitudes de búsqueda web antes de que pague algo, lo cual es suficiente para el desarrollo y cargas de trabajo de agentes pequeños. La facturación es prepaga: usted compra créditos por adelantado, y el crédito mensual gratuito se aplica automáticamente.
La trampa es la tarjeta. No puede activar ningún plan, incluido el crédito gratuito, sin ingresar una. Si ha visto guías antiguas que describen un plan gratuito sin tarjeta con una cuota de consulta mensual fija, describen una generación anterior de precios de Brave. Las cuentas nuevas obtienen el modelo de crédito anterior.
Seleccione el plan e ingrese los detalles de su tarjeta. El plan se muestra como activo en el panel de control de inmediato.
Paso 3: Cree la clave de API
Con un plan activo, abra la sección "API Keys", haga clic en "Add API Key" y asigne un nombre descriptivo a la clave. La guía de inicio rápido de Brave sugiere nombres como "Aplicación de Producción" o "Desarrollo". Una clave por entorno vale la pena más tarde, cuando necesite revocar una sola clave sin tocar las otras.
Copie la clave y guárdela en un lugar seguro de inmediato. La guía de autenticación de Brave es clara sobre dónde no debe ir: código del lado del cliente, repositorios públicos o cualquier ubicación pública. Si es nuevo en cómo funcionan estas credenciales, la introducción sobre qué es una clave de API cubre el modelo en unos minutos.
Paso 4: Envíe su primera solicitud de búsqueda
El punto final de búsqueda web es https://api.search.brave.com/res/v1/web/search. Cada solicitud necesita la clave en un encabezado X-Subscription-Token. Tenga en cuenta el nombre del encabezado: no es Authorization: Bearer, y enviar la clave de esa manera fallará.
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 los resultados por página (máximo 20, predeterminado 20), offset los pagina (base 0, máximo 9) y freshness filtra por antigüedad: pd, pw, pm o py para el último día, semana, mes o año. Otros parámetros útiles son country (código de dos letras), search_lang y safesearch (off, moderate o strict; moderate es el predeterminado).
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 respuesta contiene un objeto query (con original y un booleano more_results_available para paginación) y un array web.results. Cada resultado tiene title, url y description; establezca extra_snippets=true y obtendrá hasta cinco extractos adicionales por resultado, lo que ayuda cuando está construyendo contexto para un modelo.
Brave versiona la API con un encabezado Api-Version opcional en formato YYYY-MM-DD. Si lo omite, obtendrá la última versión; fíjelo una vez que su integración esté en producción para que un cambio brusco futuro no llegue sin ser invitado.
Paso 5: Pruebe la clave en Apidog
Pegar una clave en una línea de comando de curl está bien para una primera prueba. Es un mal lugar para dejarla. En Apidog, almacena la clave una vez como una variable, la referencia en todas partes y mantiene el secreto fuera del proyecto compartido.
- Abra la gestión de entornos en la parte superior derecha de su proyecto de Apidog y agregue un entorno llamado
Brave. Cree una variable llamadabrave_api_keyy coloque la clave real en el campo de valor local, no en el valor compartido. Los valores locales permanecen en su máquina y nunca se sincronizan con los compañeros de equipo; la referencia de variables explica el modelo de dos valores, y el flujo de trabajo completo para entornos y variables secretas en Apidog cubre diseños de desarrollo, staging y producción si necesita más de uno. - Cree una nueva solicitud GET a
https://api.search.brave.com/res/v1/web/search. En la pestaña Headers, agregueX-Subscription-Tokencon el valor{{brave_api_key}}. En Params, agregueq,countyfreshness. - Haga clic en Enviar. El panel de respuesta muestra el cuerpo JSON, y el panel de encabezados muestra
X-RateLimit-RemainingyX-RateLimit-Reset, para que pueda monitorear su cuota sin imprimir nada. - Agregue aserciones: el código de estado es igual a 200,
$.web.resultsexiste y tiene al menos un elemento, y$.query.originalcoincide con la consulta que envió. Guarde la solicitud en un escenario de prueba. Ahora, una rotación de clave o un cambio por parte de Brave aparece como un error en lugar de un agente roto a las 2 a.m.
Descargue Apidog para seguir los pasos; el plan gratuito cubre cuatro usuarios e incluye entornos y escenarios de prueba.
Límites de tasa y cómo los informa Brave
Cada respuesta incluye cuatro encabezados, documentados en la guía de límites de tasa de Brave:
X-RateLimit-Limit: los límites asociados a su plan, por ejemplo1, 15000.X-RateLimit-Policy: los mismos límites con tamaños de ventana en segundos, por ejemplo1;w=1, 15000;w=2592000(una ventana de un segundo y una ventana de 30 días).X-RateLimit-Remaining: lo que queda en cada ventana.X-RateLimit-Reset: segundos hasta que cada ventana se reinicia.
Dos detalles son importantes para el presupuesto. Primero, la guía establece que solo las respuestas exitosas y sin errores cuentan para la cuota, por lo que una ráfaga de 422s debido a un error tipográfico no consume créditos. Segundo, la cifra por segundo en esos encabezados de ejemplo (1 solicitud por segundo) es la ilustración del documento, no las 50 solicitudes por segundo anunciadas en el plan Search. Lea sus propios encabezados en lugar de asumir.
Errores comunes y qué hacer
Fallo de autenticación en una clave nueva. La guía de autenticación de Brave dice que cada solicitud debe llevar X-Subscription-Token, y un valor faltante o inválido es rechazado. Esto generalmente se manifiesta como HTTP 401 con un código de error de token inválido, aunque la referencia de la API de Brave no especifica el estado. Verifique tres cosas: el nombre del encabezado es exacto (no Authorization), la clave se copió sin espacios en blanco al final, y un plan está activo en la cuenta. Si no está seguro de por qué este esquema difiere de la autenticación de portador, consulte clave de API vs token de portador.
422 Entidad no procesable. Un parámetro está fuera de rango o mal formado: count superior a 20, offset superior a 9, un valor freshness no reconocido o una q vacía. El cuerpo sigue el esquema de error de Brave:
{
"type": "ErrorResponse",
"error": {
"id": "<ID de ocurrencia único>",
"status": 422,
"code": "<código de error de la aplicación>",
"detail": "<qué salió mal>",
"meta": {}
},
"time": 0
}
Lea error.detail; nombra el campo.
429 Demasiadas solicitudes. Alcanzó el límite por segundo o se quedó sin créditos. Brave documenta RATE_LIMITED y QUOTA_LIMITED como códigos de error, así que verifique cuál obtuvo: esperar el número de segundos en X-RateLimit-Reset y reintentar con retroceso exponencial (Brave sugiere 1s, 2s, 4s) soluciona el primero, y solo recargar créditos o esperar el restablecimiento mensual soluciona el segundo.
Preguntas frecuentes
¿Es gratuita la API de Brave Search?
Parcialmente. Cada plan recibe $5 en créditos cada mes, lo que equivale a unas 1,000 solicitudes de búsqueda. Más allá de eso, se paga $5.00 por cada 1,000 solicitudes. No hay forma de activar un plan sin una tarjeta de crédito, incluso si nunca excede el crédito.
¿Necesito claves separadas para la búsqueda web y el endpoint de contexto LLM?
La referencia de la API de Brave describe el token como generado "para el producto", lo que sugiere que una clave está ligada a la suscripción bajo la cual fue creada. Si una clave que funciona en /web/search falla en /llm/context o en el endpoint de Respuestas, verifique a qué plan pertenece la clave en el panel de control antes de asumir que la clave está rota.
¿Qué pasa si mi clave de API de Brave se filtra?
Revóquela en la sección de Claves de API, genere una de reemplazo y actualice la variable en Apidog para que cada solicitud guardada recoja el nuevo valor de inmediato. Luego, descubra cómo se filtró: ejecutar un escáner de secretos para claves de API filtradas en sus repositorios y registros de CI es la forma más rápida de confirmar que no hay nada más expuesto.
¿Puedo probar consultas sin escribir código?
Sí. El panel de control incluye una página de Playground para consultas ad-hoc, y el constructor de solicitudes de Apidog hace lo mismo con el beneficio adicional de que la solicitud se guarda y se puede probar posteriormente.
Siguiente paso
Tiene una cuenta, un plan activo, una clave con nombre y una solicitud que devuelve resultados reales de tres clientes. A partir de aquí, conecte la clave a un agente a través del servidor MCP, o construya el escenario de prueba de Apidog para que la rotación de claves y el agotamiento de la cuota se detecten antes de que sus usuarios se den cuenta. Ambos comienzan con el mismo encabezado X-Subscription-Token que configuró hoy.