Add analytics to any OpenAI compatible chat

With Inkeep's Analytics API, you can log your AI chat conversations to:

Get Inkeep's analytics and reporting for the chats
Provide and track "Thumbs up/down" feedback
Power "Share" or "Saved Chats" experiences

The Inkeep Analytics API is designed to be flexible and can log any OpenAI-compatible conversation, including those with tool calls or custom functionality.

If you're using Inkeep's Chat API to create your own chat UX or custom copilot, you should use the Analytics API to enable the same reporting as provided by the @inkeep/cxkit-react component library.

Authentication

All Analytics API endpoints require authentication using an API key in the request headers. See our Authentication Page for details.

Log a conversation

Initial message

To log a new conversation, make a POST request to the /conversations endpoint.

const initialConversationData = {
  id: "conv_1234", // optional
  type: "openai",
  messages: [
    {
      role: "user",
      content: "Can I log any OpenAI-compatible conversation?",
    },
    {
      role: "assistant",
      content:
        "Yes, our analytics engine is agnostic. You can log full conversations of your agent or custom copilot, even if not all interactions hit Inkeep's API endpoint.",
    },
  ],
  properties: {
    // Add any custom properties here
  },
  userProperties: {
    // Add any user-specific properties here
  },
};
 
let currentConversation = await fetch(
  "https://api.analytics.inkeep.com/conversations",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify(initialConversationData),
  }
).then((response) => {
  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }
  return response.json();
});
 
console.log(currentConversation);

Follow-up messages

To log additional messages in an existing conversation, include the id returned from the initial submission:

const continueConversationData = {
  id: currentConversation.id,
  type: "openai",
  messages: [
    ...currentConversation.messages,
    // Add new messages
    {
      role: "user",
      content: "Does that mean it supports logging tool calls?",
    },
    {
      role: "assistant",
      content:
        "Yup, Inkeep's Analytics API is fully compatible with OpenAI chat completions endpoints, including tool calling.",
    },
  ],
};
 
currentConversation = await fetch(
  "https://api.analytics.inkeep.com/conversations",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify(continueConversationData),
  }
).then((response) => {
  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }
  return response.json();
});
 
console.log(currentConversation);

Note

You can provide your own IDs for conversations and messages, or Inkeep will auto-generate them. For logging continuous exchanges in a conversation, make sure to retain and use the same conversation ID and always include the entire message history. POST /conversation works like an upsert operation.

Submit feedback

Use the /feedback endpoint to log 👍 / 👎 feedback from your UI.

const feedbackData = {
  type: "positive", // or "negative"
  messageId: "{assistant_message_id}", // e.g. currentConversation.messages[1].id
  reasons: [
    {
      label: "accurate_code_snippet",
      details: "The code worked perfectly.",
    },
  ],
  userProperties: {
    // Add any user-specific properties here
  },
};
 
fetch("https://api.analytics.inkeep.com/feedback", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify(feedbackData),
})
  .then((response) => response.json())
  .then((data) => console.log(data));

Monitor

To view analytics for your logged conversations and feedback:

Go to portal.inkeep.com
Navigate to Projects and select the relevant one
View the Chat Sessions, Insights, and Analytics tabs

You can use the GET /conversations endpoint to retrieve logged conversations and power "Share" or "Saved Chats" features.

Here's an example of how to fetch a specific conversation:

fetch(
  "https://api.analytics.inkeep.com/conversations/{existing_conversation_id}",
  {
    method: "GET",
    headers: {
      Authorization: "Bearer YOUR_API_KEY",
    },
  }
)
  .then((response) => response.json())
  .then((data) => {
    // Use the conversation data to rehydrate your UI
    console.log(data);
  });

The response will contain detailed information about the conversation:

