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"]
  }
}