Histórico de Chat¶

O Nodexa armazena o histórico de conversas de cada usuário. Você pode recuperar a lista de conversas de um usuário e buscar as mensagens de qualquer conversa específica.

Autenticação¶

Todos os endpoints de histórico de chat requerem uma API key e o header x-user-id identificando o usuário cujo histórico você está consultando.

-H "x-api-key: nxk_your_api_key_here"
-H "x-user-id: user_abc123"

Endpoints¶

Listar conversas — `GET /v1/chat/history/conversations`¶

Retorna todas as conversas do usuário especificado, ordenadas pela mais recentemente atualizada.

Headers da request:

Header	Obrigatório	Descrição
`x-api-key`	Sim	Sua API key do Nodexa
`x-user-id`	Sim	O usuário cujas conversas você quer listar

Resposta — 200 OK:

[
  {
    "id": "12e84095-d5e2-4b3a-9f1c-8e7d6c5b4a3f",
    "title": "Say hello for history test.",
    "isActive": true,
    "createdAt": "2026-03-30T09:56:18.533Z",
    "updatedAt": "2026-03-30T09:56:22.796Z",
    "assistantId": "5c110f7f-1234-5678-abcd-ef0123456789"
  }
]

Campo	Tipo	Descrição
`id`	`string`	ID único da conversa
`title`	`string`	Título gerado automaticamente com base na primeira mensagem
`isActive`	`boolean`	Se a conversa ainda está ativa
`createdAt`	`string`	Timestamp ISO 8601 de quando a conversa começou
`updatedAt`	`string`	Timestamp ISO 8601 da última mensagem
`assistantId`	`string`	O assistant que tratou a conversa

fetchcurl

const res = await fetch(
  'https://app.nodexa.cloud/v1/chat/history/conversations',
  {
    headers: {
      'x-api-key': process.env.NODEXA_API_KEY,
      'x-user-id': userId,
    },
  }
);

const conversations = await res.json();
console.log(`${conversations.length} conversation(s) found`);

curl "https://app.nodexa.cloud/v1/chat/history/conversations" \
  -H "x-api-key: nxk_your_api_key_here" \
  -H "x-user-id: user_abc123"

Obter mensagens — `GET /v1/chat/history/conversations/:id/messages`¶

Retorna todas as mensagens de uma conversa específica. A conversa deve pertencer ao usuário identificado por x-user-id — tentar buscar a conversa de outro usuário retorna 404.

Parâmetros de path:

Parâmetro	Tipo	Descrição
`id`	`string`	O ID da conversa (obtido no endpoint de listagem)

Headers da request:

Header	Obrigatório	Descrição
`x-api-key`	Sim	Sua API key do Nodexa
`x-user-id`	Sim	Deve corresponder ao dono da conversa

Resposta — 200 OK:

[
  {
    "id": "msg_01234567-89ab-cdef-0123-456789abcdef",
    "role": "user",
    "content": "Hello, can you help me?",
    "createdAt": "2026-03-30T09:56:18.533Z"
  },
  {
    "id": "msg_abcdef01-2345-6789-abcd-ef0123456789",
    "role": "assistant",
    "content": "Of course! What do you need help with?",
    "createdAt": "2026-03-30T09:56:22.796Z"
  }
]

fetchcurl

const conversationId = '12e84095-d5e2-4b3a-9f1c-8e7d6c5b4a3f';

const res = await fetch(
  `https://app.nodexa.cloud/v1/chat/history/conversations/${conversationId}/messages`,
  {
    headers: {
      'x-api-key': process.env.NODEXA_API_KEY,
      'x-user-id': userId,
    },
  }
);

if (res.status === 404) {
  console.error('Conversation not found or does not belong to this user');
} else {
  const messages = await res.json();
  messages.forEach(m => console.log(`[${m.role}] ${m.content}`));
}

curl "https://app.nodexa.cloud/v1/chat/history/conversations/12e84095-d5e2-4b3a-9f1c-8e7d6c5b4a3f/messages" \
  -H "x-api-key: nxk_your_api_key_here" \
  -H "x-user-id: user_abc123"

Isolamento por Usuário¶

O histórico de chat é estritamente isolado por usuário. O header x-user-id controla quais dados são retornados. Uma request para uma conversa que existe mas pertence a outro usuário retorna 404 Not Found — a mesma resposta de uma conversa que não existe. Isso previne enumeração de usuários.

Nunca exponha API keys no browser

Não chame esses endpoints diretamente do código client-side. Seu backend deve fazer proxy das requests de histórico, injetando o x-api-key e o x-user-id do usuário autenticado no lado do servidor.

Padrão de Uso Típico¶

Um padrão comum é mostrar uma barra lateral de histórico na sua interface de chat:

Ao carregar a página, chame GET /v1/chat/history/conversations para listar as conversas recentes do usuário atual.
Quando o usuário clicar em uma conversa, chame GET /v1/chat/history/conversations/:id/messages para carregar suas mensagens.
Renderize as mensagens e permita que o usuário continue a conversa usando o previous_response_id da última mensagem.

Confira Continuidade de Conversas para saber como continuar uma conversa existente.