Brave 검색 API 키 발급 및 첫 검색 쿼리 실행 방법

Brave API 키를 사용하면 Brave의 독립적인 웹 인덱스에 프로그래밍 방식으로 액세스할 수 있습니다. 이는 Brave Search가 브라우저에서 제공하는 것과 동일한 결과이며, 스크립트, 대시보드 또는 AI 에이전트에 공급할 수 있는 JSON 형식으로 반환됩니다. Brave 검색 API는 에이전트에 실시간 웹 액세스를 제공하기 위한 일반적인 선택이 되었습니다. 이것이 최종 목표라면, Brave 검색 MCP 서버 가이드는 해당 키가 Claude 및 다른 MCP 클라이언트에 어떻게 연결되는지 보여줍니다. 이 게시물은 그 전에 다루어야 할 부분, 즉 계정 생성, 플랜 선택, 키 생성, 그리고 curl, Python, Apidog를 사용하여 실제 쿼리를 전송하는 방법을 다룹니다.

아래 내용은 2026년 9월 기준으로 Brave 자체 대시보드 문서에서 가져온 것입니다. 가격과 제한은 변경될 수 있으므로, 이 수치들은 스냅샷으로 간주하고 예산을 책정하기 전에 링크된 페이지를 확인하세요.

시작하기 전에 필요한 것

대시보드 계정용 이메일 주소.
신용카드. Brave는 사기 방지 확인을 위해 무료 크레딧 등급을 포함한 모든 플랜에 신용카드를 요구합니다. 플랜 페이지의 FAQ에 따르면, 무료 플랜의 경우 카드는 본인 확인 용도로만 사용됩니다.
명령줄 예제를 위한 curl 또는 requests 패키지가 설치된 Python 3.
Apidog (키를 안전하게 저장하고 요청을 반복 가능한 테스트로 전환하고 싶다면). 첫 호출에는 선택 사항입니다.

1단계: Brave 검색 API 계정 생성

Brave 검색 API 대시보드로 이동하여 이메일 주소와 비밀번호로 등록하세요. Brave에서 확인 링크를 보낼 것입니다. 주소를 확인하려면 이 링크를 클릭하세요. 확인하기 전까지는 플랜을 활성화할 수 없습니다.

대시보드는 Brave 브라우저 또는 Brave Rewards 로그인과 별개이므로, 기존 브라우저 계정은 연동되지 않습니다. 새로 등록하세요.

2단계: 플랜 선택 (무료 등급에는 한 가지 함정이 있습니다)

대시보드에서 플랜 페이지를 엽니다. 2026년 9월 기준으로 Brave의 가격 페이지에는 다음과 같은 옵션이 나열되어 있습니다:

플랜	가격	무료 크레딧	요청 제한
검색	요청 1,000회당 $5.00	매월 $5 크레딧	초당 50회 요청
답변	쿼리 1,000회당 $4.00, 입력 토큰 1,000,000개당 $5.00, 출력 토큰 1,000,000개당 $5.00	매월 $5 크레딧	초당 2회 요청
맞춤법 검사	요청 10,000회당 $5.00	매월 $5 크레딧	초당 100회 요청
자동 완성	요청 10,000회당 $5.00	매월 $5 크레딧	초당 100회 요청
기업용	맞춤형	영업팀에 문의	맞춤형

웹 검색의 경우 '검색'을 선택하세요. 매월 $5의 크레딧은 약 1,000회의 웹 검색 요청을 지불 없이 처리할 수 있으며, 이는 개발 및 소규모 에이전트 작업에 충분합니다. 결제는 선불 방식입니다. 크레딧을 미리 구매하면 매월 무료 크레딧이 자동으로 적용됩니다.

함정은 카드입니다. 신용카드를 입력하지 않고는 무료 크레딧을 포함한 어떤 플랜도 활성화할 수 없습니다. 고정된 월별 쿼터가 있는 카드 없는 무료 플랜을 설명하는 이전 가이드를 보셨다면, 그것은 이전 세대의 Brave 가격 정책을 설명하는 것입니다. 새 계정에는 위에 설명된 크레딧 모델이 적용됩니다.

플랜을 선택하고 카드 정보를 입력하세요. 플랜은 대시보드에 즉시 활성 상태로 표시됩니다.

3단계: API 키 생성

활성 플랜이 있는 상태에서 API 키 섹션을 열고 "API 키 추가"를 클릭한 다음, 키에 설명적인 이름을 지정하세요. Brave의 퀵스타트 가이드에서는 "프로덕션 앱" 또는 "개발"과 같은 이름을 제안합니다. 환경당 하나의 키를 사용하면 나중에 다른 키에 영향을 주지 않고 특정 키만 해지해야 할 때 유용합니다.

