GET /v1/session/{session_id}

Reconstrua uma conversa completa para um session_id diretamente dos logs de requisição/resposta armazenados pela Floopy. Como o gateway já persiste cada turno, você pode restaurar um chat para um usuário final sem manter nenhum histórico de mensagens no seu próprio banco de dados — aponte seu cliente para este endpoint, receba de volta um array messages no formato OpenAI e continue a conversa.

O session_id é o valor que seu cliente enviou no header floopy-session-id no momento da requisição. Este endpoint é somente leitura e nunca gera um registro de log próprio.

Endpoint

GET https://api.floopy.ai/v1/session/{session_id}

Autenticação

Authorization: Bearer <sua-chave-de-api-floopy>

Permissão: read_permission na chave de API.
Disponível em todos os planos. Sujeito ao rate limit do seu plano (aplicado pelo gateway).
A conversa tem escopo de organização: a busca é fixada na organização dona da chave de API, então um session_id de outra organização é indistinguível de um inexistente (ambos retornam 404).

Parâmetros de caminho

Campo	Tipo	Obrigatório	Restrições
`session_id`	string	Sim	Recebe `trim` antes do uso. Vazio/somente espaços retorna `400`. Vinculado como parâmetro de consulta do ClickHouse — nunca interpolado no SQL — então qualquer valor é seguro.

Resposta (200)

{
  "session_id": "sess_demo_1",
  "messages": [
    { "role": "system", "content": "Você é um assistente prestativo." },
    { "role": "user", "content": "Qual é a capital da França?" },
    { "role": "assistant", "content": "A capital da França é Paris." },
    { "role": "user", "content": "E a população?" },
    { "role": "assistant", "content": "Cerca de 2,1 milhões na cidade." }
  ],
  "turn_count": 2,
  "turns": [
    {
      "request_id": "0c4a1d3f-7bea-4a1f-8b6e-2c0a8e4d3f10",
      "created_at": "2026-05-17T10:00:00Z",
      "model": "gpt-4o",
      "provider": "openai"
    },
    {
      "request_id": "1d5b2e4f-8cfb-4b2f-9c7f-3d1b9f5e4a21",
      "created_at": "2026-05-17T10:01:12Z",
      "model": "gpt-4o",
      "provider": "openai"
    }
  ]
}

Referência de campos

Campo	Tipo	Descrição
`session_id`	string	Eco do id de sessão solicitado.
`messages`	array	Conversa costurada, do mais antigo ao mais recente. Cada elemento é um objeto de mensagem cru no formato OpenAI (role, content, `tool_calls`, etc. preservados verbatim). Pronto para usar no campo `messages` de uma chamada `chat/completions` subsequente.
`turn_count`	integer	Número de turnos armazenados que contribuíram para `messages`.
`turns`	array	Proveniência por turno, na mesma ordem dos turnos que contribuíram.
`turns[].request_id`	string	Id da requisição de origem.
`turns[].created_at`	ISO8601	Timestamp da requisição no servidor (UTC).
`turns[].model`	string	Modelo que atendeu aquele turno.
`turns[].provider`	string	Provider que atendeu aquele turno.

Como funciona a reconstrução

A Floopy percorre os turnos da sessão em ordem cronológica e os costura em um único array de mensagens:

O primeiro turno inicializa messages com o histórico completo da sua requisição (assim um system prompt e qualquer contexto anterior enviado pelo cliente são preservados).
Cada turno seguinte contribui com a resposta do assistant mais quaisquer mensagens novas ao final da requisição daquele turno. Isso funciona tanto se o cliente reenvia o histórico completo a cada chamada (stateful) quanto se envia apenas a nova mensagem (stateless).

Limitações:

Uma sessão é limitada aos seus 500 turnos mais recentes, retornados do mais antigo ao mais recente.
Turnos que não são chat completions bem-sucedidos são ignorados e não contam para turn_count: respostas não-2xx, respostas em streaming (corpos SSE) e endpoints não-chat como embeddings.

Erros

Status	código `error`	Quando
`400`	`invalid_request`	`session_id` vazio ou somente espaços após o `trim`.
`401`	`unauthorized`	Chave de API ausente ou inválida.
`403`	`read_permission`	A chave não tem `read_permission`.
`404`	`not_found`	Não existem turnos para esse `session_id` na organização do chamador. Bytes idênticos para buscas cross-tenant, para não vazar existência.
`429`	`rate_limited`	Rate limit do plano excedido. Inclui `Retry-After`.
`502`	`bad_gateway`	Store de analytics indisponível.

Exemplo curl

curl -s -H "Authorization: Bearer $FLOOPY_API_KEY" \
  "https://api.floopy.ai/v1/session/sess_demo_1"

Veja também

GET /v1/decisions/{request_id} — auditoria de roteamento de uma requisição.
Referência de headers — como definir floopy-session-id.
SDK Node — client.sessions.get(sessionId).