HolyArrs API

เรียก JSON 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 status ส่วนข้อมูลลับจะถูกปิดบังบางส่วนตอนส่งกลับ

ตัวเลือก

เลือกสโคป

สโคป	อนุญาตให้ทำอะไร
health_read	ดูเฉพาะฟีดสุขภาพระบบ สำหรับเครื่องมือมอนิเตอร์
read	เส้นทางที่อ่านข้อมูล รวมฟีดสุขภาพระบบ
write	การเปลี่ยนแปลงทั้งหมด ยกเว้นเส้นทางแอดมินและการควบคุม
admin	ผู้ใช้ คำเชิญ โควตาการขอ API key รหัสผ่านและการยืนยันสองขั้นตอน การตั้งค่าการล็อกอิน การกู้คืน
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 จะไม่ผ่านเมื่อสองฝั่งไม่ตรงกัน จึงต้องอัปเดตในการเปลี่ยนแปลงเดียวกัน snapshot ของตารางเส้นทางก็จะไม่ผ่านเช่นกัน ถ้าเพิ่ม เอาออก หรือย้ายเส้นทางโดยไม่อัปเดต snapshot

เมื่อปล่อยออกไปแล้ว พาธและชื่อฟิลด์จะคงเดิม ให้เพิ่มฟิลด์ใหม่ ห้ามเปลี่ยนชื่อ หลังแก้เสร็จ ให้รัน go run ./app/backend/tools/apidoc เพื่อเขียน เส้นทาง API ใหม่

การเรียกเซิร์ฟเวอร์ metadata

HolyArrs ดึงชื่อ รูปภาพ และ id จากเซิร์ฟเวอร์ metadata ของ HolyArrs ถ้าจะให้การติดตั้งหนึ่งชี้ไปที่เซิร์ฟเวอร์อื่น ให้ใช้ HOLYARRS_METADATA_URL โค้ดของเซิร์ฟเวอร์ไม่ได้อยู่ใน repo นี้

การลงทะเบียน. ตอนค้นหาครั้งแรก การติดตั้งจะเรียก POST /v1/installations โดยไม่มี body คำตอบคือ 201 พร้อม {"schema_version":1,"token":"hai_..."} แอปเก็บ token แบบเข้ารหัส แล้วส่ง 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 ในเรื่องย่อเป็นข้อความธรรมดา

Status	ความหมาย
400	query ไม่ถูกต้อง อย่าลองใหม่
401	token ผิดหรือถูกเพิกถอน อย่าลองใหม่
404	ไม่มีรายการนี้
429	เรียกมากเกินไป รอตาม Retry-After
503	ไม่ว่าง รอแล้วลองใหม่หนึ่งครั้ง

หน้าที่เกี่ยวข้อง

• เส้นทาง API
• API แอปรุ่นเดิม
• ตัวแปรสภาพแวดล้อม