Viewing Chat History

In Caddie, a "chat" refers to a particular chat session between a user and an Agent. Within a particular chat, one or more "messages" can be exchanged. Caddie offers a few endpoints to make this data accessible.

List full chat history

To view chat history, make a request to the /agent-id/history endpoint. Make sure your organization ID header matches the organization that the Agent is part of.

The endpoint supports two optional query parameters:

• "limit": the default limit on number of results is 10, but this can be changed using the "limit" parameter
• "userId": by default, API requests will return all the chat sessions for the user that X-API-KEY belongs to To view another user's chat history, specify that user's id in the userId query parameter
• "userEmail": an alternate way to limit your search to a specific user's chats, using their email rather than ID to identify them. Note: You cannot provide both "userId" and "userEmail" simultaneously as query parameters.

fetch('http://localhost:3000/api/agent/agent-id-here/history?limit=20&userId=id-of-chat-user&', {
  method: 'GET',
  headers: {
    'X-API-KEY': 'your-api-key',
    'X-Organization-ID': ''
  }
})

Here's the schema returned by this endpoint:

{
  "chats": [
    {
      "id": "string",
      "createdAt": "UTC timestamp string",
      "title": "string",
      "userId": "string",
      "visibility": "string, defaults to private"
    },
    {
      "id": "string",
      "createdAt": "UTC timestamp string",
      "title": "string",
      "userId": "string",
      "visibility": "string, defaults to private"
    },
  ],
  "hasMore": false
}

The "hasMore" value indicates whether your "limit" parameter allowed the response to include the full chat history. Chats are returned in chronological order, with the most recent chats at the top.

View specific chat session

To view a specific chat in detail, including metadata along with all of the messages send back and forth between the user and the Agent, make a request to the /api/chat endpoint

fetch('http://localhost:3000/api/chat/your-chat-id', {
  method: 'GET',
  headers: {
    'X-API-KEY': 'your-api-key',
    'X-Organization-ID': ''
  }
});

The response will contain metadata, along with an array of JSON chatMessageHistory objects. Each message within the chatMessageHistory array has its own entry, including both messages sent from the user to the Agent, and responses from the Agent back to the user.

Response schema:

{
  chatMetadata: {
    id: string;
    createdAt: Date;
    title: string;
    userId: string;
    impersonatedById: string | null;
    agentId: string;
    visibility: "public" | "private";
  },
  chatMessageHistory: {
    id: string;
    chatId: string;
    role: string;
    parts: unknown;
    attachments: unknown;
    createdAt: Date;
  }[]
}

Deleting a chat session

Chat sessions can be deleted by issuing a DELETE request to the /api/chat/delete endpoint, providing chat id as a query parameter.

fetch('http://localhost:3000/api/chat?id=chat-session-id', {
  method: 'DELETE',
  headers: {
    'X-API-KEY': '',
    'X-Organization-ID': ''
  },
});