API của HolyArrs

Gọi chính API JSON mà ứng dụng web dùng, dưới /api/v1, từ các script của riêng bạn.

Thực hiện lệnh gọi đầu tiên

1. Mở Settings > API > API keys (cài đặt > API > khóa API) và tạo một khóa chỉ với những phạm vi nó cần. Sao chép khóa ngay, vì nó chỉ hiện một lần.
2. Gửi khóa trong header X-Api-Key ở mọi lệnh gọi. Không bao giờ đặt nó vào địa chỉ.
3. Gọi địa chỉ gốc http://your-server:6262/api/v1. Nếu URL base là /holyarrs, hãy gọi 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"

Bạn sẽ nhận lại JSON. Lỗi có dạng {"error": "plain words"} kèm một mã trạng thái HTTP. Các bí mật được trả về đã bị che.

Lựa chọn

Chọn một phạm vi

Phạm vi	Cho phép
health_read	Chỉ nguồn dữ liệu tình trạng, dành cho các công cụ giám sát
read	Các route chỉ đọc, gồm cả nguồn dữ liệu tình trạng
write	Các thay đổi, trừ route quản trị và các lệnh điều khiển
admin	Người dùng, lời mời, giới hạn yêu cầu, khóa API, mật khẩu và xác thực hai lớp, cài đặt đăng nhập, khôi phục
control	Công tắc các phần, các giai đoạn, ứng dụng đã liên kết, khởi động lại và tắt máy
all	read, write và admin. Không gồm control

Với công cụ giám sát, chỉ cấp health_read, không cấp gì khác.

Tìm một route

Settings > API hiện địa chỉ gốc, các phạm vi, các lệnh gọi mẫu, và mọi route kèm phạm vi và quyền của nó. Tệp OpenAPI nằm ở /api/v1/openapi.json khi bạn đã đăng nhập. Các route API liệt kê mọi route.

Nói chuyện với HolyArrs như một ứng dụng cũ

Seerr, Overseerr, Bazarr và các ứng dụng tương tự không dùng API này. Chúng nói chuyện với HolyArrs như thể nó là Sonarr và Radarr, với các khóa riêng. Xem API ứng dụng cũ.

Nếu không hoạt động

Triệu chứng. Lỗi 401 ở mọi lệnh gọi. Nguyên nhân. Khóa sai hoặc đã bị xóa. Cách khắc phục. Tạo khóa mới.

Triệu chứng. Lỗi 403 ở một route. Nguyên nhân. Phạm vi của khóa không bao gồm route đó. Cách khắc phục. Xem phạm vi của route trên Settings > API.

Triệu chứng. Lỗi 404 ở mọi lệnh gọi. Nguyên nhân. Thiếu URL base. Cách khắc phục. Đặt nó trước /api/v1. Xem URL base.

Dành cho người dùng nâng cao

Thêm một route

Các route nằm trong routes.go của từng module. Mỗi route được đăng ký cùng phương thức, đường dẫn và quyền của nó, nên route nào cũng có bước kiểm tra quyền.

openapi.json được tạo từ các route. TestOpenAPIGenerated báo lỗi khi hai bên lệch nhau, nên hãy cập nhật nó trong cùng một thay đổi. Bản chụp bảng route cũng báo lỗi khi một route được thêm, xóa hoặc chuyển mà không cập nhật bản chụp.

Sau khi đã phát hành, đường dẫn và tên trường được giữ nguyên. Chỉ thêm trường, không bao giờ đổi tên. Sau một thay đổi, chạy go run ./app/backend/tools/apidoc để ghi lại Các route API.

Các lệnh gọi máy chủ metadata

HolyArrs lấy tên, hình ảnh và id từ máy chủ metadata của HolyArrs. Để trỏ một bản cài sang máy chủ khác, dùng HOLYARRS_METADATA_URL. Mã của máy chủ không nằm trong repo này.

Đăng ký. Ở lần tra cứu đầu tiên, một bản cài gọi POST /v1/installations không kèm nội dung. Câu trả lời là 201 với {"schema_version":1,"token":"hai_..."}. Ứng dụng lưu token đã mã hóa và gửi Authorization: Bearer <token> ở mọi lần tra cứu. Nó chỉ đăng ký một lần. Sau một lỗi 401 nó không đăng ký lại, nên bản cài đã bị thu hồi vẫn bị thu hồi. Nếu vượt giới hạn theo giờ cho mỗi nhóm địa chỉ, câu trả lời là 429 registration_limit kèm Retry-After.

Tra cứu (đều là GET)	Route
Tìm kiếm	/v1/search?provider=tmdb&kind=movie&q=Example&page=1
Phim lẻ	/v1/movies/tmdb/{id}
Phim bộ	/v1/shows/{tmdb or tvmaze}/{id}
Mùa	/v1/shows/tmdb/{id}/seasons/{n} (mùa 0 là tập đặc biệt)
Nhạc	/v1/music/musicbrainz/{artist, release-group, release or recording}/{id}

Tham số không rõ hoặc bị lặp sẽ bị từ chối. Id của nhà cung cấp này không bao giờ được dùng cho nhà cung cấp khác.

Một câu trả lời tốt có schema_version, source, source_id, fetched_at, expires_at, completeness, stale và data. Hãy coi HTML trong phần tóm tắt là văn bản thuần.

Trạng thái	Ý nghĩa
400	Truy vấn sai, đừng thử lại
401	Token sai hoặc đã bị thu hồi, đừng thử lại
404	Không có bản ghi đó
429	Gọi quá nhiều, chờ theo Retry-After
503	Đang bận, chờ rồi thử lại một lần

Liên quan

• Các route API
• API ứng dụng cũ
• Biến môi trường