واجهة HolyArrs البرمجية (API)

استدعِ من سكربتاتك واجهة JSON نفسها التي يستخدمها تطبيق الويب، تحت /api/v1.

أجرِ أول استدعاء

1. افتح Settings > API > API keys (الإعدادات > API > مفاتيح API) وأنشئ مفتاحًا بالنطاقات التي يحتاج إليها لا غير. انسخه الآن، لأنه يظهر مرة واحدة.
2. أرسله في الترويسة X-Api-Key مع كل استدعاء. لا تضعه في العنوان أبدًا.
3. استدعِ العنوان الأساسي http://your-server:6262/api/v1. إذا كان URL base هو /holyarrs، فاستدعِ http://your-server:6262/holyarrs/api/v1.

export HOLYARRS_KEY=...your key...
curl -H "X-Api-Key: $HOLYARRS_KEY" "http://your-server:6262/api/v1/health"

سترى ردًّا بصيغة JSON. تأتي الأخطاء بالشكل {"error": "plain words"} مع رمز حالة HTTP. وتعود القيم السرية محجوبة.

الخيارات

اختر نطاقًا

النطاق	يسمح بـ
health_read	خلاصة سلامة النظام وحدها، لأدوات المراقبة
read	مسارات القراءة، ومنها خلاصة سلامة النظام
write	التغييرات، ما عدا مسارات المشرف وعناصر التحكم
admin	الأشخاص، والدعوات، وحدود الطلبات، ومفاتيح API، وكلمات المرور والتحقق بخطوتين، وإعدادات تسجيل الدخول، والاستعادة
control	مفاتيح تشغيل الأقسام، والمراحل، والتطبيقات المرتبطة، وإعادة التشغيل وإيقاف التشغيل
all	read وwrite وadmin. لا يشمل control

أعطِ أداة المراقبة health_read ولا شيء غيره.

ابحث عن مسار

تعرض Settings > API العنوان الأساسي، والنطاقات، وأمثلة على الاستدعاءات، وكل مسار مع نطاقه وإذنه. تجد ملف OpenAPI في /api/v1/openapi.json بعد تسجيل الدخول. وتسرد صفحة مسارات API كل المسارات.

خاطب HolyArrs كأنه تطبيق أقدم

لا تستخدم Seerr وOverseerr وBazarr والتطبيقات المشابهة هذه الواجهة. فهي تخاطب HolyArrs كأنه Sonarr وRadarr، بمفاتيح خاصة بها. انظر واجهة التطبيقات الأقدم.

إذا لم ينجح الأمر

العَرَض. 401 في كل استدعاء. السبب. المفتاح خاطئ أو محذوف. الحل. أنشئ مفتاحًا جديدًا.

العَرَض. 403 في مسار واحد. السبب. نطاق المفتاح لا يشمل ذلك المسار. الحل. تحقق من نطاق المسار في Settings > API.

العَرَض. 404 في كل استدعاء. السبب. URL base غير موجود في العنوان. الحل. ضعه قبل /api/v1. انظر URL base.

للخبراء

أضف مسارًا

توجد المسارات في الملف routes.go لكل وحدة. يُسجَّل كل مسار مع طريقته ونص مساره وإذنه، فلا يخلو مسار من فحص للإذن.

يُولَّد openapi.json من المسارات. يفشل TestOpenAPIGenerated إذا اختلف الملف عنها، فحدّثه في التغيير نفسه. وتفشل كذلك لقطة جدول المسارات إذا أُضيف مسار أو أُزيل أو نُقل من دون تحديث اللقطة.

بعد النشر، تبقى نصوص المسارات وأسماء الحقول كما هي. أضف حقولًا، ولا تُعد تسميتها أبدًا. بعد أي تغيير، شغّل go run ./app/backend/tools/apidoc لإعادة كتابة صفحة مسارات API.

استدعاءات خادم البيانات الوصفية

يحصل HolyArrs على الأسماء والصور والمعرّفات من خادم البيانات الوصفية الخاص بـ HolyArrs. وجّه أي تثبيت إلى خادم آخر بالمتغير HOLYARRS_METADATA_URL. شيفرة الخادم ليست في هذا المستودع.

التسجيل. عند أول استعلام، يستدعي التثبيت POST /v1/installations من دون جسم للطلب. يأتي الرد 201 مع {"schema_version":1,"token":"hai_..."}. يخزّن التطبيق الرمز مشفّرًا ويرسل Authorization: Bearer <token> مع كل استعلام. يسجّل مرة واحدة. بعد 401 لا يسجّل من جديد، فالتثبيت الذي أُلغي يبقى ملغى. وإذا تجاوزت مجموعة العناوين الحد المسموح في الساعة، يأتي الرد 429 registration_limit مع Retry-After.

الاستعلام (كلها GET)	المسار
بحث	/v1/search?provider=tmdb&kind=movie&q=Example&page=1
فيلم	/v1/movies/tmdb/{id}
مسلسل	/v1/shows/{tmdb or tvmaze}/{id}
موسم	/v1/shows/tmdb/{id}/seasons/{n} (الموسم 0 هو الحلقات الخاصة)
الموسيقى	/v1/music/musicbrainz/{artist, release-group, release or recording}/{id}

تُرفض المعاملات غير المعروفة أو المكررة. ولا تُستخدم معرّفات مزوّد مع مزوّد آخر أبدًا.

يحتوي الرد السليم على schema_version وsource وsource_id وfetched_at وexpires_at وcompleteness وstale وdata. عامل HTML الوارد في الملخصات على أنه نص عادي.

الحالة	المعنى
400	استعلام خاطئ، لا تُعد المحاولة
401	رمز خاطئ أو ملغى، لا تُعد المحاولة
404	لا يوجد سجل كهذا
429	استدعاءات كثيرة جدًا، انتظر المدة في Retry-After
503	الخادم مشغول، انتظر ثم حاول مرة واحدة

صفحات ذات صلة

• مسارات API
• واجهة التطبيقات الأقدم
• متغيرات البيئة