كيفية الحصول على مفتاح API لبحث برايف وتشغيل أول استعلام بحث لك

يمنحك مفتاح API الخاص بـ Brave وصولاً برمجيًا إلى فهرس الويب المستقل الخاص بـ Brave: نفس النتائج التي يقدمها Brave Search في المتصفح، وتُعاد كـ JSON يمكنك تغذيتها في البرامج النصية، لوحات المعلومات، أو وكلاء الذكاء الاصطناعي. أصبح Brave Search API خيارًا شائعًا لمنح الوكلاء وصولاً مباشرًا إلى الويب؛ وإذا كان هذا هو هدفك النهائي، فإن دليل خادم Brave Search MCP يوضح كيفية اتصال المفتاح بـ Claude وعملاء MCP الآخرين. تغطي هذه المقالة الجزء الذي يسبق ذلك: إنشاء الحساب، اختيار الخطة، توليد المفتاح، وإرسال استعلام حقيقي باستخدام curl و Python و Apidog.

كل ما يلي مأخوذ من وثائق لوحة تحكم Brave اعتبارًا من سبتمبر 2026. تتغير الأسعار والقيود، لذا تعامل مع الأرقام كلقطة وتحقق من الصفحات المرتبطة قبل تحديد ميزانيتك.

ما تحتاجه قبل البدء

• عنوان بريد إلكتروني لحساب لوحة التحكم.
• بطاقة ائتمان. يطلب Brave واحدة على كل خطة، بما في ذلك طبقة الرصيد المجاني، كفحص لمكافحة الاحتيال. ينص قسم الأسئلة الشائعة في صفحة الخطط على أنه بالنسبة للخطط المجانية، تُستخدم البطاقة فقط لتأكيد هويتك.
• curl، أو Python 3 مع حزمة requests، لأمثلة سطر الأوامر.
• Apidog، إذا كنت ترغب في تخزين المفتاح بأمان وتحويل الطلب إلى اختبار قابل للتكرار. إنه اختياري للمكالمة الأولى.

الخطوة 1: إنشاء حساب Brave Search API

انتقل إلى لوحة تحكم Brave Search API وسجل باستخدام عنوان بريد إلكتروني وكلمة مرور. يرسل Brave رابط تأكيد؛ انقر عليه للتحقق من العنوان. حتى تفعل ذلك، لا يمكنك تفعيل خطة.

لوحة التحكم منفصلة عن أي متصفح Brave أو تسجيل دخول Brave Rewards، لذلك لن يتم نقل حساب متصفح موجود. سجل حسابًا جديدًا.

الخطوة 2: اختيار خطة (الطبقة المجانية لها مشكلة واحدة)

افتح صفحة الخطط في لوحة التحكم. اعتبارًا من سبتمبر 2026، تسرد صفحة أسعار Brave هذه الخيارات:

