> ## Documentation Index > Fetch the complete documentation index at: https://docs.dify.ai/llms.txt > Use this file to discover all available pages before exploring further. # Update Knowledge Base Settings > Changes the knowledge base's embedding model or retrieval settings. For setting models before and after content is indexed, see [Change Models or Retrieval Settings](/en/api-reference/guides/knowledge-base#change-models-or-retrieval-settings). What happens depends on whether models are active yet: - Before the first document is indexed, the settings are stored as pending, and the call answers `200`. They are validated and take effect when the first document is indexed. Omitting `embedding` or `retrieval` leaves that group at its pending value. - Once models are active, the call returns `202` and the change runs as a migration. An embedding or reasoning model change rebuilds the content it affects, while other retrieval changes take effect without a rebuild. Poll [Get Settings Migration](/en/api-reference/settings/get-settings-migration) with `migration.id` until it ends, then read the final settings. A change that needs no migration, such as resending the active embedding model, returns `200`. Rules: - Send at least one of `embedding` or `retrieval`. Once models are active, send only one of them per call. - `retrieval` cannot be stored without an enabled rerank model, so send `rerank.enabled: true` and a `rerank.model` with it. - `retrieval` needs an embedding model, sent in the same call or stored earlier. Otherwise the call answers `409`. - `scoreThreshold.enabled: true` requires a `scoreThreshold.value`. ## OpenAPI ````yaml /en/api-reference/openapi_service.json patch /knowledge-fs/spaces/{knowledge_base_id}/settings openapi: 3.0.1 info: description: >- REST API for Dify applications and knowledge bases. Application endpoints authenticate with an app API key; knowledge endpoints authenticate with a dataset API key. title: Dify Service API version: 1.0.0 servers: - description: >- Base URL of the Dify Service API. For self-hosted deployments, replace it with your own API base URL. url: https://{api_base_url} variables: api_base_url: default: api.dify.ai/v1 description: Host and path of the API base URL, without the `https://` prefix. security: - ApiKeyAuth: [] tags: - description: Operations related to chat messages and interactions. name: Chat Messages - description: File upload and preview operations. name: Files - description: Operations related to end user information. name: End Users - description: User feedback operations. name: Feedback - description: Operations related to managing conversations. name: Conversations - description: Text-to-Speech and Speech-to-Text operations. name: Audio - description: Operations to retrieve application settings and information. name: Applications - description: Operations related to managing annotations for direct replies. name: Annotations - description: Endpoints for resuming paused workflows that require human input. name: Human Input - description: Operations for executing and managing workflows. name: Workflow Runs - description: Operations related to text generation and completion. name: Completion Messages - description: >- Operations for managing knowledge bases, including creation, configuration, and retrieval. name: Knowledge Bases - description: >- Operations for creating, updating, and managing documents within a knowledge base. name: Documents - description: Operations for managing document chunks and child chunks. name: Chunks - description: >- Operations for managing knowledge base metadata fields and document metadata values. name: Metadata - description: Operations for managing knowledge base tags and tag bindings. name: Tags - description: Operations for retrieving available models. name: Models - description: >- Operations for managing and running knowledge pipelines, including datasource plugins and pipeline execution. name: Knowledge Pipeline - description: Ask a knowledge base a question and stream the answer. name: Queries - description: Inspect what a query retrieved and why. name: Query Records - description: Run a research question in the background and collect its results. name: Research Tasks - description: >- Read the documents in a knowledge base, their files, revisions, and chunks; label documents with metadata. name: Documents and Chunks - description: >- Follow, cancel, or retry indexing, and list the knowledge base's background tasks. name: Indexing Tasks - description: >- Follow the deletion of a document file, a batch of files, or a source until it finishes. name: Deletion Jobs - description: >- Manage the sources that feed a knowledge base, their sync schedules, and their connections. name: Sources - description: >- Sync a source now, import website pages or provider items, and follow, cancel, or retry the runs. name: Source Syncs and Imports - description: >- Read and change the knowledge base's models and retrieval settings, and follow the migration a change starts. name: Settings paths: /knowledge-fs/spaces/{knowledge_base_id}/settings: patch: tags: - Settings summary: Update Knowledge Base Settings description: >- Changes the knowledge base's embedding model or retrieval settings. For setting models before and after content is indexed, see [Change Models or Retrieval Settings](/en/api-reference/guides/knowledge-base#change-models-or-retrieval-settings). What happens depends on whether models are active yet: - Before the first document is indexed, the settings are stored as pending, and the call answers `200`. They are validated and take effect when the first document is indexed. Omitting `embedding` or `retrieval` leaves that group at its pending value. - Once models are active, the call returns `202` and the change runs as a migration. An embedding or reasoning model change rebuilds the content it affects, while other retrieval changes take effect without a rebuild. Poll [Get Settings Migration](/en/api-reference/settings/get-settings-migration) with `migration.id` until it ends, then read the final settings. A change that needs no migration, such as resending the active embedding model, returns `200`. Rules: - Send at least one of `embedding` or `retrieval`. Once models are active, send only one of them per call. - `retrieval` cannot be stored without an enabled rerank model, so send `rerank.enabled: true` and a `rerank.model` with it. - `retrieval` needs an embedding model, sent in the same call or stored earlier. Otherwise the call answers `409`. - `scoreThreshold.enabled: true` requires a `scoreThreshold.value`. operationId: updateKnowledgeBaseSettings parameters: - description: >- Knowledge base ID: the last segment of the Service API endpoint shown in the knowledge base's **API Access** dialog (`…/knowledge-fs/spaces/`), and the segment after `/datasets/new/` in the address bar. in: path name: knowledge_base_id required: true schema: format: uuid type: string requestBody: content: application/json: examples: request: summary: Request Example - Before models are active value: embedding: model: text-embedding-3-small pluginId: langgenius/openai provider: openai expectedRevision: 7 retrieval: defaultMode: fast reasoningModel: model: gpt-4.1-mini pluginId: langgenius/openai provider: openai rerank: enabled: true model: model: rerank-v3.5 pluginId: langgenius/cohere provider: cohere scoreThreshold: enabled: true stage: mode-final value: 0.4 topK: 10 request_embedding: summary: Request Example - Change the embedding model value: embedding: model: text-embedding-3-large pluginId: langgenius/openai provider: openai expectedRevision: 7 schema: additionalProperties: false anyOf: - properties: embedding: nullable: false type: object required: - embedding title: Embedding Settings - properties: retrieval: nullable: false type: object required: - retrieval title: Retrieval Settings properties: embedding: additionalProperties: false description: >- The embedding model used to index content. Once a model is active, changing it starts a migration that re-embeds every document. Find the values with [Get Available Models](/en/api-reference/models/get-available-models): `text-embedding` for embedding models, `llm` for the reasoning model, `rerank` for rerank models. `pluginId` is the plugin's `organization/plugin_name`, `provider` its provider name, `model` the model name. Get Available Models returns one `provider` string shaped `organization/plugin_name/provider_name`, so `langgenius/openai/openai` splits into `pluginId` `langgenius/openai` and `provider` `openai`. A bare `openai` stands for `langgenius/openai/openai`. nullable: true properties: model: description: >- Model name as the provider plugin lists it, for example `text-embedding-3-small`. maxLength: 256 minLength: 1 type: string pluginId: description: >- Plugin that provides the model, as `organization/plugin_name` (for example `langgenius/openai`). maxLength: 256 minLength: 1 type: string provider: description: Provider name inside the plugin, for example `openai`. maxLength: 256 minLength: 1 type: string required: - model - pluginId - provider type: object expectedRevision: description: >- The current `revision` from [Get Knowledge Base Settings](/en/api-reference/settings/get-knowledge-base-settings). A stale value answers `409` and nothing changes. minimum: 1 type: integer retrieval: additionalProperties: false description: >- The retrieval settings a query uses: reasoning model, rerank model, score threshold, `topK`, and the depth to fall back on. nullable: true properties: defaultMode: description: >- Retrieval depth used when a query omits `mode`. See [Retrieval Depth](/en/cloud/use-dify/knowledge-base/retrieval-settings#retrieval-depth). enum: - fast - deep - research type: string reasoningModel: additionalProperties: false description: >- System reasoning model: used during indexing and by `research` queries. Find the values with [Get Available Models](/en/api-reference/models/get-available-models). properties: model: description: Model name as the provider plugin lists it. maxLength: 256 minLength: 1 type: string pluginId: description: >- Plugin that provides the model, as `organization/plugin_name`. maxLength: 256 minLength: 1 type: string provider: description: Provider name inside the plugin. maxLength: 256 minLength: 1 type: string required: - model - pluginId - provider type: object rerank: additionalProperties: false description: >- The rerank model applied to retrieved chunks. This operation requires `enabled: true` and a non-null model. properties: enabled: description: Whether retrieved chunks are reranked. enum: - true type: boolean model: additionalProperties: false description: >- Rerank model selection. Find the values with [Get Available Models](/en/api-reference/models/get-available-models). nullable: false properties: model: description: Model name as the provider plugin lists it. maxLength: 256 minLength: 1 type: string pluginId: description: >- Plugin that provides the model, as `organization/plugin_name`. maxLength: 256 minLength: 1 type: string provider: description: Provider name inside the plugin. maxLength: 256 minLength: 1 type: string required: - model - pluginId - provider type: object required: - enabled - model type: object scoreThreshold: additionalProperties: false anyOf: - properties: enabled: enum: - false title: Threshold Disabled - properties: enabled: enum: - true value: nullable: false type: number required: - value title: Threshold Enabled description: Score cutoff that drops low-scoring chunks. properties: enabled: description: >- Whether the cutoff applies. When `true`, send `value`. type: boolean stage: default: mode-final description: >- Where the cutoff applies. `mode-final` applies it to the final score of the depth that runs: the rerank score at `fast` and `deep`, the PageIndex score at `research`. `rerank` is the same thing under its old name. enum: - mode-final - rerank type: string value: description: >- The cutoff score. Chunks scoring below it are dropped. Higher cutoffs keep only close matches and risk returning nothing. Lower cutoffs let broader matches through. maximum: 1 minimum: 0 nullable: true type: number required: - enabled type: object topK: description: >- Maximum number of chunks each search returns. Higher values give the model more context and more noise. Lower values stay focused and can miss relevant chunks. maximum: 100 minimum: 1 type: integer required: - defaultMode - reasoningModel - rerank - scoreThreshold - topK type: object required: - expectedRevision type: object description: >- [Get Knowledge Base Settings](/en/api-reference/settings/get-knowledge-base-settings) answers in snake_case and this body is camelCase, so its response cannot be sent back unchanged. Optional fields marked nullable treat `null` as omitted. The normalized request must fit within 65,536 UTF-8 bytes. See [Request Size Limits](/en/api-reference/guides/knowledge-base#request-size-limits). required: true responses: '200': content: application/json: examples: success: summary: Response Example value: migration: null settings: active_profile_available: false active_profile_revisions: embedding: null retrieval: null capabilities: deep: false index: false ingest: true query: false research: false source_sync: true configuration_state: active embedding: dimension: null model: text-embedding-3-small plugin_id: langgenius/openai provider: openai revision: null vector_space_id: null issues: [] retrieval: default_mode: fast reasoning_model: dimension: null model: gpt-4.1-mini plugin_id: langgenius/openai provider: openai revision: null vector_space_id: null rerank: enabled: true model: model: rerank-v3.5 pluginId: langgenius/cohere provider: cohere revision: null score_threshold: enabled: true stage: mode-final value: 0.4 top_k: 10 revision: 8 schema: properties: migration: description: 'Always `null` here: no migration started.' nullable: true type: object settings: $ref: '#/components/schemas/KnowledgeBaseSettings' type: object description: >- No migration started: the settings were stored as pending, or models are active and the change needed no migration. `settings` has the same shape as [Get Knowledge Base Settings](/en/api-reference/settings/get-knowledge-base-settings), and its `revision` is the value to send on the next update. While the settings are pending, `active_profile_available` stays `false` and `capabilities.query` stays `false`. '202': content: application/json: examples: migration: summary: Response Example - Migration started value: migration: candidate_publication_fingerprint: null changed_kind: embedding checkpoint: queued completed_at: null created_at: '2026-09-08T03:10:00Z' error_code: null evaluation_summary: null id: a7c3e9f1-2b4d-4c6e-8f0a-1b3d5f7a9c2e knowledge_space_id: 0a9d3c2e-5b6f-4e1a-8c7d-2f3e4a5b6c7d rebuild_scope: full-vector-space run_state: queued updated_at: '2026-09-08T03:10:00Z' settings: active_profile_available: true active_profile_revisions: embedding: 2 retrieval: 3 capabilities: deep: true index: true ingest: true query: true research: true source_sync: true configuration_state: active embedding: dimension: 1536 model: text-embedding-3-small plugin_id: langgenius/openai provider: openai revision: 2 vector_space_id: >- embedding-space-sha256:4f7c2d9a1b3e5f60718293a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4 issues: [] retrieval: default_mode: fast reasoning_model: dimension: null model: gpt-4.1-mini plugin_id: langgenius/openai provider: openai revision: null vector_space_id: null rerank: enabled: true model: model: rerank-v3.5 pluginId: langgenius/cohere provider: cohere revision: 3 score_threshold: enabled: false stage: mode-final value: null top_k: 10 revision: 7 schema: properties: migration: allOf: - $ref: '#/components/schemas/KnowledgeBaseSettingsMigration' description: >- The migration this change started. Follow it with [Get Settings Migration](/en/api-reference/settings/get-settings-migration). settings: $ref: '#/components/schemas/KnowledgeBaseSettings' type: object description: >- The change started a migration, described in `migration`. `settings` has the same shape as [Get Knowledge Base Settings](/en/api-reference/settings/get-knowledge-base-settings). '400': content: application/json: examples: knowledge_fs_invalid_request: summary: knowledge_fs_invalid_request value: code: knowledge_fs_invalid_request message: Agent Knowledge Base request is invalid. status: 400 violations: - field: - expectedRevision type: missing knowledge_fs_invalid_request_upstream: summary: knowledge_fs_invalid_request (settings rejected) value: code: knowledge_fs_invalid_request failure: category: validation code: KNOWLEDGE_FS_INVALID_REQUEST message: The Agent Knowledge Base request is invalid. retryPolicy: never traceId: 9b7d3e1a-4c2f-4a8e-b6d0-5f1e2c3d4a5b message: The Agent Knowledge Base request is invalid. status: 400 description: >- - `knowledge_fs_invalid_request`: the request failed validation. `violations` names each failing field. Causes: - An unknown key, or a field outside its constraints. - Neither `embedding` nor `retrieval` was sent. - `retrieval` without an enabled rerank model. - `knowledge_fs_invalid_request`: the settings were rejected, for example `scoreThreshold.enabled: true` without a `value`. '401': content: application/json: examples: knowledge_fs_invalid_credential: summary: knowledge_fs_invalid_credential value: code: knowledge_fs_invalid_credential message: Invalid Agent Knowledge Base service credential. status: 401 unauthorized_1: summary: unauthorized (header missing) value: code: unauthorized message: >- Authorization header must be provided and start with 'Bearer' status: 401 unauthorized_2: summary: unauthorized (key unknown) value: code: unauthorized message: Access token is invalid status: 401 description: >- - `unauthorized`: the `Authorization` header is missing, or the key is unknown or not a knowledge base API key. - `knowledge_fs_invalid_credential`: the key is valid, but no knowledge base with this ID exists in the key's workspace, or the key is not tied to a workspace. '403': content: application/json: examples: forbidden: summary: forbidden (rate limit) value: code: forbidden message: >- Sorry, you have reached the knowledge base request rate limit of your subscription. status: 403 knowledge_fs_access_denied: summary: knowledge_fs_access_denied value: code: knowledge_fs_access_denied message: Agent Knowledge Base operation is not allowed. status: 403 description: >- - `knowledge_fs_access_denied`: the key is scoped to other knowledge bases, **API access** is off for this knowledge base, or the knowledge base is not active. - `knowledge_fs_access_denied`: the request's authorization was rejected. - `forbidden`: on Dify Cloud, the workspace has reached the knowledge base request rate limit of its subscription. Every call counts, reads included. '404': content: application/json: examples: knowledge_fs_resource_not_found: summary: knowledge_fs_resource_not_found value: code: knowledge_fs_resource_not_found failure: category: not_found code: KNOWLEDGE_FS_NOT_FOUND message: >- The requested Agent Knowledge Base resource was not found. retryPolicy: never traceId: 9b7d3e1a-4c2f-4a8e-b6d0-5f1e2c3d4a5b message: The requested Agent Knowledge Base resource was not found. status: 404 not_found: summary: not_found (feature off) value: code: not_found message: >- The requested URL was not found on the server. If you entered the URL manually please check your spelling and try again. status: 404 description: >- - `knowledge_fs_resource_not_found`: the knowledge base ID isn't recognized. - `not_found`: the Agent Knowledge Base feature is turned off on this deployment. '409': content: application/json: examples: knowledge_fs_conflict: summary: knowledge_fs_conflict (no embedding model) value: code: knowledge_fs_conflict failure: action: retry category: conflict code: KNOWLEDGE_FS_CONFLICT message: >- The Agent Knowledge Base operation conflicts with the current resource state. retryPolicy: manual traceId: 9b7d3e1a-4c2f-4a8e-b6d0-5f1e2c3d4a5b message: >- The Agent Knowledge Base operation conflicts with the current resource state. status: 409 knowledge_space_settings_revision_conflict: summary: knowledge_fs_conflict (stale revision) value: code: knowledge_fs_conflict failure: action: retry category: conflict code: KNOWLEDGE_SPACE_SETTINGS_REVISION_CONFLICT message: >- Knowledge space settings have changed. Reload the latest settings and review your changes before saving again. retryPolicy: manual traceId: 5e2a9c17-3b4d-4f60-8a1b-2c3d4e5f6a7b message: >- Knowledge space settings have changed. Reload the latest settings and review your changes before saving again. status: 409 description: >- - `knowledge_fs_conflict`: the body's `failure.code` names the cause: - `KNOWLEDGE_SPACE_SETTINGS_REVISION_CONFLICT`: `expectedRevision` is not the current `revision`, for example because another update landed first. Re-read [Get Knowledge Base Settings](/en/api-reference/settings/get-knowledge-base-settings) and retry with the `revision` it returns. - `KNOWLEDGE_SPACE_SETTINGS_COMPILATION_IN_PROGRESS`: a document is being processed. Wait for processing to finish, or cancel the indexing tasks, before changing models. - `KNOWLEDGE_SPACE_SETTINGS_MIGRATION_REQUIRED`: the change needs a migration that this call could not start, because models became active or the content is not published yet. Re-read the settings before trying again. - `KNOWLEDGE_FS_CONFLICT`: before models are active, `retrieval` was sent for a knowledge base with no embedding model. Configure one before sending `retrieval`. Once models are active, the same code means the migration could not be requested or retried. '422': content: application/json: examples: knowledge_fs_request_rejected: summary: knowledge_fs_request_rejected (both groups) value: code: knowledge_fs_request_rejected message: Agent Knowledge Base request was rejected. status: 422 description: >- - `knowledge_fs_request_rejected`: models are active and the body sends both `embedding` and `retrieval`. Send them in separate calls. This body carries neither `failure` nor `violations`. - `knowledge_fs_request_rejected`: once models are active, the selected model failed the preflight check. The body carries `failure` with a `MODEL_*` or `EMBEDDING_DIMENSION_*` code. '502': content: application/json: examples: knowledge_fs_upstream_unavailable: summary: knowledge_fs_upstream_unavailable value: code: knowledge_fs_upstream_unavailable message: Agent Knowledge Base is unavailable. status: 502 knowledge_fs_upstream_unavailable_upstream: summary: knowledge_fs_upstream_unavailable (internal error) value: code: knowledge_fs_upstream_unavailable failure: action: contact_admin category: internal code: KNOWLEDGE_FS_INTERNAL_ERROR message: >- Agent Knowledge Base could not complete the operation. Try again, or contact an administrator with the error reference. retryPolicy: manual traceId: 9b7d3e1a-4c2f-4a8e-b6d0-5f1e2c3d4a5b message: >- Agent Knowledge Base could not complete the operation. Try again, or contact an administrator with the error reference. status: 502 description: >- - `knowledge_fs_upstream_unavailable`: no answer came back in time, or the answer couldn't be read. The settings may have been stored. Read [Get Knowledge Base Settings](/en/api-reference/settings/get-knowledge-base-settings) and compare the values and `revision` before sending another update. A changed revision alone does not confirm that your update succeeded or that the models passed validation. '503': content: application/json: examples: knowledge_fs_operation_unavailable: summary: knowledge_fs_operation_unavailable value: code: knowledge_fs_operation_unavailable message: Agent Knowledge Base operation is not available. status: 503 knowledge_fs_operation_unavailable_upstream: summary: knowledge_fs_operation_unavailable (temporary) value: code: knowledge_fs_operation_unavailable failure: action: retry category: dependency code: KNOWLEDGE_FS_UNAVAILABLE message: >- A service required by Agent Knowledge Base is temporarily unavailable. retryPolicy: manual traceId: 5e2a9c17-3b4d-4f60-8a1b-2c3d4e5f6a7b message: >- A service required by Agent Knowledge Base is temporarily unavailable. status: 503 description: >- - `knowledge_fs_operation_unavailable`: the Agent Knowledge Base feature is not set up for this workspace, this operation is not available on the deployment, or the key's access to this knowledge base changed while the request was being authorized. Try again. - `knowledge_fs_operation_unavailable`: the request can't be served right now. Follow `failure.retryPolicy`. - `knowledge_fs_operation_unavailable`: `retrieval` was sent while an embedding model is active but no retrieval settings are, so the change cannot be routed. - `knowledge_fs_operation_unavailable`: the model preflight check or the migration can't be started right now. components: schemas: KnowledgeBaseSettings: properties: active_profile_available: description: >- `true` when both an embedding model and retrieval settings are live, which happens after the first document is indexed. type: boolean active_profile_revisions: description: >- Revisions of the live models. Each is `null` until the first document is indexed. Once a profile is active, a change through [Update Knowledge Base Settings](/en/api-reference/settings/update-knowledge-base-settings) runs as a migration. properties: embedding: description: Revision of the live embedding model. nullable: true type: integer retrieval: description: Revision of the live retrieval settings. nullable: true type: integer type: object capabilities: description: >- Readiness of the published settings. Three flags stand for retrieval depths, with `query` standing for `fast`. To check readiness for a specific depth, send that depth explicitly as `mode` and check its flag. Do not use a pending `retrieval.default_mode` to identify the depth of a query that omits `mode`. properties: deep: description: Queries at `deep` depth can run. type: boolean index: description: Documents can be indexed. The models are live. type: boolean ingest: description: >- Documents can be added. The models are live, or complete pending settings are ready to be activated by the first document. type: boolean query: description: Queries at `fast` depth can run. type: boolean research: description: Queries at `research` depth can run. type: boolean source_sync: description: Sources can sync. Same condition as `ingest`. type: boolean type: object configuration_state: description: >- `active` when an embedding model and complete retrieval settings (with an enabled rerank model) are stored. `setup-required` when either is missing. `validation-failed` when the pending settings failed validation while the first document was indexed. `issues` names the settings that failed. type: string embedding: description: >- Embedding model. The pending selection when one is stored, otherwise the live model. A pending selection can differ from the model queries use now. `null` when none is set. Its `dimension`, `revision`, and `vector_space_id` are informational, and no operation takes them. nullable: true properties: dimension: description: >- Vector dimension, observed when the model is first used. `null` until the model is live. nullable: true type: integer model: description: Model name. type: string plugin_id: description: Plugin that provides the model, as `organization/plugin_name`. type: string provider: description: Provider name inside the plugin. type: string revision: description: >- Revision of the live embedding model. `null` until the model is live. nullable: true type: integer vector_space_id: description: >- Identifies where the model's vectors are stored. `null` until the model is live. nullable: true type: string type: object issues: description: >- What keeps the knowledge base from being ready. Empty when nothing does. items: properties: code: description: >- What is wrong with the setting: - `missing`: the selection is absent, or rerank is disabled. - `validation_failed`, `unavailable`, or `incompatible`: the pending settings failed validation. For `incompatible`, check the model's supported task, embedding dimension, and whether the provider returned the selected model. - `binding_missing`: the published content is not ready to use the configured models. Check indexing progress in Dify. - `unavailable` on `publication`: the published content is not ready for every depth. type: string field: description: >- The setting concerned: `embedding`, `reasoning`, `rerank`, or `publication` (the published content). type: string retryable: description: >- Whether waiting and retrying can clear the issue without a settings change. type: boolean type: object type: array retrieval: description: >- Retrieval settings. The pending selection when one is stored, otherwise the live settings. A pending selection can differ from the settings queries use now. `null` when none is set. nullable: true properties: default_mode: description: >- Default depth in the returned retrieval settings: `fast`, `deep`, or `research`. When a query omits `mode`, it uses the published default, which can differ from this value if pending settings are returned. type: string reasoning_model: description: >- System reasoning model. Its `dimension`, `revision`, and `vector_space_id` are always `null`. properties: dimension: description: Always `null`. nullable: true type: integer model: description: Model name. type: string plugin_id: description: >- Plugin that provides the model, as `organization/plugin_name`. type: string provider: description: Provider name inside the plugin. type: string revision: description: Always `null`. nullable: true type: integer vector_space_id: description: Always `null`. nullable: true type: string type: object rerank: description: >- Rerank model. Its `model` object uses the camelCase key `pluginId`, unlike the rest of this response. properties: enabled: description: Whether retrieved chunks are reranked. type: boolean model: description: Rerank model selection. `null` when no rerank model is set. nullable: true properties: model: description: Model name. type: string pluginId: description: >- Plugin that provides the model, as `organization/plugin_name`. type: string provider: description: Provider name inside the plugin. type: string type: object type: object revision: description: >- Revision of the live retrieval settings. `null` while the settings are pending. nullable: true type: integer score_threshold: description: Score cutoff that drops low-scoring chunks. properties: enabled: description: Whether the cutoff applies. type: boolean stage: description: >- Where the cutoff applies. `mode-final` applies it to the final score of the depth that runs: the rerank score at `fast` and `deep`, the PageIndex score at `research`. `rerank` is the same thing under its old name. type: string value: description: The cutoff score, 0 to 1. `null` when not set. nullable: true type: number type: object top_k: description: Maximum number of chunks each search returns. type: integer type: object revision: description: >- Settings revision. Send it as `expectedRevision` in [Update Knowledge Base Settings](/en/api-reference/settings/update-knowledge-base-settings). The other revision fields in this response are not that value. type: integer type: object KnowledgeBaseSettingsMigration: properties: candidate_publication_fingerprint: description: Internal. Not needed to follow the migration. nullable: true type: string changed_kind: description: 'What the change touched: `embedding` or `retrieval`.' type: string checkpoint: description: >- Last step reached: `queued`, `candidate-built`, `evaluated`, or `activated`. type: string completed_at: description: >- When the migration ended (`succeeded`, `failed`, or `canceled`), ISO 8601. `null` while it runs. nullable: true type: string created_at: description: When the migration started, ISO 8601. type: string error_code: description: >- Code of the last failure, for example `PROFILE_MIGRATION_ATTEMPTS_EXHAUSTED` or `VECTOR_SPACE_QUOTA_EXCEEDED`. `null` when none. nullable: true type: string evaluation_summary: description: >- Flat map of evaluation results recorded for the rebuilt index. `null` when none was recorded. nullable: true type: object id: description: >- Migration ID. Pass it to [Get Settings Migration](/en/api-reference/settings/get-settings-migration). type: string knowledge_space_id: description: >- Internal ID of the knowledge base. Not the knowledge base ID in the path. type: string rebuild_scope: description: >- What the migration rebuilds: - `full-vector-space`: an embedding model change re-embeds every document. - `full-page-index-summary-outline`: a reasoning model change rebuilds the page index, summaries, and outlines. - `clone-publication`: any other retrieval change reuses the current index. type: string run_state: description: >- Progress of the migration: - `queued`, `running`: in progress. - `succeeded`: the new settings are in effect. - `failed`: stopped. `error_code` says why. Check the models in [Get Knowledge Base Settings](/en/api-reference/settings/get-knowledge-base-settings) before trying the change again. - `canceled`: a newer change of the same kind replaced this migration before it finished. Follow the newer one. type: string updated_at: description: When the migration last changed, ISO 8601. type: string type: object securitySchemes: ApiKeyAuth: bearerFormat: API_KEY description: >- Every request authenticates with an API key: `Authorization: Bearer {API_KEY}`. App endpoints take an app API key; knowledge endpoints take a knowledge base API key ([Get Started](/en/api-reference/guides/get-started)). Keep keys server-side; never embed them in client code. Requests with a missing or invalid key fail with HTTP `401` (`unauthorized`). scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.