Import initial segments¶

Import initial segments for the source. The current version baseline of the source must be read before calling; when the baseline does not match, the service refuses to write and the document details should be re-read.

HTTP
POST $CLOUDSIGMA_API_BASE/semantic-models/{model_id}/sources/{source_row_id}/segments/import-initial

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 to import initial segment from.

This interface does not receive segment content; the service imports the initial segments available for this source based on the baseline.

Request¶

Input examples

Shell
curl -X POST "$CLOUDSIGMA_API_BASE/semantic-models/$MODEL_ID/sources/$SOURCE_ROW_ID/segments/import-initial" \
  -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 to import the initial segment from.

Request body

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 updated source document snapshot on success.

Response example

JSON
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "document": {
      "source": {
        "row_id": "src_01",
        "model_id": 401,
        "ingest_status": "ready"
      },
      "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`	object	Source record.
`data.document.segment_status.available`	boolean	Whether segmented data is available.
`data.document.segment_status.total`	integer	The number of segments that can currently be read.
`data.document.segment_versions`	object[]	A segmented version of this source.
`data.document.segment_versions[].version_id`	string	Segment version ID.
`data.document.segment_versions[].current`	boolean	Whether it is the current version.
`data.document.segments`	object[]	Segmentation in the current version.
`data.document.segments[].segment_id`	string	Segment ID.
`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": "ErrParamInvalid",
  "msg": "invalid segment version baseline",
  "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 or source does not exist or is not visible to the current caller.	Reread source list to confirm 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 generate the initial segment.	Keep the desensitized response information and try again.

Follow-up operations¶

Query document details Confirm the imported segmented version.

Last updated on Sep 15, 2026