للبحث في الويب، اختر "البحث". يغطي الرصيد الشهري البالغ 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 ينتقل بين الصفحات (يعتمد على الصفر، الحد الأقصى 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 وستحصل على ما يصل إلى خمس مقتطفات إضافية لكل نتيجة، مما يساعد عند بناء سياق لنموذج.

Brave يُصنف واجهة برمجة التطبيقات (API) برأس Api-Version اختياري بصيغة YYYY-MM-DD. اتركه وستحصل على أحدث إصدار؛ قم بتثبيته بمجرد أن يصبح التكامل الخاص بك في مرحلة الإنتاج حتى لا يحدث تغيير جذري مستقبلي دون سابق إنذار.

الخطوة 5: اختبار المفتاح في Apidog

لصق مفتاح في سطر واحد من curl مناسب لضربة أولى. لكنه مكان سيء لتركه. في Apidog تخزن المفتاح مرة واحدة كمتغير، وتشير إليه في كل مكان، وتبقي السر نفسه بعيدًا عن المشروع المشترك.

1. افتح إدارة البيئات في الجزء العلوي الأيمن من مشروع Apidog الخاص بك وأضف بيئة تسمى Brave. أنشئ متغيرًا باسم brave_api_key وضع المفتاح الحقيقي في حقل القيمة المحلية، وليس القيمة المشتركة. تبقى القيم المحلية على جهازك ولا تتم مزامنتها مع الزملاء أبدًا؛ يشرح مرجع المتغيرات نموذج القيمتين، وتغطي سير العمل الكامل للبيئات والمتغيرات السرية في Apidog تخطيطات التطوير، الاختبار المرحلي، والإنتاج إذا كنت بحاجة إلى أكثر من واحد.
2. أنشئ طلب GET جديدًا إلى https://api.search.brave.com/res/v1/web/search. في علامة تبويب الرؤوس (Headers) أضف X-Subscription-Token بالقيمة {{brave_api_key}}. في المعلمات (Params) أضف q و count و freshness.
3. انقر على إرسال (Send). يظهر جزء الرد (response pane) محتوى JSON، ويظهر جزء الرؤوس (headers pane) X-RateLimit-Remaining و X-RateLimit-Reset، بحيث يمكنك مراقبة حصتك دون طباعة أي شيء.
4. أضف تأكيدات: رمز الحالة يساوي 200، $.web.results موجود ويحتوي على عنصر واحد على الأقل، و $.query.original يطابق الاستعلام الذي أرسلته. احفظ الطلب في سيناريو اختبار. الآن يظهر تدوير المفتاح أو تغيير من جانب Brave كتشغيل أحمر بدلاً من وكيل معطل في الساعة 2 صباحًا.

قم بتنزيل Apidog للمتابعة؛ تغطي الخطة المجانية أربعة مستخدمين وتتضمن بيئات وسيناريوهات اختبار.

حدود الطلبات وكيفية الإبلاغ عنها بواسطة Brave

يحمل كل رد أربعة رؤوس (headers)، موثقة في دليل تحديد معدل الطلبات من Brave:

• X-RateLimit-Limit: الحدود المرتبطة بخطتك، على سبيل المثال 1, 15000.
• X-RateLimit-Policy: نفس الحدود مع أحجام النوافذ بالثواني، على سبيل المثال 1;w=1, 15000;w=2592000 (نافذة مدتها ثانية واحدة ونافذة مدتها 30 يومًا).
• X-RateLimit-Remaining: ما تبقى في كل نافذة.
• X-RateLimit-Reset: الثواني المتبقية حتى إعادة تعيين كل نافذة.

تفصيلان مهمان للميزانية. أولاً، ينص الدليل على أن الردود الناجحة وغير الخاطئة فقط هي التي تحتسب ضمن الحصة، لذا فإن مجموعة من الأخطاء 422 الناتجة عن خطأ مطبعي لا تستهلك الأرصدة. ثانيًا، الرقم في الثانية في رؤوس الأمثلة تلك (طلب واحد في الثانية) هو مجرد توضيح في الوثيقة، وليس 50 طلبًا في الثانية المعلن عنها في خطة البحث. اقرأ رؤوسك الخاصة بدلاً من الافتراض.

الأخطاء الشائعة وماذا تفعل

فشل المصادقة على مفتاح جديد.

يقول دليل المصادقة الخاص بـ Brave أن كل طلب يجب أن يحمل X-Subscription-Token، ويتم رفض القيمة المفقودة أو غير الصالحة. يظهر هذا عادة كخطأ HTTP 401 مع رمز خطأ يشير إلى عدم صلاحية الرمز (token-invalid)، على الرغم من أن مرجع Brave API لا يوضح الحالة. تحقق من ثلاثة أمور: أن اسم الرأس دقيق (وليس Authorization)، وأن المفتاح تم نسخه بدون مسافات بيضاء زائدة، وأن هناك خطة نشطة على الحساب. إذا كنت غير متأكد لماذا يختلف هذا المخطط عن مصادقة الحامل (bearer auth)، فانظر مفتاح 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 Search API مجاني؟

جزئيًا. تحصل كل خطة على 5 دولارات من الأرصدة شهريًا، وهو ما يعادل حوالي 1,000 طلب بحث. بعد ذلك تدفع 5.00 دولارات لكل 1,000 طلب. لا توجد طريقة لتفعيل خطة بدون بطاقة ائتمان، حتى لو لم تتجاوز الرصيد المجاني أبدًا.

هل أحتاج إلى مفاتيح منفصلة للبحث في الويب ونقطة نهاية سياق LLM؟

يصف مرجع Brave API الرمز المميز بأنه تم إنشاؤه "للمنتج"، مما يشير إلى أن المفتاح مرتبط بالاشتراك الذي تم إنشاؤه بموجبه. إذا فشل مفتاح يعمل على /web/search في العمل على /llm/context أو نقطة نهاية الإجابات، فتحقق من الخطة التي ينتمي إليها المفتاح في لوحة التحكم قبل افتراض أن المفتاح معطل.

ماذا لو تسرب مفتاح Brave API الخاص بي؟

قم بإلغائه في قسم مفاتيح API، وقم بإنشاء بديل، وحدث المتغير في Apidog بحيث يلتقط كل طلب محفوظ القيمة الجديدة على الفور. ثم اكتشف كيف تسرب: تشغيل ماسح ضوئي للأسرار لمفاتيح API المتسربة عبر مستودعاتك وسجلات التكامل المستمر (CI) هو أسرع طريقة لتأكيد عدم تعرض أي شيء آخر.

هل يمكنني تجربة الاستعلامات دون كتابة تعليمات برمجية؟

نعم. تتضمن لوحة التحكم صفحة "ساحة اللعب" (Playground) للاستعلامات المخصصة، ويقوم منشئ الطلبات في Apidog بنفس الشيء مع ميزة إضافية وهي أن الطلب يتم حفظه ويمكن اختباره لاحقًا.

الخطوة التالية

لديك حساب، خطة نشطة، مفتاح مسمى، وطلب يعيد نتائج حقيقية من ثلاثة عملاء. من هنا، إما أن تربط المفتاح بوكيل عبر خادم MCP، أو أن تبني سيناريو اختبار Apidog بحيث يتم اكتشاف تدوير المفتاح واستنفاد الحصة قبل أن يلاحظ المستخدمون. يبدأ كلاهما بنفس رأس X-Subscription-Token الذي أعددته اليوم.