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.

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. Poll 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.

An embedding model change re-embeds every document. Retrieval changes, the reasoning model included, take effect without a rebuild: documents already indexed keep what the previous model built until you re-index them with Re-index Documents.

Rules:

Send at least one of embedding or retrieval. Once models are active, send only one of them per call.
retrieval needs an enabled rerank model: 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.

1 min read

patch/knowledge-fs/spaces/{knowledge_base_id}/settings

Request example

curl --request PATCH \
  --url https://api.dify.ai/v1/knowledge-fs/spaces/{knowledge_base_id}/settings \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "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
  }
}'

import requests

url = "https://api.dify.ai/v1/knowledge-fs/spaces/{knowledge_base_id}/settings"
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json",
}
payload = {
    "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
    }
}

response = requests.request("PATCH", url, headers=headers, json=payload)

print(response.text)

const response = await fetch('https://api.dify.ai/v1/knowledge-fs/spaces/{knowledge_base_id}/settings', {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "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
    }
  })
});

const data = await response.json();
console.log(data);

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => 'https://api.dify.ai/v1/knowledge-fs/spaces/{knowledge_base_id}/settings',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => 'PATCH',
  CURLOPT_POSTFIELDS => '{
  "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
  }
}',
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer <token>',
    'Content-Type: application/json',
  ],
]);

$response = curl_exec($curl);
curl_close($curl);

echo $response;

package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	url := "https://api.dify.ai/v1/knowledge-fs/spaces/{knowledge_base_id}/settings"
	payload := strings.NewReader("{\n  \"embedding\": {\n    \"model\": \"text-embedding-3-small\",\n    \"pluginId\": \"langgenius/openai\",\n    \"provider\": \"openai\"\n  },\n  \"expectedRevision\": 7,\n  \"retrieval\": {\n    \"defaultMode\": \"fast\",\n    \"reasoningModel\": {\n      \"model\": \"gpt-4.1-mini\",\n      \"pluginId\": \"langgenius/openai\",\n      \"provider\": \"openai\"\n    },\n    \"rerank\": {\n      \"enabled\": true,\n      \"model\": {\n        \"model\": \"rerank-v3.5\",\n        \"pluginId\": \"langgenius/cohere\",\n        \"provider\": \"cohere\"\n      }\n    },\n    \"scoreThreshold\": {\n      \"enabled\": true,\n      \"stage\": \"mode-final\",\n      \"value\": 0.4\n    },\n    \"topK\": 10\n  }\n}")

	req, _ := http.NewRequest("PATCH", url, payload)
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))
}

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.dify.ai/v1/knowledge-fs/spaces/{knowledge_base_id}/settings"))
    .header("Authorization", "Bearer <token>")
    .header("Content-Type", "application/json")
    .method("PATCH", HttpRequest.BodyPublishers.ofString("{\n  \"embedding\": {\n    \"model\": \"text-embedding-3-small\",\n    \"pluginId\": \"langgenius/openai\",\n    \"provider\": \"openai\"\n  },\n  \"expectedRevision\": 7,\n  \"retrieval\": {\n    \"defaultMode\": \"fast\",\n    \"reasoningModel\": {\n      \"model\": \"gpt-4.1-mini\",\n      \"pluginId\": \"langgenius/openai\",\n      \"provider\": \"openai\"\n    },\n    \"rerank\": {\n      \"enabled\": true,\n      \"model\": {\n        \"model\": \"rerank-v3.5\",\n        \"pluginId\": \"langgenius/cohere\",\n        \"provider\": \"cohere\"\n      }\n    },\n    \"scoreThreshold\": {\n      \"enabled\": true,\n      \"stage\": \"mode-final\",\n      \"value\": 0.4\n    },\n    \"topK\": 10\n  }\n}"))
    .build();

HttpResponse<String> response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());

System.out.println(response.body());

require 'uri'
require 'net/http'

url = URI('https://api.dify.ai/v1/knowledge-fs/spaces/{knowledge_base_id}/settings')

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = url.scheme == 'https'

request = Net::HTTP::Patch.new(url)
request['Authorization'] = 'Bearer <token>'
request['Content-Type'] = 'application/json'
request.body = '{
  "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
  }
}'

response = http.request(request)
puts response.read_body

Response

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

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

{
  "code": "knowledge_fs_invalid_request",
  "message": "Agent Knowledge Base request is invalid.",
  "status": 400,
  "violations": [
    {
      "field": [
        "expectedRevision"
      ],
      "type": "missing"
    }
  ]
}

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

