Knowledge Service APIs

The Knowledge Service APIs allow you to manage knowledge service configurations and topics within your OpenDialog workspace. These endpoints enable programmatic control over the NLU and AI components that power your conversational applications.

Overview

Knowledge Services use Retrieval Augmented Generation (RAG) to enhance your conversational AI with domain-specific knowledge. By configuring knowledge services, you can:

Define topics and topic sources for your knowledge base
Configure embedding and retrieval parameters
Integrate with language models for intelligent question answering
Vectorise content for semantic search

For more details on knowledge services and RAG, see the Language Services documentation.

Important Naming Rules

Knowledge service names cannot contain spaces
Topic names cannot contain spaces
Names must match the pattern: alphanumeric characters, underscores, and hyphens only (/^[\w\-]+$/)

Knowledge Service Configuration

List Knowledge Services

Retrieve a list of all knowledge service configurations in your workspace.

Endpoint: GET /public/api/knowledge-service

Headers:

Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

Response:

{
  "data": [
    {
      "id": 1,
      "name": "faq_knowledge_service",
      "component_id": "language_processor.core.knowledge_service",
      "scenario_id": "",
      "active": true,
      "type": "knowledge_service",
      "configuration": {
        "description": "Knowledge service for frequently asked questions",
        "type": "knowledge_service",
        "chunk_size": 1000,
        "chunk_overlap": 10,
        "top_k": 3,
        "language_model_component_id": "language_model.core.openai",
        "language_model_configuration": {
          "managed": 1,
          "api_key": "",
          "tasks": {
            "embedding": {
              "model": "text-embedding-3-small"
            }
          }
        }
      },
      "created_at": "2024-01-15T10:30:00.000000Z",
      "updated_at": "2024-01-15T10:30:00.000000Z"
    }
  ]
}

Get Knowledge Service Count

Get the total count of knowledge service configurations.

Endpoint: GET /public/api/knowledge-service-count

Headers:

Authorization: Bearer YOUR_API_TOKEN

Response:

{
  "data": {
    "items_count": 5
  }
}

Create Knowledge Service

Create a new knowledge service configuration. Knowledge services use a language model for embeddings and manage chunked text sources.

Endpoint: POST /public/api/knowledge-service

Headers:

Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

Request Body:

{
  "scenario_id": "",
  "name": "this_is_a_new_service",
  "component_id": "language_processor.core.knowledge_service",
  "configuration": {
    "description": "this is the new service description",
    "type": "knowledge_service",
    "chunk_size": 1000,
    "chunk_overlap": 10,
    "top_k": 3,
    "language_model_component_id": "language_model.core.open_ai",
    "language_model_configuration_name": "this_is_a_new_service Language Model",
    "language_model_configuration": {
      "api_key": "",
      "managed": true,
      "tasks": {
        "embedding": {
          "model": "text-embedding-3-small"
        }
      }
    }
  },
  "active": true
}

Request Body Parameters:

name (string, required) - Name of the knowledge service (must match pattern /^[\w\-]+$/)
scenario_id (string, optional) - ID of the associated scenario (empty string if not applicable)
component_id (string, required) - Must be "language_processor.core.knowledge_service"
active (boolean, required) - Whether the knowledge service is active
configuration (object, required) - Configuration for the knowledge service

Configuration Parameters:

description (string, optional) - Descriptive text about the knowledge service
type (string, required) - Must be "knowledge_service"
chunk_size (integer, required) - Size of text chunks for processing (default: 1000)
chunk_overlap (integer, required) - Number of tokens to overlap between chunks (0-100, default: 10)
top_k (integer, required) - Number of top results to return from vector search (minimum: 1, default: 3)
language_model_component_id (string, required) - Component ID of the language model to use for embeddings (e.g., "language_model.core.open_ai" or "language_model.core.azure_openai")
language_model_configuration_name (string, required) - A descriptive name for the language model configuration
language_model_configuration (object, required) - Configuration for the language model
- managed (boolean) - Set to true for managed (API key provided by system) or false for self-managed
- api_key (string) - API key for the language model (required if managed is false)
- tasks (object) - Task-specific model configurations
  - embedding (object) - Embedding model configuration
    - model (string) - Model name for embeddings (e.g., "text-embedding-3-small")

Validation Rules:

