REST · precisa de chave

API Oportuna

O mural no site é livre. Para o seu app consultar a base, manda a chave no header. CORS liberado. Datas em AAAA-MM-DD. Teto: 120/min e 5000/dia por chave.

Pedir chave Abrir /api

Uma chamada

curl -H "Authorization: Bearer opt_SUA_CHAVE" \
  "https://SEU_HOST/api/oportunidades?status=abertas&limit=todas"

Também vale o header X-Api-Key. A resposta vem como { "data": [...], "meta": { total, page, limit, totalPages } }.

Custo, sem enrolação

Cada GET na API gasta um pouquinho de servidor (função) e de banda. No Hobby da Vercel isso é de graça até um volume alto — pensa em centenas de milhares de chamadas no mês, não em um app de faculdade.

A chave não é para te cobrar. É para um robô não baixar o mural 80 mil vezes e queimar o plano. Se um dia o tráfego real crescer, a gente aperta o teto ou sobe o plano. Não existe “R$ por bolsa”.

Endpoints

Método	Caminho	O que faz
POST	`/api/chaves` Pede uma chave. Corpo: nome, email, projeto. A chave volta uma vez só.	Pede uma chave. Corpo: nome, email, projeto. A chave volta uma vez só.
GET	`/api` Índice da API — este não precisa de chave.	Índice da API — este não precisa de chave.
GET	`/api/taxonomia` Tipos, áreas, níveis, modalidades e países, cada um com a contagem atual.	Tipos, áreas, níveis, modalidades e países, cada um com a contagem atual.
GET	`/api/oportunidades` Lista a base. Sem filtro devolve as inscrições ainda abertas. Use limit=todas para puxar tudo de uma vez.	Lista a base. Sem filtro devolve as inscrições ainda abertas. Use limit=todas para puxar tudo de uma vez.
GET	`/api/oportunidades/:id` Detalhe de uma oportunidade, incluindo URL de inscrição.	Detalhe de uma oportunidade, incluindo URL de inscrição.

Filtros

Filtro	Uso
`q`	Busca em título, subtítulo, organização, descrição, tags e requisitos.
`tipo`	bolsa, evento, curso, estagio, intercambio ou concurso. Vários valores separados por vírgula.
`area`	Ex.: Ciência da Computação, Engenharia, Saúde.
`nivel`	ensino-medio, graduacao, pos-graduacao ou todos.
`modalidade`	presencial, remoto ou hibrido.
`pais`	Brasil, Alemanha, Estados Unidos…
`status`	abertas (padrão), encerradas ou todas.
`ordenar`	prazo (padrão), recentes ou titulo.
`page`	Página, a partir de 1.
`limit`	Itens por página (padrão 50, máximo 10000). Use todas para o acervo inteiro.

Erros

Sempre no formato { "error": { "code", "message", "details?" } }. Sem chave: missing_api_key (401). Estourou teto: rate_limited (429). Outros: not_found (404), invalid_json (400), validation_error (422).