{
  "code": "knowledge_fs_invalid_credential",
  "message": "Invalid Agent Knowledge Base service credential.",
  "status": 401
}

{
  "code": "unauthorized",
  "message": "Authorization header must be provided and start with 'Bearer'",
  "status": 401
}

{
  "code": "unauthorized",
  "message": "Access token is invalid",
  "status": 401
}

{
  "code": "forbidden",
  "message": "Sorry, you have reached the knowledge base request rate limit of your subscription.",
  "status": 403
}

{
  "code": "knowledge_fs_access_denied",
  "message": "Agent Knowledge Base operation is not allowed.",
  "status": 403
}

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

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

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

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

{
  "code": "knowledge_fs_request_rejected",
  "message": "Agent Knowledge Base request was rejected.",
  "status": 422
}

{
  "code": "knowledge_fs_upstream_unavailable",
  "message": "Agent Knowledge Base is unavailable.",
  "status": 502
}

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

{
  "code": "knowledge_fs_operation_unavailable",
  "message": "Agent Knowledge Base operation is not available.",
  "status": 503
}

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

patch/knowledge-fs/spaces/{knowledge_base_id}/settings

Authorization

Authorizationstringheaderrequired#

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).

Keep keys server-side; never embed them in client code. Requests with a missing or invalid key fail with HTTP 401 (unauthorized).

Path parameters

knowledge_base_idstringrequired#

Knowledge base ID: the last segment of the Service API endpoint shown in the knowledge base's API Access dialog (…/knowledge-fs/spaces/<knowledge base ID>), and the segment after /datasets/new/ in the address bar.

Body

application/json

Any of

embeddingobjectrequired#

Responses

application/json

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, 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.

migrationobject#

Always null here: no migration started.

settingsobject#

Show child attributes

active_profile_availableboolean#

true when both an embedding model and retrieval settings are live, which happens after the first document is indexed.

active_profile_revisionsobject#

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 runs as a migration.

Show child attributes

embeddinginteger#

Revision of the live embedding model.

retrievalinteger#

Revision of the live retrieval settings.

capabilitiesobject#

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.

Show child attributes

deepboolean#

Queries at deep depth can run.

indexboolean#

Documents can be indexed. The models are live.

ingestboolean#

Documents can be added. The models are live, or complete pending settings are ready to be activated by the first document.

queryboolean#

Queries at fast depth can run.

researchboolean#

Queries at research depth can run.

source_syncboolean#

Sources can sync. Same condition as ingest.

configuration_statestring#

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.

embeddingobject#

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.

Show child attributes

dimensioninteger#

Vector dimension, observed when the model is first used. null until the model is live.

modelstring#

Model name.

plugin_idstring#

Plugin that provides the model, as organization/plugin_name.

providerstring#

Provider name inside the plugin.

revisioninteger#

Revision of the live embedding model. null until the model is live.

vector_space_idstring#

Identifies where the model's vectors are stored. null until the model is live.

issuesobject[]#

What keeps the knowledge base from being ready. Empty when nothing does.

Show child attributes

codestring#

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.

fieldstring#

The setting concerned: embedding, reasoning, rerank, or publication (the published content).

retryableboolean#

Whether waiting and retrying can clear the issue without a settings change.

retrievalobject#

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.

Show child attributes

default_modestring#

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.

reasoning_modelobject#

System reasoning model. Its dimension, revision, and vector_space_id are always null.

Show child attributes

dimensioninteger#

Always null.

modelstring#

Model name.

plugin_idstring#

Plugin that provides the model, as organization/plugin_name.

providerstring#

Provider name inside the plugin.

revisioninteger#

Always null.

vector_space_idstring#

Always null.

rerankobject#

Rerank model. Its model object uses the camelCase key pluginId, unlike the rest of this response.

Show child attributes

enabledboolean#

Whether retrieved chunks are reranked.

modelobject#

Rerank model selection. null when no rerank model is set.

Show child attributes

modelstring#

Model name.

pluginIdstring#

Plugin that provides the model, as organization/plugin_name.

providerstring#

Provider name inside the plugin.

revisioninteger#

Revision of the live retrieval settings. null while the settings are pending.

score_thresholdobject#

Score cutoff that drops low-scoring chunks.

Show child attributes

enabledboolean#

Whether the cutoff applies.

stagestring#

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.

valuenumber#

The cutoff score, 0 to 1. null when not set.

top_kinteger#

