Manage segments and processing tasks

Maintain the current segment snapshot of a knowledge-base data source, and query or reconcile data-processing tasks.

Prerequisites

Prepare credentials that can access the target workspace and IDs for the target knowledge base and data source. For service endpoints, authentication, and general request formats, see Prepare to call an API.

Before starting, confirm that the source was added to the knowledge base. Segment writes require a file source with kb_file_id and an available vector index. Table sources do not support segment writes.

Call sequence

  1. List data-processing tasks to check source processing, then query document details to obtain the current segments and data.etag.

  2. To create, update, enable, disable, or delete a segment, pass the ETag in if_match or the If-Match header. A nonempty body value takes precedence.

  3. After a successful change, use data.document.etag for the next operation. On 409 with ErrConflict, reread the snapshot and review the intended change before submitting again.

  4. To recompute current segment vectors, call revectorization and receive the document snapshot after the write. For inconsistent processing task state, reconcile tasks and query them again to confirm the result.

API operations

Manage current segments

What you need to do

API operation

Use it when

Create a segment

Create a segment

You identified the data source and segment content.

Update a segment

Update a segment

You have a target segment ID and need to modify content or configuration.

Enable or disable a segment

Enable or disable a segment

Change whether a segment participates in current use.

Delete a segment

Delete a segment

Confirm impact and conditions on the action page before deletion.

Process and reprocess data

What you need to do

API operation

Use it when

Query data-processing tasks

List data-processing tasks

View processing tasks and confirm later results.

Reconcile data-processing tasks

Reconcile processing task status

Reconcile processing tasks for a target data source.

Re-vectorize data

Re-vectorize a data source

Re-vectorize the target data source.

Confirm the result

After reconciling tasks, list data-processing tasks to inspect the target task. Segment writes and revectorization return a complete document snapshot. Query document details to inspect content and enabled status.

Limitations and notes

Deleting or disabling a segment changes retrieval results. Deletion cannot be undone, and at least one segment must remain. The details response’s next_cursor reads later segment pages; its ETag controls writes to the entire current snapshot.

The old bulk import and version-switching APIs have been removed. Creating a segment handles one segment per call; multiple calls do not preserve bulk import atomicity. Enabling or disabling a segment does not restore historical content.

Next steps

Last updated on