HolyArrs API

설정

웹 앱이 쓰는 것과 같은 JSON API를 /api/v1 아래에서 직접 만든 스크립트로 호출할 수 있습니다.

첫 호출 보내기

Settings > API > API keys(설정 > API > API 키)를 열고, 꼭 필요한 스코프만 넣어 키를 만드세요. 키는 한 번만 표시되니 바로 복사하세요.
호출할 때마다 X-Api-Key 헤더에 키를 넣어 보내세요. 주소에는 절대 넣지 마세요.
기본 주소 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이 돌아오면 정상입니다. 오류는 HTTP 상태 코드와 함께 {"error": "plain words"} 형태로 옵니다. 비밀 값은 가려진 채로 돌아옵니다.

선택 사항

스코프 고르기

스코프	허용 범위
`health_read`	상태 피드만. 모니터링 도구용
`read`	읽기 라우트. 상태 피드 포함
`write`	변경 작업. 관리자 라우트와 제어 기능은 제외
`admin`	사용자, 초대, 요청 한도, API 키, 비밀번호와 2단계 인증, 로그인 설정, 복원
`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로 다른 서버를 가리키게 할 수 있습니다. 서버 코드는 이 저장소에 없습니다.

등록. 설치된 HolyArrs는 첫 조회 때 본문 없이 POST /v1/installations를 호출합니다. 응답은 201과 {"schema_version":1,"token":"hai_..."}입니다. 앱은 토큰을 암호화해 저장하고, 조회할 때마다 Authorization: Bearer <token>을 보냅니다. 등록은 한 번만 합니다. 401을 받은 뒤에는 다시 등록하지 않으므로, 취소된 설치는 취소된 상태로 남습니다. 주소 그룹당 시간당 한도를 넘으면 Retry-After와 함께 429 registration_limit이 응답으로 옵니다.

조회 (모두 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	서버가 바쁨. 기다렸다가 한 번만 재시도하세요