name - Must match pattern /^[\w\-]+$/ (alphanumeric, underscores, and hyphens only; no spaces)
configuration.chunk_size - Required, integer, minimum value varies based on system configuration
configuration.chunk_overlap - Required, integer, minimum 0, maximum 100
configuration.top_k - Required, integer, minimum 1

Response:

{
  "data": {
    "id": 39000003,
    "name": "this_is_a_new_service",
    "component_id": "language_processor.core.knowledge_service",
    "scenario_id": "",
    "active": true,
    "type": "knowledge_service",
    "configuration": {
      "description": "this is the new service description",
      "type": "knowledge_service",
      "chunk_size": 1000,
      "chunk_overlap": 10,
      "top_k": 3,
      "language_model_component_id": "language_model.core.open_ai",
      "language_model_configuration_name": "this_is_a_new_service Language Model",
      "language_model_configuration": {
        "api_key": "",
        "managed": true,
        "tasks": {
          "embedding": {
            "model": "text-embedding-3-small"
          }
        }
      }
    },
    "created_at": "2025-11-18T15:40:37.000000Z",
    "updated_at": "2025-11-18T15:40:37.000000Z",
    "scenario_count": 0
  }
}

Get Knowledge Service

Retrieve a specific knowledge service configuration by ID.

Endpoint: GET /public/api/knowledge-service/{id}

Headers:

Authorization: Bearer YOUR_API_TOKEN

URL Parameters:

id (required) - The ID of the knowledge service configuration

Response:

{
  "data": {
    "id": 1,
    "name": "faq_knowledge_service",
    "component_id": "language_processor.core.knowledge_service",
    "scenario_id": "",
    "active": true,
    "type": "knowledge_service",
    "configuration": {
      "description": "Knowledge service for FAQ",
      "type": "knowledge_service",
      "chunk_size": 1000,
      "chunk_overlap": 10,
      "top_k": 3,
      "language_model_component_id": "language_model.core.openai",
      "language_model_configuration": {
        "managed": 1,
        "api_key": "",
        "tasks": {
          "embedding": {
            "model": "text-embedding-3-small"
          }
        }
      }
    },
    "created_at": "2024-01-15T10:30:00.000000Z",
    "updated_at": "2024-01-15T10:30:00.000000Z"
  }
}

Delete Knowledge Service

Remove a knowledge service configuration.

Endpoint: DELETE /public/api/knowledge-service/{id}

Headers:

Authorization: Bearer YOUR_API_TOKEN

URL Parameters:

id (required) - The ID of the knowledge service configuration

Response: 204 No Content

Knowledge Service Topics

List Topics

Retrieve all topics for a specific knowledge service.

Endpoint: GET /public/api/language-processor/{knowledge_service_id}/language-processor-topic

Headers:

Authorization: Bearer YOUR_API_TOKEN

URL Parameters:

knowledge_service_id (required) - The ID of the knowledge service

Query Parameters:

search (optional) - Search topics by name
order_by (optional) - Field to order by (default: created_at)
order_dir (optional) - Sort direction: asc or desc (default: desc)
per_page (optional) - Number of results per page (default: 15)

Response:

