Settings

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. An embedding or reasoning model change rebuilds the content it affects, while other retrieval changes take effect without a rebuild. 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.

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.

PATCH

knowledge-fs

spaces

{knowledge_base_id}

settings

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
  }
}
'

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

The normalized request must fit within 65,536 UTF-8 bytes. See Request Size Limits.

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

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

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
  }
}
'

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

Guides

App APIs

Knowledge APIs

Update Knowledge Base Settings

Authorizations

Path Parameters

Body

Response