Documentação da API aberta de eventos
O que é uma "API aberta"?
Imagine que a nossa agenda é um cardápio de restaurante. Você pode olhar o cardápio na vitrine e copiar à mão os pratos que interessam — mas toda vez que o cardápio muda, você precisa voltar e copiar de novo. Uma API funciona como um garçom: em vez de você copiar à mão, o seu site pede a informação e o nosso sistema entrega a agenda pronta, sempre atualizada, sozinho.
"Aberta" significa que não precisa de cadastro, chave de acesso, contrato ou pagamento. Funciona como um site comum: você abre um endereço na internet e recebe a resposta. A diferença é que, em vez de uma página bonita para humanos lerem, a resposta vem formatada para o computador entender direto — em um padrão chamado JSON, que é só texto organizado com chaves e colchetes.
Em resumo: o seu site pergunta, o nosso responde, sem custo e sem burocracia. Basta usar o endereço abaixo.
Resumo do endpoint principal
GET https://eventos.terralibris.com.br/api/public/agenda- O que devolve
- Uma lista de eventos na livraria com título, tipo, data, horários, local, editora, livro, autor e imagens.
- Formato
- JSON, com CORS liberado e cache de 5 minutos.
- Autenticação
- Nenhuma. É público e gratuito.
- Privacidade
- Datas ainda em negociação aparecem apenas como "Em confirmação", sem detalhes internos.
Parâmetros aceitos
| Parâmetro | Exemplo | O que faz |
|---|---|---|
| limite | ?limite=5 | Limita a quantidade de eventos (máx. 100) |
| mes | ?mes=2026-09 | Só eventos de um mês (formato AAAA-MM) |
| tipo | ?tipo=Lançamento | Filtra por tipo: Lançamento, Bate-papo, Contação, Cinema, Feira ou Outro |
| q | ?q=Mott | Busca por palavra-chave (título, autor, editora, livro, local) |
| passados | ?passados=true | Mostra eventos já realizados (histórico) |
Os parâmetros podem ser combinados. Ex.: ?tipo=Lançamento&limite=10
Exemplos de requisição
Cada linha abaixo é um endereço. Você pode colar direto no navegador para ver o resultado.
Os próximos eventos
Traz a agenda que ainda vai acontecer, do mais próximo ao mais distante.
GET https://eventos.terralibris.com.br/api/public/agendaSó os 5 próximos
Ideal para um bloco pequeno no rodapé ou na barra lateral do seu site.
GET https://eventos.terralibris.com.br/api/public/agenda?limite=5Eventos de um mês
Use o formato ano-mês. Serve para montar uma pauta mensal.
GET https://eventos.terralibris.com.br/api/public/agenda?mes=2026-09Só lançamentos
Filtra por tipo: Lançamento, Bate-papo, Contação, Cinema, Feira ou Outro.
GET https://eventos.terralibris.com.br/api/public/agenda?tipo=LançamentoBuscar por palavra-chave
Procura em título, tipo, autor, editora, livro e local. Não diferencia maiúsculas de minúsculas.
GET https://eventos.terralibris.com.br/api/public/agenda?q=MottO que já aconteceu
Histórico dos eventos realizados, do mais recente para o mais antigo.
GET https://eventos.terralibris.com.br/api/public/agenda?passados=trueResposta real do sistema
Este JSON foi buscado agora, ao vivo, em /api/public/agenda?limite=2.
Carregando resposta real...
Exemplos em cURL
cURL é um programa que já vem instalado em computadores Mac e Linux (e no Windows 10+). Abra o terminal, cole o comando e tecle Enter. Serve para testar a API rapidamente sem escrever código.
Listar eventos
# Listar todos os próximos eventos curl "https://eventos.terralibris.com.br/api/public/agenda"
Filtrar por tipo
# Filtrar só lançamentos curl "https://eventos.terralibris.com.br/api/public/agenda?tipo=Lançamento"
Buscar por palavra-chave
# Buscar por palavra-chave curl "https://eventos.terralibris.com.br/api/public/agenda?q=Mott"
Eventos passados
# Eventos já realizados curl "https://eventos.terralibris.com.br/api/public/agenda?passados=true"
Combinar filtros
# Combinar filtros: lançamentos de um mês, no máximo 10 curl "https://eventos.terralibris.com.br/api/public/agenda?tipo=Lançamento&mes=2026-09&limite=10"
Exemplos em JavaScript
Para usar no navegador ou em frameworks como React, Vue e Astro. Todos os exemplos usam fetch, que já vem nativo no JavaScript.
1. Listar eventos
// 1. Listar todos os próximos eventos
const resposta = await fetch("https://eventos.terralibris.com.br/api/public/agenda");
const { eventos } = await resposta.json();
for (const ev of eventos) {
console.log(ev.data, "—", ev.titulo);
}2. Filtrar por tipo
// 2. Filtrar só lançamentos (server-side)
const resposta = await fetch("https://eventos.terralibris.com.br/api/public/agenda?tipo=Lançamento");
const { eventos } = await resposta.json();3. Buscar por palavra-chave
// 3. Buscar por palavra-chave (server-side)
const resposta = await fetch("https://eventos.terralibris.com.br/api/public/agenda?q=Mott");
const { eventos } = await resposta.json();
for (const ev of eventos) {
console.log(ev.titulo, "|", ev.autor_convidado ?? ev.editora);
}4. Exibir no HTML
// 4. Montar uma lista HTML simples no seu site
const resposta = await fetch("https://eventos.terralibris.com.br/api/public/agenda?limite=5");
const { eventos } = await resposta.json();
const html = eventos
.map((ev) => `<li>${ev.data} — ${ev.titulo}</li>`)
.join("");
document.getElementById("agenda").innerHTML = `<ul>${html}</ul>`;Uso livre e gratuito, com crédito à Terra Libris. Se você publicar algo usando a nossa agenda, adoraríamos saber — fale com a produção.