---
title: "Create a knowledge"
method: POST
path: "/v2/knowledge"
tags: ["Knowledge Bases"]
---

# Create a knowledge

`POST /v2/knowledge`

## Request body

- union
  - object
    - `type` 'internal'
    - `key` string, required
    - `description` string
    - `embedding_model` string, required — The embeddings model to use for the knowledge base in the format "provider/model" for public models or "workspaceKey@provider/model" for private workspace models. This model will be used to embed the chunks when they are added to the knowledge base.
    - `retrieval_settings` object — The retrieval settings for the knowledge base. If not provider, Hybrid Search will be used as a default query strategy.
      - `retrieval_type` 'vector_search' | 'keyword_search' | 'hybrid_search' — The retrieval type to use for the knowledge base. If not provided, Hybrid Search will be used as a default query strategy.
      - `top_k` integer — The number of results to return from the search.
      - `threshold` number — The threshold value used to filter the search results, only documents with a relevance score greater than the threshold will be returned
      - `rerank_config` object, nullable — The rerank configuration for the knowledge base. In case the model is provided it will be used to enhance the search precision.
        - `top_k` integer — The number of results to return by the reranking model
        - `rerank_threshold` number — The threshold value used to filter the rerank results, only documents with a relevance score greater than the threshold will be returned
        - `rerank_model` string, required — The rerank model to use for the knowledge base.
      - `agentic_rag_config` object, nullable — The Agentic RAG configuration for the knowledge base. If `null` is provided, Agentic RAG will be disabled.
        - `model` string, required — The model to use for the Agentic RAG
    - `path` string, required — Entity storage path. With workspace-level API keys, use the format `project/folder/subfolder/...`. The first element identifies the project, followed by nested folders (auto-created as needed). Example: `Default/agents`. With project-level API keys, the project is predetermined by the API key, so the path is relative to that project. Example: `agents`. For backward compatibility, a leading project name is ignored when it matches the scoped project.
  - object
    - `type` 'external'
    - `key` string, required
    - `description` string
    - `external_config` object, required
      - `name` string, required — The name of the external knowledge base.
      - `api_url` string, uri, required — The API URL of the external knowledge base.
      - `api_key` string, required — The API key to access the external knowledge base.
    - `path` string, required — Entity storage path. With workspace-level API keys, use the format `project/folder/subfolder/...`. The first element identifies the project, followed by nested folders (auto-created as needed). Example: `Default/agents`. With project-level API keys, the project is predetermined by the API key, so the path is relative to that project. Example: `agents`. For backward compatibility, a leading project name is ignored when it matches the scoped project.

## Response `200`

Knowledge successfully created

- union
  - object
    - `_id` string, required — The unique identifier of the knowledge base.
    - `created` string, required — The creation date of the knowledge base.
    - `description` string, nullable — The description of the knowledge base.
    - `key` string, required — The unique key of the knowledge base.
    - `domain_id` string, required — The project/domain ID of the knowledge base.
    - `path` string — Entity storage path. With workspace-level API keys, use the format `project/folder/subfolder/...`. The first element identifies the project, followed by nested folders (auto-created as needed). Example: `Default/agents`. With project-level API keys, the project is predetermined by the API key, so the path is relative to that project. Example: `agents`. For backward compatibility, a leading project name is ignored when it matches the scoped project.
    - `created_by_id` string, uuid, nullable
    - `updated_by_id` string, uuid, nullable
    - `updated` string, required — The last update date of the knowledge base.
    - `type` 'internal'
    - `retrieval_settings` object — The retrieval settings for the knowledge base. If not provider, Hybrid Search will be used as a default query strategy.
      - `retrieval_type` 'vector_search' | 'keyword_search' | 'hybrid_search' — The retrieval type to use for the knowledge base. If not provided, Hybrid Search will be used as a default query strategy.
      - `top_k` integer — The number of results to return from the search.
      - `threshold` number — The threshold value used to filter the search results, only documents with a relevance score greater than the threshold will be returned
      - `rerank_config` object, nullable — The rerank configuration for the knowledge base. In case the model is provided it will be used to enhance the search precision.
        - `top_k` integer — The number of results to return by the reranking model
        - `rerank_threshold` number — The threshold value used to filter the rerank results, only documents with a relevance score greater than the threshold will be returned
        - `rerank_model` string, required — The rerank model to use for the knowledge base.
      - `agentic_rag_config` object, nullable — The Agentic RAG configuration for the knowledge base. If `null` is provided, Agentic RAG will be disabled.
        - `model` string, required — The model to use for the Agentic RAG
    - `model` string, required — The embeddings model used for the knowledge base.
  - object
    - `_id` string, required — The unique identifier of the knowledge base.
    - `created` string, required — The creation date of the knowledge base.
    - `description` string, nullable — The description of the knowledge base.
    - `key` string, required — The unique key of the knowledge base.
    - `domain_id` string, required — The project/domain ID of the knowledge base.
    - `path` string — Entity storage path. With workspace-level API keys, use the format `project/folder/subfolder/...`. The first element identifies the project, followed by nested folders (auto-created as needed). Example: `Default/agents`. With project-level API keys, the project is predetermined by the API key, so the path is relative to that project. Example: `agents`. For backward compatibility, a leading project name is ignored when it matches the scoped project.
    - `created_by_id` string, uuid, nullable
    - `updated_by_id` string, uuid, nullable
    - `updated` string, required — The last update date of the knowledge base.
    - `type` 'external'
    - `retrieval_settings` object — The retrieval settings for the knowledge base.
      - `top_k` integer — The number of results to return from the search.
      - `threshold` number — The threshold value used to filter the search results, only documents with a relevance score greater than the threshold will be returned
      - `rerank_config` object, nullable — The rerank configuration for the knowledge base. In case the model is provided it will be used to enhance the search precision.
        - `top_k` integer — The number of results to return by the reranking model
        - `rerank_threshold` number — The threshold value used to filter the rerank results, only documents with a relevance score greater than the threshold will be returned
        - `rerank_model` string, required — The rerank model to use for the knowledge base.
      - `agentic_rag_config` object, nullable — The Agentic RAG configuration for the knowledge base. If `null` is provided, Agentic RAG will be disabled.
        - `model` string, required — The model to use for the Agentic RAG
    - `external_config` object, required
      - `name` string, required — The name of the external knowledge base.
      - `api_url` string, uri, required — The API URL of the external knowledge base.

---

[API](https://skmtc.net/orq-ai/apis/orq-ai-api.md) · [All operations](https://skmtc.net/orq-ai/apis/orq-ai-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/orq-ai/orq-ai-api/versions/41c02aedc7c0/schema)