📡 API Documentation - Cidadão.AI
Autor: Anderson Henrique da Silva
Última Atualização: 2025-09-25 18:20:00 -03:00 (São Paulo, Brasil)
🌐 Visão Geral
API RESTful para análise de transparência governamental com sistema multi-agente de IA.
Base URL: https://api.cidadao.ai (produção) ou http://localhost:8000 (desenvolvimento)
🔐 Autenticação
JWT Bearer Token
Authorization: Bearer <token>
Obter Token
POST /api/v1/auth/login
Content-Type: application/json
{
"email": "[email protected]",
"password": "senha123"
}
Resposta:
{
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
"refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
"token_type": "bearer",
"expires_in": 3600
}
💬 Chat API
Enviar Mensagem
POST /api/v1/chat/message
Authorization: Bearer <token>
Content-Type: application/json
{
"message": "Quero investigar contratos do Ministério da Saúde",
"session_id": "uuid-da-sessao"
}
Resposta:
{
"response": "Vou analisar os contratos do Ministério da Saúde...",
"session_id": "uuid-da-sessao",
"agent": "zumbi",
"intent": "investigate",
"metadata": {
"processing_time": 1.23,
"cache_hit": false,
"timestamp": "2025-09-25T18:20:00Z"
}
}
Streaming de Resposta (SSE)
POST /api/v1/chat/stream
Authorization: Bearer <token>
Content-Type: application/json
Accept: text/event-stream
{
"message": "Analise detalhada dos gastos",
"session_id": "uuid-da-sessao"
}
Resposta (Server-Sent Events):
data: {"chunk": "Iniciando análise", "type": "start"}
data: {"chunk": "Encontrei 15 contratos", "type": "progress"}
data: {"chunk": "Análise completa", "type": "complete"}
Histórico de Conversa
GET /api/v1/chat/history/{session_id}/paginated?cursor=&limit=20
Authorization: Bearer <token>
Resposta:
{
"messages": [
{
"id": "msg-uuid",
"role": "user",
"content": "Olá",
"timestamp": "2025-09-25T18:00:00Z"
},
{
"id": "msg-uuid-2",
"role": "assistant",
"content": "Olá! Como posso ajudar?",
"timestamp": "2025-09-25T18:00:01Z",
"agent": "drummond"
}
],
"next_cursor": "eyJpZCI6ICJtc2ctdXVpZC0zIn0=",
"has_more": true
}
🔍 Investigações
Criar Investigação
POST /api/v1/investigations/analyze
Authorization: Bearer <token>
Content-Type: application/json
{
"title": "Análise de Contratos 2025",
"description": "Investigar anomalias em contratos",
"target_type": "contract",
"parameters": {
"org_code": "26000",
"date_start": "2025-01-01",
"date_end": "2025-09-25"
}
}
Resposta:
{
"investigation_id": "inv-uuid",
"status": "processing",
"created_at": "2025-09-25T18:20:00Z",
"estimated_time": 30
}
Status da Investigação
GET /api/v1/investigations/{investigation_id}
Authorization: Bearer <token>
Resposta:
{
"id": "inv-uuid",
"status": "completed",
"progress": 100,
"results": {
"anomalies_found": 5,
"risk_score": 0.72,
"summary": "Encontradas 5 anomalias significativas",
"details": [...]
},
"created_at": "2025-09-25T18:20:00Z",
"completed_at": "2025-09-25T18:25:00Z"
}
🤖 Agentes
Listar Agentes Disponíveis
GET /api/v1/agents/status
Authorization: Bearer <token>
Resposta:
{
"agents": [
{
"name": "zumbi",
"display_name": "Zumbi dos Palmares",
"role": "Investigador de Anomalias",
"status": "operational",
"capabilities": ["anomaly_detection", "pattern_analysis"],
"load": 0.45
},
{
"name": "anita",
"display_name": "Anita Garibaldi",
"role": "Analista de Padrões",
"status": "operational",
"capabilities": ["trend_analysis", "correlation"],
"load": 0.32
}
]
}
Análise Direta com Agente
POST /api/agents/zumbi
Authorization: Bearer <token>
Content-Type: application/json
{
"action": "analyze_contracts",
"data": {
"contracts": [...],
"threshold": 2.5
}
}
📊 Portal da Transparência
Buscar Contratos
GET /api/v1/transparency/contracts?codigoOrgao=26000&pagina=1
Authorization: Bearer <token>
Resposta:
{
"contratos": [
{
"numero": "01/2025",
"fornecedor": "Empresa XYZ",
"valor": 150000.00,
"dataAssinatura": "2025-01-15",
"objeto": "Serviços de TI"
}
],
"total": 150,
"pagina": 1,
"totalPaginas": 15
}
Buscar Servidor Público
GET /api/v1/transparency/servants?cpf=***.680.938-**
Authorization: Bearer <token>
Resposta:
{
"servidor": {
"nome": "FULANO DE TAL",
"cargo": "Analista",
"orgao": "Ministério XYZ",
"situacao": "Ativo"
}
}
📈 Monitoramento
Health Check
GET /health
Resposta:
{
"status": "healthy",
"version": "1.0.0",
"timestamp": "2025-09-25T18:20:00Z"
}
Métricas Detalhadas
GET /health/detailed
Authorization: Bearer <token>
Resposta:
{
"status": "healthy",
"services": {
"database": "connected",
"redis": "connected",
"agents": "operational"
},
"metrics": {
"uptime_seconds": 86400,
"total_requests": 15000,
"active_investigations": 12,
"cache_hit_rate": 0.92
}
}
🚨 Códigos de Erro
| Código | Descrição | Exemplo |
|---|---|---|
| 400 | Bad Request | Parâmetros inválidos |
| 401 | Unauthorized | Token inválido ou expirado |
| 403 | Forbidden | Sem permissão para o recurso |
| 404 | Not Found | Recurso não encontrado |
| 429 | Too Many Requests | Rate limit excedido |
| 500 | Internal Server Error | Erro do servidor |
Formato de Erro
{
"error": {
"code": "INVALID_PARAMETER",
"message": "O parâmetro 'codigoOrgao' é obrigatório",
"details": {
"field": "codigoOrgao",
"requirement": "string, 5 digits"
}
},
"timestamp": "2025-09-25T18:20:00Z"
}
⚡ Rate Limiting
| Tier | Limite | Janela |
|---|---|---|
| Anônimo | 10 req | 1 min |
| Autenticado | 60 req | 1 min |
| Premium | 300 req | 1 min |
| Admin | Ilimitado | - |
Headers de resposta:
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1632582000
🔄 WebSocket
Chat em Tempo Real
const ws = new WebSocket('wss://api.cidadao.ai/api/v1/ws/chat/{session_id}');
ws.onopen = () => {
ws.send(JSON.stringify({
type: 'message',
content: 'Olá!'
}));
};
ws.onmessage = (event) => {
const data = JSON.parse(event.data);
console.log('Resposta:', data);
};
📡 API Documentation - Cidadão.AI (English)
Author: Anderson Henrique da Silva
Last Updated: 2025-09-25 18:20:00 -03:00 (São Paulo, Brazil)
🌐 Overview
RESTful API for government transparency analysis with multi-agent AI system.
Base URL: https://api.cidadao.ai (production) or http://localhost:8000 (development)
🔐 Authentication
JWT Bearer Token
Authorization: Bearer <token>
Get Token
POST /api/v1/auth/login
Content-Type: application/json
{
"email": "[email protected]",
"password": "password123"
}
Response:
{
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
"refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
"token_type": "bearer",
"expires_in": 3600
}
[Continue with English translations of all sections above...]