A API do HolyArrs

Chama, a partir dos teus scripts, a mesma API JSON que a app web usa, em /api/v1.

Faz a tua primeira chamada

1. Abre Settings > API > API keys (Definições > API > chaves de API) e cria uma chave só com os âmbitos de que precisa. Copia-a já, porque só é mostrada uma vez.
2. Envia-a no cabeçalho X-Api-Key em todas as chamadas. Nunca a ponhas no endereço.
3. Chama o endereço base http://your-server:6262/api/v1. Com um URL base de /holyarrs, chama 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"

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

Opções

Escolhe um âmbito

Âmbito	Permite
health_read	Só o feed de saúde, para ferramentas de monitorização
read	As rotas de leitura, incluindo o feed de saúde
write	Alterações, exceto rotas de administração e controlos
admin	Pessoas, convites, limites de pedidos, chaves de API, palavras-passe e autenticação de dois fatores, definições de início de sessão, restauro
control	Interruptores das partes, fases, apps ligadas, reiniciar e desligar
all	read, write e admin. Não inclui control

Dá a uma ferramenta de monitorização health_read e mais nada.

Encontra uma rota

Settings > API mostra o endereço base, os âmbitos, exemplos de chamadas e todas as rotas com o respetivo âmbito e permissão. O ficheiro OpenAPI está em /api/v1/openapi.json quando tens a sessão iniciada. Rotas da API lista todas as rotas.

Fala com o HolyArrs como uma app anterior

O Seerr, o Overseerr, o Bazarr e apps parecidas não usam esta API. Falam com o HolyArrs como se fosse o Sonarr e o Radarr, com chaves próprias. Vê API de apps anteriores.

Se não funcionar

Sintoma. 401 em todas as chamadas. Causa. A chave está errada ou foi apagada. Solução. Cria uma chave nova.

Sintoma. 403 numa rota. Causa. O âmbito da chave não cobre essa rota. Solução. Confirma o âmbito da rota em Settings > API.

Sintoma. 404 em todas as chamadas. Causa. Falta o URL base. Solução. Põe-no antes de /api/v1. Vê URL base.

Para especialistas

Adicionar uma rota

As rotas vivem no routes.go de cada módulo. Cada uma é registada com o seu método, caminho e permissão, por isso todas as rotas têm uma verificação de permissão.

O openapi.json é gerado a partir das rotas. O TestOpenAPIGenerated falha quando deixam de coincidir, por isso atualiza-o na mesma alteração. Um snapshot da tabela de rotas também falha quando uma rota é adicionada, removida ou movida sem atualizar o snapshot.

Depois de lançados, os caminhos e os nomes dos campos mantêm-se. Acrescenta campos, nunca os renomeies. Depois de uma alteração, executa go run ./app/backend/tools/apidoc para reescrever Rotas da API.

Chamadas ao servidor de metadados

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

Registo. Na primeira pesquisa, uma instalação chama POST /v1/installations sem corpo. A resposta é 201 com {"schema_version":1,"token":"hai_..."}. A app guarda o token cifrado e envia Authorization: Bearer <token> em todas as pesquisas. Regista-se uma só vez. Depois de um 401 não volta a registar-se, por isso uma instalação revogada continua revogada. Acima do limite por hora para cada grupo de endereços, a resposta é 429 registration_limit com Retry-After.

Pesquisa (todas GET)	Rota
Pesquisa	/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}

Os parâmetros desconhecidos ou repetidos são recusados. Os ids de um fornecedor nunca são usados para outro.

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

Estado	Significa
400	Pedido inválido, não voltes a tentar
401	Token inválido ou revogado, não voltes a tentar
404	Esse registo não existe
429	Demasiadas chamadas, espera pelo Retry-After
503	Ocupado, espera e tenta mais uma vez

Relacionado

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