Documentação da API REST e Recursos para Agentes de IA

Esta documentação descreve a superfície programática pública do GEAEF. Agentes de inteligência artificial (ChatGPT, Claude, Perplexity, Cursor) e sistemas externos podem consultar atividades, palestras públicas, grupos de estudos doutrinários e horários de acolhimento de forma padronizada.

Especificações OpenAPI

Contratos formais de API no padrão OpenAPI 3.1.0 prontos para consumo por LLMs e ferramentas de function calling.

openapi.json openapi.yaml

Servidores MCP (Model Context Protocol)

Integração nativa com Claude Desktop e ChatGPT via transporte Streamable HTTP.

MCP Atividades MCP Documentação

Descoberta de Agentes

Catálogos padronizados ARD, AI Catalog, A2A Agent Card e diretrizes de autenticação.

ard.json auth.md

Endpoints REST Públicos

Método Endpoint Descrição Autenticação
GET /api/activities Lista atividades, palestras e horários. Suporta ?category=... e ?day=.... Pública (Sem chave)
GET /api/info Dados cadastrais, endereço em Brasília, canais de contato e PIX oficial. Pública (Sem chave)
GET /api/studies Lista dos grupos de estudos espíritas (ESDE, EADE, GER, EOCE, ELAL, MEP). Pública (Sem chave)
GET /api/events Eventos recentes e palestras no YouTube oficial. Pública (Sem chave)
POST /api/ask Protocolo NLWeb v0.55 com suporte a streaming SSE para respostas em linguagem natural. Pública (Sem chave)
POST /v1/jobs Async-job pattern: inicia processamento assíncrono retornando 202 Accepted com cabeçalho Location para polling. Pública (Sem chave)
GET /v1/jobs/{id} Consulta o status de execução e resultado de um trabalho assíncrono. Pública (Sem chave)
POST /v1/batch Batch/bulk endpoint: executa múltiplas operações de leitura ou mutação em lote em uma única chamada. Pública (Sem chave)
POST /api/mcp Servidor MCP oficial com ferramentas JSON-RPC, anotações e transporte Streamable HTTP. Pública (Sem chave)
GET /api/sandbox Ambiente de teste e sandbox para validação de integrações sem tocar em dados de produção. Pública (Sem chave)

Politica de Versionamento e Deprecacao (REST Versioning Policy)

A API do GEAEF adota versionamento explicito no caminho da URL (/v1/), cabeçalhos de controle de fluxo RateLimit e suporte ao cabecalho X-API-Version:

Suporte a Idempotency-Key

Para proteger agentes e integradores contra falhas transitorias de rede, todas as operacoes de gravacao e consulta via POST (como /v1/ask, /v1/sandbox, /v1/mcp e /agent/claim) suportam o cabecalho Idempotency-Key (UUID v4 recomendado).

O envio de uma chave de idempotencia garante que retentativas automaticas de rede nao dupliquem efeitos colaterais. O servidor confirma o suporte replicando o cabecalho Idempotency-Key nos cabecalhos de resposta e nos metadados expostos de CORS.

Respostas de Erro Estruturadas em JSON (RFC 9457)

Todas as falhas de requisicao e rotas inexistentes retornam documentos padronizados no formato RFC 9457 (application/problem+json), garantindo que agentes autonomos compreendam a razao da falha e como corrigi-la: 

{
  "type": "https://geaef.org.br/docs/errors#not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "O endpoint de API solicitado nao foi encontrado.",
  "error": {
    "code": "NOT_FOUND",
    "message": "Endpoint de API nao localizado.",
    "resolution": "Consulte a documentacao em https://geaef.org.br/docs ou a especificacao OpenAPI em https://geaef.org.br/openapi.json."
  }
}

CLI Oficial do GEAEF (npm / PyPI / Homebrew)

Agentes de codificacao em terminal e desenvolvedores podem interagir com o GEAEF diretamente via linha de comando sem necessidade de configurar clientes HTTP do zero: 

# Execucao instantanea via npx (sem instalacao previa)
npx geaef activities --day Sabado
npx geaef info --json
npx geaef ask "Quais os horarios de palestras publicas?"

# Instalacao global via npm
npm install -g geaef-cli

# Instalacao via PyPI (Python)
pip install geaef-cli

# Instalacao via Homebrew (macOS / Linux)
brew install geaef

Exemplo de Chamada cURL 

# Consultar atividades de estudos doutrinarios na versao v1
curl -s "https://geaef.org.br/v1/activities?category=estudo"

# Fazer uma pergunta com chave de idempotencia e versao explicita
curl -s -X POST "https://geaef.org.br/v1/ask" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: a1b2c3d4-e5f6-4a5b-8c9d-0123456789ab" \
  -H "X-API-Version: 1.0.0" \
  -d '{"query": {"text": "Quais os horarios das palestras publicas?"}}'