Delete segment¶

Removes a segment from the source’s current snapshot. Deletion cannot be undone, and the source must retain at least one segment.

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

Preparation before calling¶

First query document details to obtain data.etag and confirm the segment ID to delete. 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: Segment ID to delete.

Request example¶

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

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¶

Submit the current snapshot’s ETag to avoid overwriting another caller’s changes. 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. The body may be omitted when using only the header.

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.

Successful response¶

Returns 200 and the complete source document snapshot after deletion. 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": 1
      },
      "etag": "<NEW_DOCUMENT_ETAG>",
      "segments": [
        {
          "segment_id": "seg_02",
          "enabled": true
        }
      ]
    }
  }
}

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.etag`	string	Current snapshot ETag; returned when nonempty, for subsequent conditional writes.
`data.document.segments`	array of object	The remaining segments of the current snapshot.
`data.document.segments[].segment_id`	string	Remaining segment ID.

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 deleting the last segment, returns 400 with ErrParamInvalid. An ETag that differs from the current snapshot returns 409 with ErrConflict. Error messages depend on the request language.

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

Common HTTP errors¶

HTTP status code	error code	Common causes	Recommended actions
`400`	`ErrParamInvalid`	The path ID, body, or ETag is invalid, or deletion would leave no segments.	Read document details, submit the current ETag, and retain at least one segment.
`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 supplied ETag differs from the current snapshot.	Read the latest snapshot and confirm the deletion target before submitting again.
`500`	`ErrServer`	The service failed to delete the segment.	Keep the desensitized response information and try again.

Follow-up operations¶

Query document details to confirm the deletion. Use data.document.etag for the next write; on conflict, reread the snapshot and confirm the deletion target before submitting again.

Last updated on Oct 19, 2026