{
  "id": "conv_123456789",
  "type": "openai",
  "createdAt": "2024-07-11T10:15:30.123Z",
  "updatedAt": "2024-07-11T10:16:45.678Z",
  "projectId": "proj_987654321",
  "integrationId": "intg_246813579",
  "properties": {
    "source": "web_chat"
  },
  "userProperties": {
    "userId": "user_135792468"
  },
  "messages": [
    {
      "id": "msg_1",
      "type": "openai",
      "conversationId": "conv_123456789",
      "createdAt": "2024-07-11T10:15:30.123Z",
      "updatedAt": "2024-07-11T10:15:30.123Z",
      "role": "user",
      "content": "Can I log any OpenAI-compatible conversation?",
      "name": null,
      "links": null,
      "properties": {},
      "userProperties": {}
    },
    {
      "id": "msg_2",
      "type": "openai",
      "conversationId": "conv_123456789",
      "createdAt": "2024-07-11T10:15:40.456Z",
      "updatedAt": "2024-07-11T10:15:40.456Z",
      "role": "assistant",
      "content": "Yes, our analytics engine is agnostic. You can log full conversations of your agent or custom copilot, even if not all interactions hit Inkeep's API endpoint.",
      "name": null,
      "links": null,
      "properties": {},
      "userProperties": {}
    },
    {
      "id": "msg_3",
      "type": "openai",
      "conversationId": "conv_123456789",
      "createdAt": "2024-07-11T10:16:15.789Z",
      "updatedAt": "2024-07-11T10:16:15.789Z",
      "role": "user",
      "content": "Does that mean it supports logging tool calls?",
      "name": null,
      "links": null,
      "properties": {},
      "userProperties": {}
    },
    {
      "id": "msg_4",
      "type": "openai",
      "conversationId": "conv_123456789",
      "createdAt": "2024-07-11T10:16:45.678Z",
      "updatedAt": "2024-07-11T10:18:45.678Z",
      "role": "assistant",
      "content": "Yup, Inkeep's Analytics API is fully compatible with OpenAI chat completion endpoints, including tool calling.",
      "name": null,
      "links": null,
      "properties": {},
      "userProperties": {}
    }
  ],
  "messagesOpenAIFormat": [
    {
      "role": "user",
      "content": "Can I log any OpenAI-compatible conversation?"
    },
    {
      "role": "assistant",
      "content": "Yes, Inkeep's analytics engine is agnostic. You can log full conversations of your agent or custom copilot, even if not all interactions hit Inkeep's API endpoint."
    },
    {
      "role": "user",
      "content": "Does that mean it supports logging tool calls?"
    },
    {
      "role": "assistant",
      "content": "Yup, Inkeep's Analytics API is fully compatible with OpenAI chat completions endpoints, including tool calling."
    }
  ]
}

This response includes all extended details about the conversation and its messages, including any properties you associated with it.

The messagesOpenAIFormat property provides the messages of the conversation in a format compatible with OpenAI's chat completions API. You can use this to implement Share a chat, Saved Chats, or any other functionality that requires retrieving an existing chat.

Here's how:

Share a chat - Create an entry point in your application or UI that parses a query parameter, e.g. ?chatId=<id>. Then, use the GET /conversations/{id} endpoint to get the last state of a conversation and hydrate the chat UI in your own application. If you want to be able to "fork" shared chats, then simply use a different id when logging the continuation of a shared conversation to POST /conversations. This will log it as a separate conversation from the original.
Saved Chats - Whenever a user creates a new conversation, associate that id with the user in your database or application. This way, you have a relationship of chats<>user and can display a user's history in your UI. You can also store that relationship in a user's browser session for unauthenticated contexts.

Log usage events

In addition to logging conversations and feedback, you can also track specific usage events related to conversations or messages using the /events endpoint.

For example, you may want to track events like:

message:copied: When a user copies a message
message:code_snippet:copied: When a user runs a code snippet from a message
conversation:shared: When a user shares a conversation

When logged, they will be incorporated in the Inkeep Analytics reporting.

The below shows an example of how to log these events.

log-event.js

// Message event
const eventData = {
  type: "message:copied",
  entityType: "message" // 'message' or 'conversation'
  messageId: "{message_id}",
};
 
fetch('https://api.analytics.inkeep.com/events', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(eventData)
})
.then(response => response.json())
.then(data => console.log(data));
 
// Conversation Event
const conversationEventData = {
  type: "conversation:shared",
  entityType: "conversation"
  conversationId: "{conversation_id}",
};
 
fetch('https://api.analytics.inkeep.com/events', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(conversationEventData)
})
.then(response => response.json())

Concepts

This glossary defines the key objects and concepts used throughout the Inkeep Analytics API and explains how they relate to each other.

Conversation

A conversation represents a series of messages between a user and an AI assistant. Conversations are the primary unit for tracking chat interactions in the Analytics API. Each conversation contains multiple messages and can receive feedback from users. Conversations can be grouped into semantic threads based on their topical similarity.

Message

A message represents a single interaction within a conversation, either from a user or the assistant. Messages are contained within conversations and can individually receive feedback. Users can perform various actions on messages (like copying), which are tracked as events.

Feedback

Feedback captures user reactions to assistant messages, typically in the form of thumbs up/down reactions with optional explanations. Feedback is associated with specific messages and helps improve the quality of responses over time.

Event

Events track specific user interactions with the Analytics API, such as copying a message, sharing a conversation, or clicking on a source. Events are always associated with either a message or a conversation entity and help analyze user engagement patterns.

Query

Queries allow for retrieving and analyzing analytics data stored in the system. There are several types of queries:

Conversation queries: Retrieve conversation data
Event queries: Access logged events
Semantic thread queries: Retrieve semantically linked conversation threads

Properties / User Properties

Custom properties can be attached to Analytics API objects for filtering and segmentation. These properties allow for flexible data organization and analysis across conversations, messages, and other entities.

SemanticThread

A semantic thread is a set of one or more related conversations grouped by semantic meaning rather than by converstion ID or timestamp. Threads connect conversations that discuss similar topics, allowing for analysis of user interests and common questions across multiple interactions.

Project

The organizational unit that groups analytics data in the Inkeep system. Projects contain conversations, messages, and all related analytics data, typically corresponding to a specific integration or implementation.

Add analytics to any OpenAI compatible chat

On this page