Revectorize¶

Re-vectorize the source segments. After the request is submitted successfully, you still need to read the source or process the task status to confirm the actual result.

HTTP
POST $CLOUDSIGMA_API_BASE/semantic-models/{model_id}/sources/{source_row_id}/segments/re-embedding

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.

Request¶

Input examples

Shell
curl -X POST "$CLOUDSIGMA_API_BASE/semantic-models/$MODEL_ID/sources/$SOURCE_ROW_ID/segments/re-embedding" \
  -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.

Request body

The current version baseline of the commit source.

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 an updated source document snapshot on success; the final result of the vectorization should still be confirmed by source or task status.

Response example

JSON
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "document": {
      "source": {
        "row_id": "src_01",
        "model_id": 401,
        "ingest_status": "processing"
      },
      "segment_status": {
        "available": true,
        "total": 2
      },
      "current_segment_version_id": "ver_03",
      "current_index_version": 3,
      "segment_versions": [
        {
          "version_id": "ver_03",
          "current": true,
          "index_version": 3,
          "chunk_count": 2
        }
      ],
      "segments": [
        {
          "segment_id": "seg_01",
          "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.ingest_status`	string	Current processing status; does not replace processing completion with HTTP success.
`data.document.segment_status`	object	Available status and number of segments.
`data.document.current_segment_version_id`	string	Current segment version.
`data.document.current_index_version`	integer	Current index version.
`data.document.segment_versions`	object[]	Currently available segment versions.
`data.document.segments`	object[]	Segmentation in the current version.

[] after a type means an array. For example, object[] is an array of objects.

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`	Invalid path ID or staging version baseline.	Use current baseline after rereading document.
`401`	`ErrUnauthorized`	The API Key is invalid or has expired.	Check API Key.
`403`	`ErrForbidden`	The caller does not have permission to update the source.	Check workspace and object authorization.
`404`	`ErrNotFound`	The knowledge base or source does not exist or is not visible to the current caller.	Reconfirm the path ID.
`409`	`ErrConflict`	The current segment version has changed.	Retry after reading the latest document.
`500`	`ErrServer`	The service failed to perform revectorization.	Keep the desensitized response information and try again.

Follow-up operations¶

Vectorization is performed asynchronously. Confirm the final result of vectorization through Query data processing tasks or Query document details.

Last updated on Sep 15, 2026