Maximum number of chunks each search returns.

revisioninteger#

Settings revision. Send it as expectedRevision in Update Knowledge Base Settings. The other revision fields in this response are not that value.

migrationobject#

The migration this change started. Follow it with Get Settings Migration.

Show child attributes

candidate_publication_fingerprintstring#

Internal. Not needed to follow the migration.

changed_kindstring#

What the change touched: embedding or retrieval.

checkpointstring#

Last step reached: queued, candidate-built, evaluated, or activated. To tell when the migration ends, read run_state.

completed_atstring#

When the migration ended (succeeded, failed, or canceled), ISO 8601. null while it runs.

created_atstring#

When the migration started, ISO 8601.

error_codestring#

Code of the last failure, for example PROFILE_MIGRATION_ATTEMPTS_EXHAUSTED or VECTOR_SPACE_QUOTA_EXCEEDED. null when none.

evaluation_summaryobject#

Flat map of results recorded for the migration. Not needed to follow the migration. null when none was recorded.

idstring#

Migration ID. Pass it to Get Settings Migration.

knowledge_space_idstring#

Internal ID of the knowledge base. Not the knowledge base ID in the path.

rebuild_scopestring#

What the migration rebuilds:

full-vector-space: an embedding model change re-embeds every document.
clone-publication: any retrieval change reuses the current index.
full-page-index-summary-outline: deprecated. Older migrations may still report it; a reasoning model change reports clone-publication.

run_statestring#

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 before trying the change again.
canceled: a newer change of the same kind replaced this migration before it finished. Follow the newer one.

updated_atstring#

When the migration last changed, ISO 8601.

settingsobject#

Show child attributes

active_profile_availableboolean#

true when both an embedding model and retrieval settings are live, which happens after the first document is indexed.

active_profile_revisionsobject#

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 runs as a migration.

Show child attributes

embeddinginteger#

Revision of the live embedding model.

retrievalinteger#

Revision of the live retrieval settings.

capabilitiesobject#

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.

Show child attributes

deepboolean#

Queries at deep depth can run.

indexboolean#

Documents can be indexed. The models are live.

ingestboolean#

Documents can be added. The models are live, or complete pending settings are ready to be activated by the first document.

queryboolean#

Queries at fast depth can run.

researchboolean#

Queries at research depth can run.

source_syncboolean#

Sources can sync. Same condition as ingest.

configuration_statestring#

embeddingobject#

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.

Show child attributes

dimensioninteger#

Vector dimension, observed when the model is first used. null until the model is live.

modelstring#

Model name.

plugin_idstring#

Plugin that provides the model, as organization/plugin_name.

providerstring#

Provider name inside the plugin.

revisioninteger#

Revision of the live embedding model. null until the model is live.

vector_space_idstring#

Identifies where the model's vectors are stored. null until the model is live.

issuesobject[]#

What keeps the knowledge base from being ready. Empty when nothing does.

Show child attributes

codestring#

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.

fieldstring#

The setting concerned: embedding, reasoning, rerank, or publication (the published content).

retryableboolean#

Whether waiting and retrying can clear the issue without a settings change.

retrievalobject#

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.

Show child attributes

default_modestring#

reasoning_modelobject#

System reasoning model. Its dimension, revision, and vector_space_id are always null.

Show child attributes

dimensioninteger#

Always null.

modelstring#

Model name.

plugin_idstring#

Plugin that provides the model, as organization/plugin_name.

providerstring#

Provider name inside the plugin.

revisioninteger#

Always null.

vector_space_idstring#

Always null.

rerankobject#

Rerank model. Its model object uses the camelCase key pluginId, unlike the rest of this response.

Show child attributes

enabledboolean#

Whether retrieved chunks are reranked.

modelobject#

Rerank model selection. null when no rerank model is set.

Show child attributes

modelstring#

Model name.

pluginIdstring#

Plugin that provides the model, as organization/plugin_name.

providerstring#

Provider name inside the plugin.

revisioninteger#

Revision of the live retrieval settings. null while the settings are pending.

score_thresholdobject#

Score cutoff that drops low-scoring chunks.

Show child attributes

enabledboolean#

Whether the cutoff applies.

stagestring#

valuenumber#

The cutoff score, 0 to 1. null when not set.

top_kinteger#

Maximum number of chunks each search returns.

revisioninteger#

Settings revision. Send it as expectedRevision in Update Knowledge Base Settings. The other revision fields in this response are not that value.

Get Knowledge Base Settings Get Settings Migration