HolyArrs API'si

Web uygulamasının kullandığı JSON API’nin aynısını, /api/v1 altından kendi betiklerinde çağırabilirsin.

İlk çağrını yap

1. Settings > API > API keys (Ayarlar > API > API anahtarları) sayfasını aç ve yalnızca gereken kapsamlara sahip bir anahtar oluştur. Anahtar bir kez gösterilir, o yüzden hemen kopyala.
2. Her çağrıda anahtarı X-Api-Key başlığıyla gönder. Adresin içine asla yazma.
3. Temel adres olarak http://your-server:6262/api/v1 kullan. URL base /holyarrs ise http://your-server:6262/holyarrs/api/v1 adresini çağır.

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

Cevap olarak JSON almalısın. Hatalar, bir HTTP durum koduyla birlikte {"error": "plain words"} biçiminde gelir. Gizli bilgiler maskelenmiş döner.

Seçenekler

Kapsam seç

Kapsam	İzin verdiği
health_read	Yalnızca sağlık feed’i, izleme araçları için
read	Okuma rotaları, sağlık feed’i dahil
write	Değişiklikler; yönetici rotaları ve kontroller hariç
admin	Kişiler, davetler, istek limitleri, API anahtarları, parolalar ve iki adımlı doğrulama, giriş ayarları, geri yükleme
control	Modül anahtarları, aşamalar, bağlı uygulamalar, yeniden başlatma ve kapatma
all	read, write ve admin. control dahil değil

İzleme aracına health_read ver, başka bir şey verme.

Rota bul

Settings > API sayfası temel adresi, kapsamları, örnek çağrıları ve her rotayı kapsamı ve izniyle birlikte gösterir. Giriş yaptığında OpenAPI dosyası /api/v1/openapi.json adresinde durur. API rotaları sayfası her rotayı listeler.

HolyArrs ile eski bir uygulama gibi konuş

Seerr, Overseerr, Bazarr ve benzeri uygulamalar bu API’yi kullanmaz. HolyArrs ile sanki Sonarr ve Radarr’mış gibi, kendilerine ait anahtarlarla konuşurlar. Eski uygulama API’si sayfasına bak.

Çalışmazsa

Belirti. Her çağrıda 401. Neden. Anahtar yanlış ya da silinmiş. Çözüm. Yeni bir anahtar oluştur.

Belirti. Tek bir rotada 403. Neden. Anahtarın kapsamı o rotayı kapsamıyor. Çözüm. Rota’un kapsamını Settings > API sayfasında kontrol et.

Belirti. Her çağrıda 404. Neden. URL base eksik. Çözüm. /api/v1 öncesine koy. URL base sayfasına bak.

Uzmanlar için

Rota ekle

Rotalar her modülün routes.go dosyasında durur. Her rota yöntemi, yolu ve izniyle kaydedilir, bu yüzden her rotada bir izin denetimi vardır.

openapi.json rotalardan üretilir. İkisi birbirinden ayrılırsa TestOpenAPIGenerated başarısız olur, o yüzden aynı değişiklikte onu da güncelle. Rota tablosunun anlık görüntüsü de, bir rota anlık görüntü güncellenmeden eklenir, silinir ya da taşınırsa başarısız olur.

Bir kez yayımlandıktan sonra rota yolları ve alan adları değişmez. Alan ekle, hiçbirini yeniden adlandırma. Değişiklikten sonra API rotaları sayfasını yeniden yazmak için go run ./app/backend/tools/apidoc çalıştır.

Metadata sunucusu çağrıları

HolyArrs adları, resimleri ve kimlikleri HolyArrs metadata sunucusundan alır. Bir kurulumu başka bir sunucuya yöneltmek için HOLYARRS_METADATA_URL kullan. Sunucunun kodu bu repoda yok.

Kayıt. Bir kurulum ilk aramasında gövdesiz bir POST /v1/installations çağrısı yapar. Cevap 201 ve {"schema_version":1,"token":"hai_..."} olur. Uygulama token’ı şifreli saklar ve her aramada Authorization: Bearer <token> gönderir. Yalnızca bir kez kayıt olur. 401 aldıktan sonra yeniden kayıt olmaz, yani iptal edilen kurulum iptal kalır. Adres grubu başına saatlik limit aşılırsa cevap Retry-After ile birlikte 429 registration_limit olur.

Arama (hepsi GET)	Rota
Arama	/v1/search?provider=tmdb&kind=movie&q=Example&page=1
Film	/v1/movies/tmdb/{id}
Dizi	/v1/shows/{tmdb or tvmaze}/{id}
Sezon	/v1/shows/tmdb/{id}/seasons/{n} (0. sezon özel bölümlerdir)
Müzik	/v1/music/musicbrainz/{artist, release-group, release or recording}/{id}

Bilinmeyen ya da tekrar eden parametreler reddedilir. Bir sağlayıcının kimlikleri başka bir sağlayıcı için asla kullanılmaz.

İyi bir cevapta schema_version, source, source_id, fetched_at, expires_at, completeness, stale ve data bulunur. Özetlerdeki HTML’yi düz metin say.

Durum	Anlamı
400	Hatalı sorgu, yeniden deneme
401	Hatalı ya da iptal edilmiş token, yeniden deneme
404	Böyle bir kayıt yok
429	Çok fazla çağrı, Retry-After kadar bekle
503	Meşgul, bekle ve bir kez daha dene

İlgili

• API rotaları
• Eski uygulama API’si
• Ortam değişkenleri