키를 복사하여 즉시 안전한 곳에 보관하세요. Brave의 인증 가이드는 키를 두어서는 안 되는 장소(클라이언트 측 코드, 공개 리포지토리 또는 모든 공개 위치)에 대해 명확하게 언급하고 있습니다. 이러한 자격 증명이 어떻게 작동하는지 처음 접하는 경우, API 키란 무엇인가에 대한 기본 설명서가 몇 분 안에 모델을 다룹니다.

4단계: 첫 검색 요청 보내기

웹 검색 엔드포인트는 https://api.search.brave.com/res/v1/web/search입니다. 모든 요청은 X-Subscription-Token 헤더에 키를 포함해야 합니다. 헤더 이름을 잘 기억하세요. Authorization: Bearer가 아니며, 이런 방식으로 키를 보내면 실패합니다.

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는 페이지당 결과 수(최대 20개, 기본값 20개)를 제한하고, offset은 페이지를 넘기며(0부터 시작, 최대 9), freshness는 기간별로 필터링합니다: pd (지난 하루), pw (지난 주), pm (지난 달), 또는 py (지난 해). 다른 유용한 매개변수로는 country (두 글자 코드), search_lang, 그리고 safesearch (off, moderate 또는 strict; moderate가 기본값)가 있습니다.

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

응답은 query 객체(페이지네이션을 위한 original 및 more_results_available 불리언 포함)와 web.results 배열을 포함합니다. 각 결과에는 title, url, description이 있습니다. extra_snippets=true로 설정하면 결과당 최대 5개의 추가 발췌문을 얻을 수 있으며, 이는 모델을 위한 컨텍스트를 구축할 때 유용합니다.

Brave는 YYYY-MM-DD 형식의 선택적 Api-Version 헤더를 사용하여 API 버전을 관리합니다. 이를 생략하면 최신 버전을 얻게 됩니다. 통합이 프로덕션에 배포되면 버전을 고정하여 향후 파괴적인 변경 사항이 예기치 않게 적용되는 것을 방지하세요.

5단계: Apidog에서 키 테스트

첫 시도에 curl 한 줄 명령에 키를 붙여넣는 것은 괜찮습니다. 하지만 그 상태로 두는 것은 좋지 않습니다. Apidog에서는 키를 변수로 한 번 저장하고, 모든 곳에서 참조하며, 실제 비밀 정보를 공유 프로젝트에서 분리하여 보관할 수 있습니다.

Apidog 프로젝트 우측 상단에서 환경 관리를 열고 Brave라는 환경을 추가합니다. brave_api_key라는 변수를 생성하고 실제 키를 공유 값이 아닌 로컬 값 필드에 넣습니다. 로컬 값은 사용자 머신에만 유지되며 팀원과 동기화되지 않습니다. 변수 참조는 두 가지 값 모델을 설명하며, Apidog의 환경 및 비밀 변수에 대한 전체 워크플로는 여러 환경이 필요한 경우 개발, 스테이징, 프로덕션 레이아웃을 다룹니다.
https://api.search.brave.com/res/v1/web/search로 새로운 GET 요청을 생성합니다. 헤더 탭에서 X-Subscription-Token을 값 {{brave_api_key}}와 함께 추가합니다. Params에는 q, count, freshness를 추가합니다.
전송(Send)을 클릭합니다. 응답 창에는 JSON 본문이 표시되고, 헤더 창에는 X-RateLimit-Remaining과 X-RateLimit-Reset이 표시되어 아무것도 출력하지 않고도 할당량을 확인할 수 있습니다.
어설션(assertion)을 추가합니다: 상태 코드가 200인지, $.web.results가 존재하며 최소한 하나의 요소를 가지고 있는지, 그리고 $.query.original이 보낸 쿼리와 일치하는지 확인합니다. 요청을 테스트 시나리오로 저장합니다. 이제 키 변경이나 Brave 측의 변경 사항이 새벽 2시에 에이전트 오류가 아닌 실패한 실행으로 나타납니다.

함께 따라하려면 Apidog를 다운로드하세요. 무료 플랜은 사용자 4명까지 지원하며 환경 및 테스트 시나리오를 포함합니다.

요청 제한 및 Brave가 이를 보고하는 방법

모든 응답에는 Brave의 요청 제한 가이드에 문서화된 네 가지 헤더가 포함됩니다:

X-RateLimit-Limit: 플랜에 적용된 제한, 예를 들어 1, 15000.
X-RateLimit-Policy: 초 단위의 윈도우 크기가 포함된 동일한 제한, 예를 들어 1;w=1, 15000;w=2592000 (1초 윈도우 및 30일 윈도우).
X-RateLimit-Remaining: 각 윈도우에 남은 잔여량.
X-RateLimit-Reset: 각 윈도우가 재설정될 때까지 남은 시간(초).