{
  "data": [
    {
      "id": 1,
      "name": "Product Information",
      "description": "Information about our products",
      "dataset_id": 1,
      "status": "active",
      "created_at": "2024-01-15T10:30:00.000000Z",
      "updated_at": "2024-01-15T10:30:00.000000Z",
      "sources": []
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 15,
    "total": 1
  }
}

Create Topic

Create a new topic for a knowledge service.

Endpoint: POST /public/api/language-processor/{language_processor_id}/language-processor-topic

Headers:

Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

URL Parameters:

language_processor_id (required) - The ID of the knowledge service

Request Body:

{
  "name": "product_information",
  "description": "Information about our products",
  "topic_type": "vectorised"
}

Validation Rules:

name - Must match pattern /^[\w\-]+$/ (alphanumeric, underscores, and hyphens only; no spaces)
topic_type - Must be either vectorised or static_text

Response:

{
  "data": {
    "id": 2,
    "name": "product_information",
    "description": "Information about our products",
    "dataset_id": 1,
    "created_at": "2024-01-15T11:00:00.000000Z",
    "updated_at": "2024-01-15T11:00:00.000000Z"
  }
}

Get Topic

Retrieve a specific topic.

Endpoint: GET /public/api/language-processor/{language_processor_id}/language-processor-topic/{topic_id}

Headers:

Authorization: Bearer YOUR_API_TOKEN

URL Parameters:

language_processor_id (required) - The ID of the knowledge service
topic_id (required) - The ID of the topic

Response:

{
  "data": {
    "id": 1,
    "name": "Product Information",
    "description": "Information about our products",
    "dataset_id": 1,
    "topic_type": "vectorised",
    "created_at": "2024-01-15T10:30:00.000000Z",
    "updated_at": "2024-01-15T10:30:00.000000Z"
  }
}

Update Topic

Update an existing topic.

Endpoint: PUT /public/api/language-processor/{language_processor_id}/language-processor-topic/{topic_id}

Headers:

Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

URL Parameters:

language_processor_id (required) - The ID of the knowledge service
topic_id (required) - The ID of the topic

Request Body:

{
  "name": "updated_topic_name",
  "description": "Updated description",
  "topic_type": "vectorised"
}

Validation Rules:

name - Must match pattern /^[\w\-]+$/ (alphanumeric, underscores, and hyphens only; no spaces)
topic_type - Must be either vectorised or static_text

Response: 204 No Content

Topic Sources

Topic sources are the actual content that gets embedded and vectorised for semantic search within a knowledge service. Sources can be text content, documents, or other data that you want to make searchable through the knowledge service.

Topics with a type of static_text only support a single text type topic source that cannot be vectorised.

List Topic Sources

Retrieve all sources for a specific topic.

Endpoint: GET /public/api/language-processor/{language_processor_id}/language-processor-topic/{topic_id}/language-processor-topic-source

Headers:

Authorization: Bearer YOUR_API_TOKEN

URL Parameters:

language_processor_id (required) - The ID of the knowledge service
topic_id (required) - The ID of the topic

Create Topic Source

Add a new source to a topic. Topic sources contain the actual content to be vectorised and made searchable.

Endpoint: POST /public/api/language-processor/{language_processor_id}/language-processor-topic/{topic_id}/language-processor-topic-source

Headers:

Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

URL Parameters:

language_processor_id (required) - The ID of the knowledge service
topic_id (required) - The ID of the topic

Request Body:

Topic sources support three different types: text, url, and file. Below are examples for each type:

Text Type

{
  "type": "text",
  "configuration": {
    "name": "Some text",
    "source": "This is some text source"
  }
}

URL Type

{
  "type": "url",
  "configuration": {
    "source": "https://opendialog.ai",
    "name": "opendialog.ai",
    "exclusion_classes": [
      "exclude_class"
    ],
    "exclusion_ids": [
      "exclude_id"
    ],
    "should_strip_tags": true
  }
}

File Type

{
  "type": "file",
  "configuration": {
    "source": "file_upload.txt",
    "name": "file_upload"
  },
  "file": {
    "file": "data:text/plain;base64,PGZpbGUtdXBsb2FkPi4uLg==",
    "file_name": "file_upload.txt",
    "type": "text/plain"
  }
}

Response:

{
  "data": {
    "id": 1,
    "topic_id": 1,
    "type": "text",
    "configuration": {
      "name": "Some text",
      "source": "This is some text source"
    },
    "created_at": "2024-01-15T11:00:00.000000Z",
    "updated_at": "2024-01-15T11:00:00.000000Z"
  }
}

Get Topic Source

Retrieve a specific topic source by ID.

Endpoint: GET /public/api/language-processor/{language_processor_id}/language-processor-topic/{topic_id}/language-processor-topic-source/{topic_source_id}

Headers:

Authorization: Bearer YOUR_API_TOKEN

URL Parameters:

language_processor_id (required) - The ID of the knowledge service
topic_id (required) - The ID of the topic
topic_source_id (required) - The ID of the topic source

Response:

{
  "data": {
    "id": 1,
    "topic_id": 1,
    "type": "text",
    "configuration": {
      "name": "Some text",
      "source": "This is some text source",
      "vectorisation_status": "pending",
      "exclusion_classes": [],
      "exclusion_ids": [],
      "should_strip_tags": false,
      "is_truncated": false,
      "allow_truncation": false,
      "next_vectorisation": null,
      "vectorisation_interval": null,
      "vectorisation_period": null,
      "last_vectorised": null,
      "will_revectorise": false
    },
    "created_at": "2024-01-15T11:00:00.000000Z",
    "updated_at": "2024-01-15T11:00:00.000000Z"
  }
}

Configuration Parameters:

vectorisedtype (string, required) - Type of source: text, url, or file
source (string, required) - The source content or identifier (text content, URL, or filename for file type)
name (string, optional) - A descriptive name for the source
exclusion_classes (array, optional) - List of CSS/HTML classes to exclude during processing (URL type)
exclusion_ids (array, optional) - List of element IDs to exclude during processing (URL type)
should_strip_tags (boolean, optional) - Whether to strip HTML/XML tags during processing (URL and file types)
file (object, optional) - File metadata (required for file type)
- file (string) - Base64-encoded file content with data URI prefix
- file_name (string) - Original filename
- type (string) - MIME type of the file (e.g., “text/plain”, “application/pdf”)
vectorisation_status (string) - Current vectorisation status: pending, in_progress, completed, failed, or obsolete
next_vectorisation (timestamp, optional) - Scheduled time for next vectorisation
vectorisation_interval (integer, optional) - Interval in seconds between auto-vectorisations
vectorisation_period (string, optional) - Time period for vectorisation scheduling
is_truncated (boolean) - Whether the source content was truncated
allow_truncation (boolean) - Whether truncation is allowed for this source
last_vectorised (timestamp, optional) - When this source was last vectorised
will_revectorise (boolean) - Whether the source will be re-vectorised

Vectorisation Status Values:

Vectorisationpending - Source waiting to be vectorised
in_progress - Source is currently being vectorised
completed - Source has been successfully vectorised
failed - Vectorisation failed for this source
obsolete - Source content changed; vectorisation is outdated

Delete Topic Source

Remove a topic source from a topic.

Endpoint: DELETE /public/api/language-processor/{language_processor_id}/language-processor-topic/{topic_id}/language-processor-topic-source/{topic_source_id}

Headers:

Authorization: Bearer YOUR_API_TOKEN

URL Parameters:

language_processor_id (required) - The ID of the knowledge service
topic_id (required) - The ID of the topic
topic_source_id (required) - The ID of the topic source

Response: 204 No Content

Vectorise Topic

Trigger vectorisation for a topic.

Endpoint: POST /public/api/language-processor/{language_processor_id}/language-processor-topic/{topic_id}/vectorise

Headers:

Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

URL Parameters:

language_processor_id (required) - The ID of the knowledge service
topic_id (required) - The ID of the topic

Response:

{
  "message": "Topic vectorization initiated"
}

Unified Topic Management

The unified topic endpoints provide simplified topic management operations for knowledge services. These endpoints allow you to create, retrieve, and update topics along with their sources in a single operation.

Create Unified Topic

Create a new topic with associated sources in a single request.

Endpoint: POST /public/api/language-processor/{language_processor_id}/language-processor-topics

Headers:

Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

URL Parameters:

language_processor_id (required) - The ID of the knowledge service

Request Body:

{
  "name": "test_topic",
  "description": "test_description",
  "topic_type": "vectorised",
  "sources": [
    {
      "type": "text",
      "configuration": {
        "source": "test_text"
      }
    },
    {
      "type": "text",
      "configuration": {
        "source": "test_text2"
      }
    }
  ]
}

Request Body Parameters:

name (string, required) - Name of the topic (must match pattern /^[\w\-]+$/)
description (string, required) - Description of the topic
topic_type - Must be either vectorised or static_text
sources (array, required) - Array of topic sources to create with this topic (minimum 1 source required)
- type (string, required) - Type of source: text, url, or file
- configuration (object, required) - Configuration for the source
  - source (string, required) - The source content, URL, or filename
  - name (string, optional) - A descriptive name for the source
  - exclusion_classes (array, optional) - List of CSS/HTML classes to exclude (for URL type)
  - exclusion_ids (array, optional) - List of element IDs to exclude (for URL type)
  - should_strip_tags (boolean, optional) - Whether to strip HTML/XML tags (for URL and file types)

Response: 204 No Content

Get Unified Topic

Retrieve a specific topic with all its associated sources.

Endpoint: GET /public/api/language-processor/{language_processor_id}/language-processor-topics/{topic_id}

Headers:

Authorization: Bearer YOUR_API_TOKEN

URL Parameters:

language_processor_id (required) - The ID of the knowledge service
topic_id (required) - The ID of the topic

Response:

{
  "data": {
    "id": 1,
    "name": "test_topic",
    "description": "test_description",
    "dataset_id": 1,
    "status": "active",
    "sources": [
      {
        "id": 1,
        "topic_id": 1,
        "type": "text",
        "configuration": {
          "source": "test_text",
          "name": "test_text",
          "vectorisation_status": "pending",
          "exclusion_classes": [],
          "exclusion_ids": [],
          "should_strip_tags": false,
          "is_truncated": false,
          "allow_truncation": false,
          "next_vectorisation": null,
          "vectorisation_interval": null,
          "vectorisation_period": null,
          "last_vectorised": null,
          "will_revectorise": false
        },
        "created_at": "2025-11-18T15:40:37.000000Z",
        "updated_at": "2025-11-18T15:40:37.000000Z"
      },
      {
        "id": 2,
        "topic_id": 1,
        "type": "text",
        "configuration": {
          "source": "test_text2",
          "name": "test_text2",
          "vectorisation_status": "pending",
          "exclusion_classes": [],
          "exclusion_ids": [],
          "should_strip_tags": false,
          "is_truncated": false,
          "allow_truncation": false,
          "next_vectorisation": null,
          "vectorisation_interval": null,
          "vectorisation_period": null,
          "last_vectorised": null,
          "will_revectorise": false
        },
        "created_at": "2025-11-18T15:40:37.000000Z",
        "updated_at": "2025-11-18T15:40:37.000000Z"
      }
    ],
    "created_at": "2025-11-18T15:40:37.000000Z",
    "updated_at": "2025-11-18T15:40:37.000000Z"
  }
}

Update Unified Topic

Update a topic and manage its sources (update, remove, or add sources) in a single request.

Endpoint: PATCH /public/api/language-processor/{language_processor_id}/language-processor-topics/{topic_id}

Headers:

Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

URL Parameters:

language_processor_id (required) - The ID of the knowledge service
topic_id (required) - The ID of the topic

Request Body:

{
  "name": "test_topic_updated",
  "description": "test_description_updated",
  "sources": [
    {
      "id": 1,
      "operation": "update",
      "type": "text",
      "configuration": {
        "source": "test_text_updated"
      }
    },
    {
      "id": 2,
      "operation": "remove"
    },
    {
      "operation": "add",
      "type": "text",
      "configuration": {
        "source": "test_text3"
      }
    }
  ]
}

Request Body Parameters:

name (string, optional) - Updated name of the topic
description (string, optional) - Updated description of the topic
sources (array, optional) - Array of source operations
- id (integer) - ID of the source (required for update and remove operations, omit for add)
- operation (string, required) - Operation to perform: add, update, or remove
- type (string) - Type of source: text, url, or file (required for add and update operations)
- configuration (object) - Configuration for the source (required for add and update operations)
  - source (string, required) - The source content, URL, or filename
  - name (string, optional) - A descriptive name for the source
  - exclusion_classes (array, optional) - List of CSS/HTML classes to exclude (for URL type)
  - exclusion_ids (array, optional) - List of element IDs to exclude (for URL type)
  - should_strip_tags (boolean, optional) - Whether to strip HTML/XML tags (for URL and file types)

Response: 204 No Content

Example: Adding a URL source to an existing topic

{
  "sources": [
    {
      "operation": "add",
      "type": "url",
      "configuration": {
        "source": "https://example.com",
        "name": "example.com",
        "exclusion_classes": ["nav", "footer"],
        "exclusion_ids": ["sidebar"],
        "should_strip_tags": true
      }
    }
  ]
}

Example: Updating an existing source and adding a new file source

{
  "sources": [
    {
      "id": 5,
      "operation": "update",
      "type": "text",
      "configuration": {
        "source": "Updated text content here",
        "name": "Updated Text Source"
      }
    },
    {
      "operation": "add",
      "type": "file",
      "configuration": {
        "source": "document.pdf",
        "name": "PDF Document"
      },
      "file": {
        "file": "data:application/pdf;base64,JVBERi0xLjQK...",
        "file_name": "document.pdf",
        "type": "application/pdf"
      }
    }
  ]
}

Error Responses

All endpoints may return the following error responses:

401 Unauthorized

{
  "message": "Unauthenticated."
}

403 Forbidden

{
  "message": "This action is unauthorized."
}

404 Not Found

{
  "message": "Resource not found."
}

422 Unprocessable Entity

{
  "message": "The given data was invalid.",
  "errors": {
    "field_name": ["Error message"]
  }
}