---
title: "Documentação da API e Recursos para Desenvolvedores - GEAEF"
description: "Documentação da API REST, servidores MCP e protocolos de agentes de IA do GEAEF."
canonical: "https://geaef.org.br/docs"
last-updated: 2026-10-20
---

# Documentação da API e Agentes - GEAEF

O Grupo Educacional e Assistencial Espírita Fraternidade (GEAEF) oferece uma API REST pública e servidores MCP para permitir que agentes de inteligência artificial e desenvolvedores consultem dados da casa com transparência.

## Endpoints Disponíveis

- **GET /api/activities:** Lista completa de atividades da casa, palestras, grupos de estudo e atendimentos fraternos. Suporta parâmetros `category`, `day`, `limit` e `offset`.
- **GET /api/info:** Informações institucionais, endereço em Brasília, canais de contato e dados para doações PIX.
- **GET /api/studies:** Detalhes de turmas, programas e livros dos grupos de estudos doutrinários (ESDE, EADE, GER, EOCE, ELAL, MEP). Suporta parâmetros `limit` e `offset`.
- **GET /api/events:** Eventos recentes e palestras gravadas no YouTube. Suporta parâmetros `limit` e `offset`.
- **POST /api/ask:** Protocolo NLWeb v0.55 com suporte a streaming Server-Sent Events (SSE) para responder dúvidas em linguagem natural.
- **POST /api/mcp:** Servidor MCP oficial via transporte Streamable HTTP expondo ferramentas de busca e escrita (`submit_study_interest`).
- **GET /api/sandbox:** Ambiente de simulação para agentes testarem chamadas.
- **POST /v1/jobs:** Criação assíncrona de jobs para agentes com retorno HTTP 202 Accepted e cabeçalho `Location`.
- **GET /v1/jobs/{id}:** Consulta de status e resultado de tarefas em segundo plano.
- **POST /v1/batch:** Execução de requisições em lote para múltiplas operações da API em uma única chamada.

## Controle de Taxa (RFC Rate Limiting)

Para proteger a infraestrutura e orientar agentes autônomos sobre cotas de requisição, as respostas da API contêm cabeçalhos padronizados da IETF:
- `RateLimit-Limit`: Cota máxima de requisições permitida na janela de tempo.
- `RateLimit-Remaining`: Requisições restantes disponíveis na janela corrente.
- `RateLimit-Reset`: Tempo restante em segundos até a renovação da cota.
- `RateLimit-Policy`: Política de cota aplicada.

## Paginação Padronizada

Endpoints que retornam coleções (`/api/activities`, `/api/studies`, `/api/events`) suportam paginação consistente:
- `limit` (inteiro, padrão: 20, máximo: 100): Quantidade máxima de registros retornados.
- `offset` (inteiro, padrão: 0): Posição inicial do deslocamento.
As respostas incluem o objeto de metadados `pagination` com `total`, `limit`, `offset` e indicador booleano `hasMore`.

## Politica de Versionamento e Deprecacao (REST Versioning Policy)

A API do GEAEF adota versionamento explicito no caminho da URL (/v1/) e suporte ao parametro de cabecalho X-API-Version.

- **URL Base v1 (Recomendada):** `https://geaef.org.br/v1/`
- **Prefixos compativeis:** `https://geaef.org.br/api/` e `https://geaef.org.br/api/v1/`
- **Politica de Deprecacao:** Qualquer descontinuacao de rota ou campo e anunciada com antecedencia minima de 180 dias atraves dos cabecalhos HTTP RFC 8594 (`Deprecation` e `Sunset`). Mudancas incompativeis geram uma nova versao maior (/v2/).
- **Cabecalhos de Versao:** Respostas incluem `X-API-Version: 1.0.0` e `API-Version: 1.0.0`.

## Suporte a Idempotency-Key

Para operacoes de mutacao e consulta POST (`/v1/ask`, `/v1/sandbox`, `/v1/mcp`, `/agent/claim`), agentes podem enviar o cabecalho `Idempotency-Key` (UUID v4 recomendado).
Isso garante retentativas seguras em caso de oscilacoes de rede, sem risco de duplicacao. O servidor confirma a recepcao replicando o cabecalho `Idempotency-Key` na resposta.

## Respostas de Erro Estruturadas em JSON (RFC 9457)

Todas as rotas de API e endpoints inexistentes retornam respostas de erro tipadas em JSON (`application/problem+json`) contendo codigo da falha, mensagem explicativa e dica de resolucao:

```json
{
  "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 e desenvolvedores podem interagir com os servicos do GEAEF diretamente pelo terminal:

```bash
# Execucao direta sem instalacao via npx
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 Python / PyPI
pip install geaef-cli

# Instalacao via Homebrew
brew install geaef
```

## Especificações Técnicas

- [OpenAPI v3.1 Spec (JSON)](https://geaef.org.br/openapi.json)
- [OpenAPI v3.1 Spec (YAML)](https://geaef.org.br/api/openapi.yaml)
- [Catálogo ARD](https://geaef.org.br/.well-known/ard.json)
- [Guia de Autenticação (auth.md)](https://geaef.org.br/auth.md)
- [Repositório GitHub Oficial (.cursorrules e AGENTS.md)](https://github.com/roberto-mota20/geaef.org.br)
- [Registro no Smithery MCP Registry](https://smithery.ai/servers/roberto-mota20/geaef)
- [Registro no mcp.so MCP Registry](https://mcp.so/server/geaef)