Update segments¶

Updates the contents of the specified section. Version baselines are used to avoid overwriting newer modifications.

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

Before you call this API¶

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

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

Set the operation-specific values used in the request:

$MODEL_ID: Knowledge Base ID.
$SOURCE_ROW_ID: Source record ID.
$SEGMENT_ID: Segment ID to update.

Request¶

Input examples

Shell
curl -X PATCH "$CLOUDSIGMA_API_BASE/semantic-models/$MODEL_ID/sources/$SOURCE_ROW_ID/segments/$SEGMENT_ID" \
  -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>,
    "content": "<SEGMENT_CONTENT>"
  }'

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

Request body

Submit the source’s current version baseline, and the text, OCR text, or image description to be updated.

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.
`content`	string	No	The updated text content.
`ocr_text`	string	No	Updated OCR text.
`image_description`	string	No	Updated image description.

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,
          "chunk_count": 2
        }
      ],
      "segments": [
        {
          "segment_id": "seg_01",
          "segment_type": "text",
          "level": "chunk",
          "content": "更新后的文本",
          "enabled": true
        }
      ]
    }
  }
}

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.segment_versions[].current`	boolean	Whether it is the current segmented version.
`data.document.segments[].segment_id`	string	Segment ID.
`data.document.segments[].content`	string	Updated segmented text; may be omitted if content is not returned.
`data.document.segments[].enabled`	boolean	Whether the segment participates in retrieval.

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": "ErrConflict",
  "msg": "segment version conflict",
  "data": null
}

Field reference

Common HTTP errors¶

HTTP status code	error code	Common causes	Recommended actions
`400`	`ErrParamInvalid`	The path ID, request body, or staging version baseline is invalid.	Submit using the current version information after re-reading the document.
`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.	Keep the desensitized response information and try again.

Follow-up operations¶

Query document details to confirm the update result.

Last updated on Sep 15, 2026