Referência da API · Sessões e Mensagens

API de Sessões e Mensagens de Chat

Crie, liste, renomeie, fixe, favorite e exclua sessões de chat, além de gerenciar mensagens individuais — com histórico de edições rastreado e opção de desfazer.

← Voltar à documentação Ir para os endpoints

Endpoints de sessão

POST /api/v1/sessions

GET /api/v1/sessions

GET /api/v1/sessions/{session_id}/messages

PATCH /api/v1/sessions/{session_id}

DELETE /api/v1/sessions/{session_id}

Endpoints de mensagens

GET /api/v1/messages/{message_id}

PATCH /api/v1/messages/{message_id}

GET /api/v1/messages/{message_id}/history

POST /api/v1/messages/{message_id}/undo

DELETE /api/v1/messages/{message_id}

Criar Sessão — Corpo da Requisição

json

{
  "title": "Untitled Chat",
  "kind": "chat",
  "folder_id": null,
  "agent_id": null,
  "metadata": {}
}

workspace_id não é aceito pelo cliente em runtimes pessoais, e caso exista deve corresponder ao contexto de runtime do workspace ativo — não é tratado como uma sobreposição arbitrária enviada pelo cliente.

Listar — Parâmetros de consulta e resposta

kindagent_idpinnedlimit (padrão 50, máximo 200)offset (padrão 0)

json

{
  "items": [ { "id": "...", "title": "...", "pinned": false, "...": "..." } ],
  "total": 12,
  "limit": 50,
  "offset": 0
}

Atualizar Sessão (PATCH)

Pelo menos um campo deve estar presente no corpo da requisição — um PATCH vazio é rejeitado.

titlepinnedstarredmarked_unread

json

{
  "pinned": true,
  "starred": false
}

Comportamentos da sessão

Uma sessão pertence a exatamente um proprietário (um usuário, opcionalmente vinculado a um workspace) — isso é determinado pelo contexto de autenticação da requisição, não pela entrada do cliente.
Excluir uma sessão é uma remoção lógica (deleted_at é definido); a sessão e suas mensagens permanecem no banco de dados, mas são excluídas de todas as consultas padrão.
GET /sessions/{session_id}/messages retorna uma contagem de mensagens calculada em tempo real a partir das próprias mensagens, e não de um contador em cache.
Os parâmetros de caminho session_id e message_id são validados como UUIDs — um ID malformado gera um erro de validação claro, não um erro de servidor.
As sessões de demonstração do site de marketing são limitadas a 3 por usuário e retornam 403 quando esse limite é atingido.

Histórico de edições de mensagens e Desfazer

Toda edição do conteúdo ou do payload de uma mensagem é registrada antes de a alteração ser aplicada, preservando a versão anterior.

json

[
  {
    "id": "8f14e...",
    "old_content": "Original message text",
    "old_payload": null,
    "edited_at": "2026-07-30T16:40:00Z"
  }
]

Uma mensagem só pode ser editada ou excluída pelo proprietário da sessão a que pertence.
Desfazer restaura a versão registrada mais recente e remove essa entrada do histórico — não volta além da última edição.
Editar ou excluir uma mensagem não ajusta atualmente o campo de contagem em cache da sessão; esse campo sempre reflete a contagem em tempo real.

Modelos de erro

400

Solicitação inválida — por exemplo, corpo PATCH vazio ou nenhuma alteração detectada.

401

Autenticação ausente ou inválida.

404

Sessão ou mensagem não encontrada (ou não pertencente ao solicitante).

Exemplos

Criar sessão

bash

curl -X POST "/api/v1/sessions" \
  -H "Authorization: Bearer [token]" \
  -H "Content-Type: application/json" \
  -d '{"title": "New Chat", "kind": "chat"}'

Fixar sessão

bash

curl -X PATCH "/api/v1/sessions/[session_id]" \
  -H "Authorization: Bearer [token]" \
  -H "Content-Type: application/json" \
  -d '{"pinned": true}'

Editar mensagem

bash

curl -X PATCH "/api/v1/messages/[message_id]" \
  -H "Authorization: Bearer [token]" \
  -H "Content-Type: application/json" \
  -d '{"content": "Corrected message text"}'

Desfazer a última edição

bash

curl -X POST "/api/v1/messages/[message_id]/undo" \
  -H "Authorization: Bearer [token]"