AI-inovyo-assistende-db/docs/api-reference.md

Referência da API

A API REST é servida pelo FastAPI na porta 8000, implementada em app/api.py e orquestrada por app/backend/orquestrador.py.

Endpoints

GET /

Health check da aplicação.

Resposta:

{
  "status": "ok"
}

---

POST /agent

Executa uma consulta no agente analítico.

Request Body (QueryRequest):

Campo	Tipo	Obrigatório	Descrição
query	string	Sim	Pergunta do usuário em português
history	string	Não	Histórico de mensagens anteriores (serializado)
model	string	Não	ID do modelo LLM (padrão: Claude Haiku)
base	string	Não	Nome do dashboard/base de dados

Response Body (QueryResponse):

Campo	Tipo	Descrição
response	string	Resposta do agente em português
input_tokens	int	Total de tokens de entrada consumidos
output_tokens	int	Total de tokens de saída gerados
total_tokens	int	Total de tokens (input + output)

Exemplo — cURL:

curl -X POST http://localhost:8000/agent \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Qual foi meu NPS?",
    "history": "",
    "model": "anthropic.claude-haiku-4-5-20251001-v1:0",
    "base": "nome_do_dashboard"
  }'

Exemplo — Resposta:

{
  "response": "O NPS foi...",
  "input_tokens": 1250,
  "output_tokens": 340,
  "total_tokens": 1590
}

Modelos Disponíveis

ID do Modelo	Provider
anthropic.claude-haiku-4-5-20251001-v1:0	Anthropic
anthropic.claude-sonnet-4-5-20250929-v1:0	Anthropic
meta.llama4-maverick-17b-instruct-v1:0	Meta
meta.llama4-scout-17b-instruct-v1:0	Meta
amazon.nova-lite-v1:0	Amazon
amazon.nova-pro-v1:0	Amazon
amazon.nova-2-lite-v1:0	Amazon

Bases Disponíveis

As bases são carregadas dinamicamente do DynamoDB (tabela TABLE, index item_type_index, item_type = "contexto"). O formato do nome segue o padrão {cliente}_{dashboard}.

Documentação Interativa

Com a aplicação rodando:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc