# 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](../../api-call-basics.md).

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](../../../../reference/api/ai-studio/resource-center/knowledge-bases/list-data-processing-jobs.md) to check source processing, then [query document details](../../../../reference/api/ai-studio/resource-center/knowledge-bases/get-document.md) 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](../../../../reference/api/ai-studio/resource-center/knowledge-bases/create-segment.md) | You identified the data source and segment content. |
| Update a segment | [Update a segment](../../../../reference/api/ai-studio/resource-center/knowledge-bases/update-segment.md) | You have a target segment ID and need to modify content or configuration. |
| Enable or disable a segment | [Enable or disable a segment](../../../../reference/api/ai-studio/resource-center/knowledge-bases/set-segment-enabled.md) | Change whether a segment participates in current use. |
| Delete a segment | [Delete a segment](../../../../reference/api/ai-studio/resource-center/knowledge-bases/delete-segment.md) | 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](../../../../reference/api/ai-studio/resource-center/knowledge-bases/list-data-processing-jobs.md) | View processing tasks and confirm later results. |
| Reconcile data-processing tasks | [Reconcile processing task status](../../../../reference/api/ai-studio/resource-center/knowledge-bases/reconcile-data-processing-jobs.md) | Reconcile processing tasks for a target data source. |
| Re-vectorize data | [Re-vectorize a data source](../../../../reference/api/ai-studio/resource-center/knowledge-bases/revectorize-data-source.md) | Re-vectorize the target data source. |

## Confirm the result

After reconciling tasks, [list data-processing tasks](../../../../reference/api/ai-studio/resource-center/knowledge-bases/list-data-processing-jobs.md) to inspect the target task. Segment writes and revectorization return a complete document snapshot. [Query document details](../../../../reference/api/ai-studio/resource-center/knowledge-bases/get-document.md) 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

- [Manage data sources and documents](data-sources-documents.md)
- [Manage semantic entries](semantic-entries.md)