Quick Start

subscription StartNewChat {
    input: {
      messageInput: "How do I get started?"
      organizationId: "<YOUR_ORG_ID>"
      integrationId: "<YOUR_INTEGRATION_ID>"
  ) {
    message {
      citations {

The newSessionChatResult subscription is used to create a new chat and receive a subscription event every time there is a new update to the chat response. With this subscription, you can stream responses, provide citations, and get run-time analytics of the user chat using websockets.

Try the API Playground for an interactive way to use the newSessionChatResult API.

Want to try out a REST version of our API? Contact us at support@inkeep.com for the documentation. It's a native proxy on top of our GraphQL API with equivalent functionality.



inputNewSessionChatResultInputRequired. The input parameters that will be used in the subscription.

Input Types


messageInputString!Required. The message input string.
organizationIdID!Required. The ID of the organization.
integrationIdID!Required. The ID of the integration.
chatModeChatModeThe mode of the chat (AUTO, TURBO).
outputModeOutputModeThe output mode of the chat (DEFAULT, SQL, PYTHON, CODE).
filtersChatFiltersInputUse to scope the considered sources based on context known about the user.
messageContextStringAdd dynamic context about the user that isn’t part of the user’s message. This can include in-app or dynamic information that your client can infer about the user that might be helpful for the chat bot.
userAttributesJSONAdd key <> value pairs that you’d like to use as filters in our analytics suite. This can include emails, IDs, cohorts, groups, pricing tiers and more.
tags[String!]Tags to add to the chat session metadata. These are useful for batch-testing a set of questions and collecting feedback for an iteration of your chatbot.
workflowIdString(Preview). The ID of the workflow. Workflows allow you to define specific scenarios in natural language, that leverage your Inkeep knowledge base. Typical scenarios include migrating from X to Y. Contact us for more information.
workflowVersionString(Preview). The version of the workflow.


When we ingest content, we add metadata to the content that is filterable in our search and chat APIs. For example, if you have multiple products or version your product, you can “scope” the chat session if you know the product or product version that the user is interested in.

This might be based on:

  • the URL the user is viewing
  • a product or version picker in your docs or chat UX
  • in-app context you have about the user, like which products or versions they use

By default, we label source documents with a product and product version if it can be inferred from your HTML or URL structure.

If you use our ingestion APIs, you can add your own ‘attributes’ that are filterable to the source documents and create your own filter queries based on that.

productStringThe product name. Used to scope the response to content relevant to a specific product.
productVersionStringThe product version name. Used to scope the response to content relevant to a specific product version.
sourceIdsStringThe source IDs.
attributesJSONThe attributes.

Filter attributes

Our attributes filtering schema is based on MongoDB’s query and projection operators. We currently support $in, $not, $and and $or operators or conditions.

The attributes value should be valid within this schema. See an example below

  "attributes": {
    "$and": [
      { "env": "production" },
      { "modules": { "$in": ["module1", "module2"] } }

Note that all filters are assumed to follow $and and by exclusive by default, unless using the $or operator.

That is, sources not meeting those filters will not be used in the chat response.

Filtering by URLs

You can filter by the URLs by using the recordUrlsByRegex and recordUrlsByExact patterns as illustrated below.

  "attributes": {
    "$and": [
        "recordUrlsByRegex": {
          "$in": [".*inkeep.*"]
        "recordUrlsByExact": {
          "$in": ["https://www.inkeep.com/product/1.0"]

Enum Types


This enum is used to set the mode of the chat. It can be either AUTO or TURBO.

AUTOThe AUTO mode uses the best models available (e.g. GPT4 and Claude V2) for better reasoning and instruction following. It supports longer conversations, considers more sources when formulating an answer, and uses additional chain of thought reasoning and other LLM techniques for Q&A. However, it is slower and more expensive.
TURBOThe TURBO mode is faster and more affordable. It uses standard models (e.g. GPT 3.5-turbo) and supports standard conversation length and input size. It considers standard sources when formulating an answer and uses standard intermediary LLM steps.


Our API can output conversational outputs (DEFAULT) or only code-snippets in specific a specific programming language.


Object Types


You don’t have to pass in all the historical chat messages for a conversation, we automatically handle this by creating a chat session with a chatSessionId. For additional messages using the Continue Chat Session, you only need to specify the sessionId and new user message.

sessionIdID!The ID of the chat session.
messageBotMessage!The bot message.
isEndBoolean!Indicates if the chat session has ended.
postChatResultSignalsPostChatResultSignalsThe post chat result signals.


idID!A unique ID for the message.
contentStringThe content of the message.
citations[ChatCitation!]!The citations in the message.
codeBlocks[CodeBlock!]The code blocks in the message.


If using a code-based output mode, this will contain the output as code snippets.

languageCodeLanguage!The language of the code block.
codeStringThe code in the code block.


citationNumberInt!The citation number.
titleStringThe title of the citation.
urlString!The URL of the citation.
rootRecordIdIDThe ID of the root record.
rootRecordTypeRecordTypeThe type of the root record.

How to handle citations in the UI

The content of the bot message will have inline-citations in the format of [^int] where int corresponds to the citationNumber in the ChatCitation object.

To show this in the UX, you can use a regex to extract the inline citations and replace them with the URL of the source as see in the citations object. For example, convert [^int] to [^int](citation[int].url) to add footnotes with the appropriate citation URL. Try out our chat UI to see this in action.

PostChatResultSignals (preview)

If you prefer to track usage analytics in your own analytics system instead of ours, we provide analytics in the chat session response that you can use to enrich your own analytics.

botAbleToAnswerGivenSourcesBooleanIndicates if the bot was able to answer given sources.
featureNotSupportedBooleanIndicates whether the bot indicated that a feature or capability is not currently supported.
suggestedFollowupQuestions[String!]Suggested follow-up questions based on the user question and bot answer

Please note that this feature is currently in preview, if you’d like this enabled for your organization, please contact us at support@inkeep.com to enable it for your organization.