Enable or disable segmentation¶

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

PATCH https://api.moi.matrixorigin.cn/v5/semantic-models/{model_id}/sources/{source_row_id}/segments/{segment_id}/enabled

Preparation before calling¶

First query document details to obtain data.etag and confirm the target segment ID. Prepare a personal access token with access to the target workspace and its workspace ID.

The source must be a file source with kb_file_id and an available vector index; table sources do not support segment writes.

The example below uses:

$AI_STUDIO_API_KEY: The actual personal access token, passed through the X-API-Key Header.
$WORKSPACE_ID: Target workspace ID, passed through X-Workspace-ID Header.
$MODEL_ID: Knowledge Base ID.
$SOURCE_ROW_ID: Source record ID.
$SEGMENT_ID: The segment ID to enable or disable.

Request example¶

curl -X PATCH "https://api.moi.matrixorigin.cn/v5/semantic-models/$MODEL_ID/sources/$SOURCE_ROW_ID/segments/$SEGMENT_ID/enabled" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "if_match": "<DOCUMENT_ETAG>",
    "enabled": false
  }'

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¶

Submit the target enabled status and current snapshot’s ETag. If the body does not provide a nonempty if_match, pass the ETag in the If-Match header. At least one is required; a nonempty body value takes precedence.

Field	Type	Required	Description
`if_match`	string	Conditionally required	The `data.etag` read before this call; may be omitted when using the `If-Match` header.
`enabled`	boolean	Yes	`true` enables the segment; `false` disables it. Omission and `null` are rejected.

Successful response¶

Returns 200 and the complete updated source document snapshot on success. The example below is a response excerpt.

{
  "code": "OK",
  "msg": "OK",
  "data": {
    "document": {
      "source": {
        "row_id": "src_01",
        "model_id": 401
      },
      "segment_status": {
        "available": true,
        "total": 2
      },
      "etag": "<NEW_DOCUMENT_ETAG>",
      "segments": [
        {
          "segment_id": "seg_01",
          "enabled": false
        }
      ]
    }
  }
}

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.etag`	string	Current snapshot ETag; returned when nonempty, for subsequent conditional writes.
`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. See document details for the complete source, preview, file information, status, and segment fields. Optional segment fields are omitted when unset.

Error response¶

A missing or blank ETag, or an omitted, null, or nonboolean enabled, returns 400 with ErrParamInvalid. An ETag that differs from the current snapshot returns 409 with ErrConflict. Error messages depend on the request language.

{
  "code": "ErrParamInvalid",
  "msg": "<ERROR_MESSAGE>",
  "data": null
}

Common HTTP errors¶

HTTP status code	error code	Common causes	Recommended actions
`400`	`ErrParamInvalid`	`enabled`, path ID, or ETag 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 supplied ETag differs from the current snapshot.	Read the latest snapshot, confirm the target status, and submit 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 to confirm the enabled status. Use data.document.etag for the next write; on conflict, reread the snapshot and confirm the target status before submitting again.

Last updated on Oct 19, 2026