Skip to content

Chat History

Nodexa stores a history of conversations for each user. You can retrieve the list of conversations a user has had, and fetch the messages within any specific conversation.

Authentication

All chat history endpoints require an API key and the x-user-id header identifying the user whose history you are querying.

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

Endpoints

List conversations — GET /v1/chat/history/conversations

Returns all conversations for the specified user, ordered by most recently updated.

Request headers:

Header Required Description
x-api-key Yes Your Nodexa API key
x-user-id Yes The user whose conversations to list

Response — 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"
  }
]
Field Type Description
id string Unique conversation ID
title string Auto-generated title based on the first message
isActive boolean Whether the conversation is still active
createdAt string ISO 8601 timestamp when the conversation started
updatedAt string ISO 8601 timestamp of the last message
assistantId string The assistant that handled the conversation 
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"

Get messages — GET /v1/chat/history/conversations/:id/messages

Returns all messages in a specific conversation. The conversation must belong to the user identified by x-user-id — attempting to fetch another user's conversation returns 404.

Path parameters:

Parameter Type Description
id string The conversation ID (from the list endpoint)

Request headers:

Header Required Description
x-api-key Yes Your Nodexa API key
x-user-id Yes Must match the owner of the conversation

Response — 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"
  }
]

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"

User Isolation

Chat history is strictly isolated per user. The x-user-id header controls which user's data is returned. A request for a conversation that exists but belongs to a different user returns 404 Not Found — the same response as a conversation that does not exist at all. This prevents user enumeration.

Never expose API keys to the browser

Do not call these endpoints directly from client-side code. Your backend should proxy history requests, injecting the x-api-key and the authenticated user's x-user-id on the server side.

Typical Usage Pattern

A common pattern is to show a history sidebar in your chat UI:

  1. On page load, call GET /v1/chat/history/conversations to list recent conversations for the current user.
  2. When the user clicks a conversation, call GET /v1/chat/history/conversations/:id/messages to load its messages.
  3. Render the messages and allow the user to continue the conversation using the last message's previous_response_id for threading.

See Conversation Threading for how to continue an existing conversation.