Delete segment¶

Removes the specified segment from the current version of the source. It cannot be restored after deletion.

HTTP
DELETE $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, obtain the current segment version ID and index version as the baseline, and confirm the segment ID to be deleted.

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

Request¶

Input examples

Shell
curl -X DELETE "$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>
  }'

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

Request body

Commit the current version baseline of the source to avoid deleting versions that have been modified by other callers.

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.

Successful response¶

Returns 200 and the deleted 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": 1
      },
      "segment_versions": [
        {
          "version_id": "ver_03",
          "current": true,
          "chunk_count": 1
        }
      ],
      "segments": [
        {
          "segment_id": "seg_02",
          "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 source document after deletion.
`data.document.source.row_id`	string	Source record ID.
`data.document.segment_status.total`	integer	The current number of segments after deletion.
`data.document.segment_versions[].version_id`	string	The segment version ID generated or switched to after deletion.
`data.document.segments`	object[]	The remaining segments of the current version.
`data.document.segments[].segment_id`	string	Remaining segment ID.

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 delete segments.	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 delete it.	Retry after reading the latest document.
`500`	`ErrServer`	The service failed to delete the segment.	Keep the desensitized response information and try again.

Follow-up operations¶

Query document details Confirm that the segment has been deleted.

Last updated on Sep 15, 2026