HolyArrs API

वेब ऐप जिस JSON API का इस्तेमाल करता है, वही API /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 और ऐसे दूसरे ऐप इस API का इस्तेमाल नहीं करते। वे HolyArrs से ऐसे बात करते हैं जैसे वह Sonarr और Radarr हो, और उनकी अपनी अलग कुंजी होती हैं। पुराने ऐप का API देखें।

अगर काम न करे

लक्षण। हर कॉल पर 401। वजह। कुंजी गलत है या हटा दी गई है। हल। नई कुंजी बनाएं।

लक्षण। किसी एक रूट पर 403। वजह। कुंजी का स्कोप उस रूट को कवर नहीं करता। हल। Settings > API पर उस रूट का स्कोप देखें।

लक्षण। हर कॉल पर 404। वजह। URL base छूट गया है। हल। इसे /api/v1 से पहले लगाएं। URL base देखें।

एक्सपर्ट के लिए

रूट जोड़ें

रूट हर मॉड्यूल की routes.go में रहते हैं। हर रूट अपने मेथड, पाथ और अनुमति के साथ रजिस्टर होता है, इसलिए हर रूट पर अनुमति की जाँच होती है।

openapi.json रूट से बनती है। दोनों में फ़र्क आते ही TestOpenAPIGenerated फ़ेल हो जाता है, इसलिए इसे उसी बदलाव में अपडेट करें। रूट-टेबल का एक स्नैपशॉट भी तब फ़ेल होता है जब कोई रूट स्नैपशॉट अपडेट किए बिना जोड़ा, हटाया या दूसरी जगह ले जाया जाए।

एक बार रिलीज़ होने के बाद पाथ और फ़ील्ड के नाम वही रहते हैं। फ़ील्ड जोड़ें, उनका नाम कभी न बदलें। बदलाव के बाद go run ./app/backend/tools/apidoc चलाएं, ताकि API रूट दोबारा लिखा जाए।

मेटाडेटा सर्वर की कॉल

HolyArrs नाम, तस्वीरें और id 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}

अनजान या दोहराए गए पैरामीटर ठुकरा दिए जाते हैं। एक प्रोवाइडर की id कभी दूसरे के लिए इस्तेमाल नहीं होतीं।

सही जवाब में schema_version, source, source_id, fetched_at, expires_at, completeness, stale और data होते हैं। सारांश में आए HTML को सादा टेक्स्ट मानें।

स्टेटस	मतलब
400	क्वेरी गलत है, दोबारा कोशिश न करें
401	टोकन गलत है या रद्द हो चुका है, दोबारा कोशिश न करें
404	ऐसा कोई रिकॉर्ड नहीं
429	बहुत ज़्यादा कॉल, Retry-After तक रुकें
503	सर्वर व्यस्त है, रुकें और एक बार दोबारा कोशिश करें

इससे जुड़े पेज

• API रूट
• पुराने ऐप का API
• एनवायरनमेंट वेरिएबल