Call the Inkeep RAG API with an HTTP Request

The Inkeep RAG API provides structured documents from your knowledge base. This page shows how to make direct HTTP requests to the API. Please ensure you have an API key (don't have one? Get one here).

Request Format

POST https://api.inkeep.com/v1/chat/completions
Content-Type: application/json
Authorization: Bearer YOUR_INKEEP_API_KEY

{
  "model": "inkeep-rag",
  "messages": [
    {
      "role": "user",
      "content": "How do I get started?"
    }
  ],
  "response_format": {
    "type": "json_object"
  }
}

Response Format

{
  "id": "chatcmpl-123abc",
  "object": "chat.completion",
  "created": 1677858242,
  "model": "inkeep-rag",
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "{\"content\":[{\"type\":\"document\",\"record_type\":\"Documentation\",\"url\":\"https://docs.inkeep.com/ui-components/js-snippet/in-page/embedded-search-and-chat\",\"title\":\"Embedded Search and Chat (JS) - Inkeep\",\"source\":{\"type\":\"content\",\"content\":[{\"type\":\"text\",\"text\":\"## Quick start\\n\\nAdd the below `<script>` tag to the `<head>` or `<body>` of your website.\"}]}},{\"type\":\"document\",\"record_type\":\"Documentation\",\"url\":\"https://docs.inkeep.com/projects/overview\",\"title\":\"Projects Overview - Inkeep\",\"source\":{\"type\":\"content\",\"content\":[{\"type\":\"text\",\"text\":\"# Projects Overview\\n\\nProjects are the core organizational unit in Inkeep. Each project represents a distinct AI assistant with its own knowledge base, settings, and integrations.\"}]}}]}"
      },
      "finish_reason": "stop",
      "index": 0
    }
  ]
}

Content Example

The sources are under content as stringified JSON. The parsed result looks like:

{
  "content": [
    {
      "type": "document",
      "record_type": "documentation",
      "url": "https://docs.inkeep.com/ui-components/js-snippet/in-page/embedded-search-and-chat",
      "title": "Embedded Search and Chat (JS) - Inkeep",
      "source": {
        "type": "content",
        "content": [
          {
            "type": "text",
            "text": "## Quick start\n\nAdd the below `<script>` tag to the `<head>` or `<body>` of your website."
          }
        ]
      }
    },
    {
      "type": "document",
      "record_type": "documentation",
      "url": "https://docs.inkeep.com/projects/overview",
      "title": "Projects Overview - Inkeep",
      "source": {
        "type": "content",
        "content": [
          {
            "type": "text",
            "text": "# Projects Overview\n\nProjects are the core organizational unit in Inkeep. Each project represents a distinct AI assistant with its own knowledge base, settings, and integrations."
          }
        ]
      }
    }
  ]
}

Content Schema

The RAG API returns a JSON object with an array of documents in the content field. Each document has the following structure:

Field	Type	Description
`type`	string	The type of the document, typically "document"
`record_type`	string	The source of the document (e.g., "Documentation", "GitHub Issue", "Forum")
`url`	string	The URL where the document can be found
`title`	string	The title of the document
`source`	object	Contains the content of the document (see Source Entity for details)
`context`	string	Optional additional context about the document

Source Entity

The source field contains the actual content of the document in a structured format. It has the following structure:

Field	Type	Description
`type`	string	Type of the source, typically "content"
`content`	array	Array of content blocks

Each item in the content array has the following structure:

Field	Type	Description
`type`	string	Type of content block (e.g., "text")
`text`	string	The actual text content when type is "text"
`media_type`	string	Optional media type of the content (e.g., "text/plain")
`data`	string	Optional alternative data field for content

Document Source Types

The RAG API can return documents from various sources:

Record Type	Description
`documentation`	Official documentation pages
`site`	Content from your website
`discourse_post`	Discourse Forum Posts
`github_issue`	GitHub issues or pull requests
`github_discussion`	GitHub Discussions
`stackoverflow_question`	StackOverflow Questions and Answers
`discord_forum_post`	Discord Forum Posts
`discord_message`	Discord Threads/Messages
`custom_question_answer`	Custom FAQ Added to the knowledge base

Example Usage

Here's an example of how to call the RAG API using curl:

curl -X POST https://api.inkeep.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $INKEEP_API_KEY" \
  -d '{
    "model": "inkeep-rag",
    "messages": [
      {
        "role": "user",
        "content": "How do I get started?"
      }
    ],
    "response_format": {
      "type": "json_object"
    }
  }'

Example Source Entity

Here's an example of a source entity from the response:

"source": {
  "type": "content",
  "content": [
    {
      "type": "text",
      "text": "## Quick start\n\nAdd the below `<script>` tag to the `<head>` or `<body>` of your website."
    },
    {
      "type": "text",
      "text": "```html\n<script>\n  (function() {\n    var inkeepConfig = {\n      apiKey: \"YOUR_API_KEY\",\n      baseSettings: {\n        organizationDisplayName: \"Your Organization\",\n        primaryBrandColor: \"#26D6FF\"\n      }\n    };\n    var script = document.createElement(\"script\");\n    script.src = \"https://cdn.inkeep.com/embed.js\";\n    script.setAttribute(\"data-inkeep\", JSON.stringify(inkeepConfig));\n    document.head.appendChild(script);\n  })();\n</script>\n```"
    }
  ]
}

Processing the Response

To process the response, you'll need to:

Parse the JSON response
Extract the content field from the message.content JSON string
Process each document in the content array

This will give you structured access to the documents retrieved from your knowledge base.

Filtering by Source ID

You can filter the RAG API results to only include documents from specific sources by using the inkeep-filters header in your request. This is useful when you want to limit results to particular sources in your knowledge base.

Filter Format

To filter by a single source ID, use this header structure:

inkeep-filters: {"attributes": {"source_id": "your_source_id"}}

To filter by multiple source IDs, use the $or operator:

inkeep-filters: {"attributes": {"$or": [{"source_id": "source_id_1"}, {"source_id": "source_id_2"}]}}

Finding Source IDs

Source IDs can be found in the Inkeep Dashboard under the Sources tab. Each source in your project has a unique identifier that you can use for filtering.

Example with Filtering

Here's a complete example of calling the RAG API with source filtering:

curl -X POST https://api.inkeep.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $INKEEP_API_KEY" \
  -H "inkeep-filters: {\"attributes\": {\"source_id\": \"source_id_1\"}}" \
  -d '{
    "model": "inkeep-rag",
    "messages": [
      {
        "role": "user",
        "content": "How do I get started?"
      }
    ],
    "response_format": {
      "type": "json_object"
    }
  }'

The API will only return documents from the specified source(s), allowing you to query specific portions of your knowledge base.

Call the Inkeep RAG API with an HTTP Request

On this page