예산 책정에 두 가지 중요한 세부 사항이 있습니다. 첫째, 가이드에 따르면 성공적인(오류가 아닌) 응답만 할당량에 포함되므로, 오타로 인한 422 오류가 연속적으로 발생해도 크레딧이 소모되지 않습니다. 둘째, 예시 헤더의 초당 요청 수치(초당 1회 요청)는 문서의 설명일 뿐, 검색 플랜에서 광고하는 초당 50회 요청이 아닙니다. 추정하기보다 자신의 헤더를 직접 확인하세요.

일반적인 오류 및 대처 방법

새 키에 대한 인증 실패. Brave의 인증 가이드에 따르면 모든 요청은 X-Subscription-Token을 포함해야 하며, 누락되거나 유효하지 않은 값은 거부됩니다. Brave의 API 참조에 상태가 명시되어 있지는 않지만, 일반적으로 토큰 무효 오류 코드와 함께 HTTP 401로 나타납니다. 다음 세 가지를 확인하세요: 헤더 이름이 정확한지 (Authorization이 아님), 키가 후행 공백 없이 복사되었는지, 그리고 계정에 활성 플랜이 있는지. 이 방식이 베어러 인증과 왜 다른지 확실하지 않다면 API 키 대 베어러 토큰을 참조하세요.

422 처리할 수 없는 엔티티. 매개변수가 범위를 벗어나거나 형식이 잘못된 경우입니다: count가 20을 초과하거나, offset이 9를 초과하거나, 인식할 수 없는 freshness 값, 또는 비어 있는 q. 본문은 Brave의 오류 스키마를 따릅니다:

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

error.detail을 읽으세요. 어떤 필드에 문제가 있는지 알려줍니다.

429 너무 많은 요청. 초당 요청 제한을 초과했거나 크레딧이 소진된 경우입니다. Brave는 RATE_LIMITED와 QUOTA_LIMITED를 모두 오류 코드로 문서화하므로, 어떤 오류를 받았는지 확인하세요. X-RateLimit-Reset에 명시된 시간(초)만큼 기다린 후 백오프(Brave는 1초, 2초, 4초를 제안)와 함께 재시도하면 첫 번째 문제를 해결할 수 있고, 크레딧을 충전하거나 월별 재설정을 기다려야만 두 번째 문제를 해결할 수 있습니다.

자주 묻는 질문

Brave 검색 API는 무료인가요?

부분적으로 그렇습니다. 모든 플랜은 매월 $5의 크레딧을 받으며, 이는 약 1,000회의 검색 요청에 해당합니다. 그 이상 사용하면 요청 1,000회당 $5.00를 지불해야 합니다. 크레딧을 초과하지 않더라도 신용카드 없이는 플랜을 활성화할 수 없습니다.

웹 검색과 LLM 컨텍스트 엔드포인트를 위해 별도의 키가 필요한가요?

Brave의 API 참조는 토큰이 "제품용으로" 생성된다고 설명하며, 이는 키가 생성된 구독에 연결되어 있음을 시사합니다. /web/search에서 작동하는 키가 /llm/context 또는 답변 엔드포인트에서 실패하는 경우, 키가 손상되었다고 가정하기 전에 대시보드에서 해당 키가 어떤 플랜에 속하는지 확인하세요.

Brave API 키가 유출되면 어떻게 해야 하나요?

API 키 섹션에서 키를 해지하고, 대체 키를 생성한 다음, Apidog의 변수를 업데이트하여 저장된 모든 요청이 새 값을 즉시 사용하도록 하세요. 그런 다음 키가 어떻게 유출되었는지 파악하세요. 리포지토리와 CI 로그 전반에 걸쳐 유출된 API 키에 대한 비밀 스캐너를 실행하는 것이 다른 어떤 것도 노출되지 않았음을 확인하는 가장 빠른 방법입니다.

코드를 작성하지 않고도 쿼리를 테스트할 수 있나요?

네, 가능합니다. 대시보드에는 임시 쿼리를 위한 Playground 페이지가 포함되어 있으며, Apidog의 요청 빌더도 동일한 기능을 제공합니다. 추가적인 이점은 요청이 저장되고 나중에 테스트할 수 있다는 점입니다.

다음 단계

이제 계정, 활성 플랜, 이름이 지정된 키, 그리고 세 가지 클라이언트에서 실제 결과를 반환하는 요청을 갖추게 되었습니다. 여기에서 MCP 서버를 통해 키를 에이전트에 연결하거나, 사용자 모르게 키 변경 및 할당량 소진을 감지할 수 있도록 Apidog 테스트 시나리오를 구축할 수 있습니다. 두 가지 방법 모두 오늘 설정한 동일한 X-Subscription-Token 헤더로 시작합니다.