Revectorize¶

Revectorizes enabled segments in the source’s current snapshot. The service returns the document snapshot after writing the vectors.

POST https://api.moi.matrixorigin.cn/v5/semantic-models/{model_id}/sources/{source_row_id}/segments/re-embedding

Preparation before calling¶

First query document details, confirm that the source has segments, and obtain data.etag. 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.

Request example¶

curl -X POST "https://api.moi.matrixorigin.cn/v5/semantic-models/$MODEL_ID/sources/$SOURCE_ROW_ID/segments/re-embedding" \
  -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.

Request body¶

Submit the 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. 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 the write. 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": "<DOCUMENT_ETAG_AFTER_WRITE>",
      "segments": [
        {
          "segment_id": "seg_01",
          "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 updated source document.
`data.document.segment_status`	object	Available status and number of segments.
`data.document.etag`	string	Current snapshot ETag after the write; returned when nonempty, for subsequent conditional writes.
`data.document.segments`	array of object	Segments in the current snapshot.

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 a source with no current segments, 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`	Invalid path ID or ETag, or the source has no current segments.	Read document details, confirm the segments, and submit the current ETag.
`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 supplied ETag differs from the current snapshot.	Read the latest snapshot and confirm before submitting again.
`500`	`ErrServer`	The service failed to perform revectorization.	Keep the desensitized response information and try again.

Follow-up operations¶

Query document details to inspect the current segments. Use the returned data.document.etag for the next write; on conflict, reread the snapshot and confirm before submitting again.

Last updated on Oct 19, 2026