A API do HolyArrs

Chame nos seus próprios scripts a mesma API JSON que o app web usa, em /api/v1.

Faça sua primeira chamada

1. Abra Settings > API > API keys (Configurações > API > chaves de API) e crie uma chave só com os escopos necessários. Copie a chave na hora, porque ela aparece uma única vez.
2. Envie a chave no cabeçalho X-Api-Key em toda chamada. Nunca coloque a chave no endereço.
3. Chame o endereço base http://your-server:6262/api/v1. Com uma URL base /holyarrs, chame 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"

Você deve receber JSON de volta. Os erros vêm como {"error": "plain words"} com um status HTTP. Os segredos voltam mascarados.

Opções

Escolha um escopo

Escopo	Permite
health_read	Só o feed de saúde, para ferramentas de monitoramento
read	As rotas de leitura, incluindo o feed de saúde
write	Alterações, menos as rotas de administração e os controles
admin	Pessoas, convites, limites de pedidos, chaves de API, senhas e verificação em duas etapas, configurações de login, restauração
control	Chaves das Partes, etapas, apps vinculados, reiniciar e desligar
all	read, write e admin. Não inclui control

Para uma ferramenta de monitoramento, dê health_read e mais nada.

Encontre uma rota

Settings > API mostra o endereço base, os escopos, exemplos de chamadas e todas as rotas com o escopo e a permissão de cada uma. O arquivo OpenAPI fica em /api/v1/openapi.json quando você está com o login feito. Rotas da API lista todas as rotas.

Fale com o HolyArrs como um app anterior

Seerr, Overseerr, Bazarr e apps parecidos não usam esta API. Eles falam com o HolyArrs como se fosse o Sonarr e o Radarr, com chaves próprias. Veja API dos apps anteriores.

Se não funcionar

Sintoma. 401 em toda chamada. Causa. A chave está errada ou foi excluída. Solução. Crie uma chave nova.

Sintoma. 403 em uma rota. Causa. O escopo da chave não cobre essa rota. Solução. Confira o escopo da rota em Settings > API.

Sintoma. 404 em toda chamada. Causa. Falta a URL base. Solução. Coloque a URL base antes de /api/v1. Veja URL base.

Para especialistas

Adicionar uma rota

As rotas ficam no routes.go de cada módulo. Cada rota é registrada com seu método, caminho e permissão, então toda rota tem uma verificação de permissão.

O openapi.json é gerado a partir das rotas. O TestOpenAPIGenerated falha quando os dois deixam de bater, então atualize o arquivo na mesma alteração. Um snapshot da tabela de rotas também falha quando alguém adiciona, remove ou move uma rota sem atualizar o snapshot.

Depois de lançados, os caminhos e os nomes dos campos ficam como estão. Adicione campos, nunca mude o nome deles. Depois de uma alteração, execute go run ./app/backend/tools/apidoc para reescrever Rotas da API.

Chamadas ao servidor de metadados

O HolyArrs busca nomes, imagens e ids no servidor de metadados do HolyArrs. Aponte uma instalação para outro servidor com HOLYARRS_METADATA_URL. O código do servidor não está neste repositório.

Registro. Na primeira consulta, a instalação chama POST /v1/installations sem corpo. A resposta é 201 com {"schema_version":1,"token":"hai_..."}. O app salva o token criptografado e envia Authorization: Bearer <token> em toda consulta. O registro acontece uma vez só. Depois de um 401, o app não se registra de novo, então uma instalação revogada continua revogada. Acima do limite por hora de cada grupo de endereços, a resposta é 429 registration_limit com Retry-After.

Consulta (todas GET)	Rota
Busca	/v1/search?provider=tmdb&kind=movie&q=Example&page=1
Filme	/v1/movies/tmdb/{id}
Série	/v1/shows/{tmdb or tvmaze}/{id}
Temporada	/v1/shows/tmdb/{id}/seasons/{n} (a temporada 0 são os especiais)
Música	/v1/music/musicbrainz/{artist, release-group, release or recording}/{id}

O servidor recusa parâmetros desconhecidos ou repetidos. Os ids de um provedor nunca são usados em outro.

Uma resposta boa tem schema_version, source, source_id, fetched_at, expires_at, completeness, stale e data. Trate o HTML dos resumos como texto simples.

Status	Significa
400	Consulta inválida, não tente de novo
401	Token inválido ou revogado, não tente de novo
404	Esse registro não existe
429	Chamadas demais, espere o Retry-After
503	Ocupado, espere e tente de novo uma vez

Relacionados

• Rotas da API
• API dos apps anteriores
• Variáveis de ambiente