Create segments¶

Creates a segment in the source’s current segment version. A new text, OCR, or image description segment can be provided by source content.

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

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" \
  -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>,
    "level": "chunk",
    "content": "<SEGMENT_CONTENT>"
  }'

Parameter reference

Path parameters

Parameters	Type	Description
`model_id`	integer	Knowledge base ID.
`source_row_id`	string	Source record ID.

Request body

Commit source’s current version baseline and staging content.

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.
`level`	string	No	Segment level.
`content`	string	No	Text segment content.
`ocr_text`	string	No	OCR recognized text.
`image_description`	string	No	Image content description.
`image_file_id`	string	No	The associated image file ID.
`page_image_file_id`	string	No	The associated page image file ID.
`bbox`	JSON	No	Boundary information for the segment in the original content.
`metadata`	JSON	No	Additional metadata.

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
      },
      "segment_status": {
        "available": true,
        "total": 3
      },
      "segment_versions": [
        {
          "version_id": "ver_03",
          "current": true,
          "chunk_count": 3
        }
      ],
      "segments": [
        {
          "segment_id": "seg_03",
          "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 source document after writing.
`data.document.source.row_id`	string	Source record ID.
`data.document.segment_status`	object	Current segment availability status and total number.
`data.document.segment_versions[].version_id`	string	New or updated segment version ID.
`data.document.segment_versions[].current`	boolean	Whether it is the current segmented version.
`data.document.segments[].segment_id`	string	New segment ID.
`data.document.segments[].level`	string	Segment level.
`data.document.segments[].content`	string	Segmented text; may be omitted if content is not returned.
`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 create the segment.	Keep the desensitized response information and try again.

Follow-up operations¶

Query document details confirms that the new segment has taken effect.

Last updated on Sep 15, 2026