Enable or disable segmentation¶

Update the enabled status of the specified segment and control whether the segment participates in retrieval.

HTTP
PATCH $CLOUDSIGMA_API_BASE/semantic-models/{model_id}/sources/{source_row_id}/segments/{segment_id}/enabled

Before you call this API¶

Configure the regional API endpoint and authentication, and select the target workspace.

First query the document details, obtain the current segment version ID and index version as the baseline, and confirm the segment ID to be operated.

Set the operation-specific values used in the request:

$MODEL_ID: Knowledge Base ID.
$SOURCE_ROW_ID: Source record ID.
$SEGMENT_ID: The segment ID to enable or disable.

Request¶

Input examples

Shell
curl -X PATCH "$CLOUDSIGMA_API_BASE/semantic-models/$MODEL_ID/sources/$SOURCE_ROW_ID/segments/$SEGMENT_ID/enabled" \
  -H "X-API-Key: $CLOUDSIGMA_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "base_segment_version_id": "<SEGMENT_VERSION_ID>",
    "base_index_version": <INDEX_VERSION>,
    "enabled": false
  }'

Parameter reference

Path parameters

Parameters	Type	Description
`model_id`	integer	Knowledge base ID.
`source_row_id`	string	Source record ID.
`segment_id`	string	The segment ID to enable or disable.

Request body

Commit target enablement status and source current version baseline.

Field	Type	Required	Description
`base_segment_version_id`	string	Yes	The current segment version ID read before the call.
`base_index_version`	integer	Yes	The current index version read before the call.
`enabled`	boolean	Yes	`true` enables segmentation, `false` disables segmentation.

Successful response¶

Returns 200 and the updated source document snapshot on success.

Response example

JSON
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "document": {
      "source": {
        "row_id": "src_01",
        "model_id": 401
      },
      "segment_status": {
        "available": true,
        "total": 2
      },
      "segment_versions": [
        {
          "version_id": "ver_02",
          "current": true
        }
      ],
      "segments": [
        {
          "segment_id": "seg_01",
          "enabled": false
        }
      ]
    }
  }
}

Field reference

The response fields are as follows.

Field	Type	Description
`code`	string	`OK` on success.
`msg`	string	`OK` on success.
`data.document`	object	Snapshot of the updated source document.
`data.document.source.row_id`	string	Source record ID.
`data.document.segment_status`	object	Current segment availability status and total number.
`data.document.segment_versions[].version_id`	string	Updated segment version ID.
`data.document.segments[].segment_id`	string	Segment ID.
`data.document.segments[].enabled`	boolean	Whether to participate in retrieval after update.

In field paths, [] means each item in an array. For example, data.document.segment_versions[].version_id is the version_id field of each item in data.document.segment_versions.

Error response¶

Response example

JSON
{
  "code": "ErrParamInvalid",
  "msg": "enabled is required",
  "data": null
}

Field reference

Common HTTP errors¶

HTTP status code	error code	Common causes	Recommended actions
`400`	`ErrParamInvalid`	`enabled`, path ID, or staging version baseline is invalid.	Provide a boolean value and reread the document to confirm the baseline.
`401`	`ErrUnauthorized`	The API Key is invalid or has expired.	Check API Key.
`403`	`ErrForbidden`	The caller does not have permission to update this source.	Check workspace and object authorization.
`404`	`ErrNotFound`	The knowledge base, source, or segment does not exist or is not visible to the current caller.	Reread document confirmation ID.
`409`	`ErrConflict`	The current version has changed and the service refuses to write.	Merge changes after reading the latest document and try again.
`500`	`ErrServer`	The service failed to update the segment status.	Keep the desensitized response information and try again.

Follow-up operations¶

Query document details Confirm that the segmentation enable status has taken effect.

Last updated on Sep 15, 2026