Can♱ólico Partner API · v1

API do Cantólico.

Pesquisa cânticos e consulta sugestões para cada celebração.

Autenticação

Chave de API

Envia a chave em Authorization: Bearer <api_key> ou X-API-Key.

curl "https://www.cantolico.pt/api/v1/songs?q=aleluia" -H "Authorization: Bearer ctk_a_tua_chave"

URL base: https://www.cantolico.pt/api/v1. Respostas em JSON.

Catálogo

Pesquisar cânticos

GET/songs

Pesquisa títulos com q. Filtra por momento, tipo ou instrumento. Cada cântico inclui url, o link direto para o Cantólico.

Parâmetro	Valores
`q`	texto no título
`moment`	momento litúrgico
`type`	ACORDES ou PARTITURA
`instrument`	ORGAO, GUITARRA, PIANO, CORO ou OUTRO
`page` / `per_page`	página / 1 a 100 resultados

GET /songs?q=aleluia&moment=ACLAMACAO_EVANGELHO&page=1&per_page=25

Detalhe

Ficha de cântico

GET/songs/{id-ou-slug}

Devolve autoria, instrumento, momentos, etiquetas, capo, url e a versão atual com letra, acordes e links multimédia.

GET /songs/aleluia-pascal

Liturgia

Sugestões de cânticos

GET/liturgical-suggestions?date=YYYY-MM-DD

Devolve celebração, leituras, cor litúrgica e três cânticos por momento. O primeiro é a sugestão principal. Cada cântico inclui url. Sem date, usa o dia atual em Lisboa.

GET /liturgical-suggestions?date=2026-10-04

A resposta inclui celebration, suggestions, source e format_version. Uma data não encontrada devolve 404 not_found.

Limites e erros

Limite: 120 pedidos por minuto por chave. As respostas incluem X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset.

{ "error": { "code": "invalid_api_key", "message": "É necessária uma chave de API válida." } }

401 chave inválida, revogada ou expirada
403 chave sem permissão
404 recurso não encontrado
422 parâmetros inválidos
429 limite atingido; inclui Retry-After
500 erro temporário