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.

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

cURL

request

curl --request PATCH \
  --url https://{api_base_url}/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
  }
}
'

200

success

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

Authorizations

Authorization · string · header · required

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_id · string<uuid> · required

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

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.

Embedding Settings

Retrieval Settings

embedding · object · required

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

Show child attributes

expectedRevision · integer · required

The current revision from Get Knowledge Base Settings. A stale value answers 409 and nothing changes.

Required range: x >= 1

retrieval · object | null

The retrieval settings a query uses: reasoning model, rerank model, score threshold, topK, and the depth to fall back on.

Show child attributes

Response

200

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.

migration · object | null

Always null here: no migration started.

settings · object

Show child attributes