# Compose and maintain a segment
Use the selected channel's MANAGE_SEGMENT permission. Source screen editors are modals on the segments list, so every operation uses that one actual console destination.
1. [Read segments](../tools/publ_segments_get.md). Use list creationRevision for create, or a selected non-preset detail revision for update/delete. A numeric row id or title cannot replace distinctId.
2. [Discover options](../tools/publ_segment_options.md) through majors → subjects → items → condition. Copy actual classification values, evaluation type, release status and source input requirements. No all-user default is inserted.
3. For entity conditions, [read target options](../tools/publ_segment_entities.md) and retain observed distinctIds. The definition determines the target and multiplicity. Nested installed-feature selectors remain unsupported.
4. Compose explicit include/exclude groups using [AND/OR rules and value bounds](../tools/publ_segment_preview.md#condition-input). [Preview](../tools/publ_segment_preview.md) performs read-only POSTs when needed; mutable conditions return unavailable count rather than zero.
5. [Apply](../tools/publ_segment_apply.md) a dry run, inspect its intended body, then use the same original requestId/input with dryRun:false if that save is authorized. Replacement conditions replace both trees. Title-only update preserves them. Creation uses explicit title and conditions.
6. [Delete](../tools/publ_segment_delete.md) only the observed non-preset target when requested, with DELETE_SEGMENT and a fresh detail revision. It is irreversible and has no automatic restoration.
Read a selected target:
```json
{"channelCode":"selected-channel-code","view":{"kind":"detail","distinctId":"observed-segment"}}
```
Prepare a title-only change without saving:
```json
{"channelCode":"selected-channel-code","action":"update","distinctId":"observed-segment","requestId":"segment-rename-001","expectedRevision":"0000000000000000000000000000000000000000000000000000000000000000","settings":{"title":"Updated audience"},"dryRun":true}
```
Use the actual returned revision, not the placeholder. Dry run reads current data; entity composition can perform a read-only resolver POST, and save does not calculate a count. Entity resolution alone accepts 200/201, receipt row IDs alone normalize canonical safe decimal strings, and standalone null descriptions are preserved. Definition/option metadata and nondeleted selected entity metadata are composed explicitly and remain subject to full-tree equality. A source effect may exist even when the method cannot confirm completion.
## Saved work and recovery
Keep the same connection, selected channel, job storage, requestId and original input. [Task status](../tools/publ_task_status.md) checks history and access without advancing business work. [Task resume](../tools/publ_task_resume.md) may advance an untouched prepared operation; it never resends write-sent. There is no background completion implied by pending.
```json
{"taskId":"segment-rename-001","taskType":"segment"}
```
- prepared: guards may still allow the original first write. Changed context, detail, inventory or definitions/entities prevents it.
- write-sent: reconciliation only. Update uses repeated full detail; delete requires known absence and stable preservation of remaining inventory. Creation requires its durably saved returned identity. Lost identity is not adopted by title or list differences.
- done: status/replay/resume returns historical:true, storedCompletion:true, confirmed:false and fullReadbackVerified:false. The history stays immutable; use a fresh get for current state.
Fresh completion returns confirmed:true/fullReadbackVerified:true but atomicSnapshot:false/memberEligibilityVerified:false. acknowledged records validated save identity or accepted delete transport; writesPerformed is false for prepared/no-op, true after acknowledgement, otherwise null. Read lastResult/outcome and journalPersistence together. A save-sent failure is unknown unless explicitly rejected. Never use a new request ID to bypass an uncertain earlier write.
Stored trees, count results and preserved configuration do not prove individual membership, benefit issuance, campaign effects, visitor behavior or hosted-client operation. [Promotion campaigns](promotion-campaigns.md) and [Discounts](discounts.md) keep their separate permissions and human financial boundaries.
## Current page selection
The standalone list defaults to page1/limit15. A condition's flat entity selector
defaults to page1/limit100, matching the source modal; explicit15/30/50/100 still
work in both. segments_get list results include their parsed view and preserve
page, size and search in the single returned console address. Detail and entity
selector results open the actual parent segments list. The source opens their
editors locally; a link cannot restore the selected modal or its private search.
SEGMENT_PAGE_OUT_OF_RANGE and SEGMENT_ENTITY_PAGE_OUT_OF_RANGE mean that the requested page exceeds the observed total. Explicitly request page1 again instead of treating that result as an empty audience or product inventory. A valid empty first page still succeeds.
## Oversized responses and recovery
Current segment observations read at most2MiB of UTF-8 JSON per response, including
list/detail, condition options, entity selection/resolution and count preview.
UPSTREAM_RESPONSE_TOO_LARGE means the response cannot be verified within that
bridge limit. It does not mean an audience is empty or a selected item is absent.
For a list, an explicitly smaller supported page may help; a large single record
or catalogue still needs inspection in the console. No silent truncation occurs.
If apply/delete already sent its effect, a subsequent oversized read leaves the
same task pending with unknown outcome. Keep its original taskId/requestId and
input. Use status/resume for that task; never issue a new save or delete to bypass
the failed read. Resume verifies current state without replaying the sent effect.
This response bound is a bridge limit, not a promise about source payload size.
## Distinguish selectable items
Current segment_entities includes sourceDetails for each row, in addition to the
observed distinctId and title. Use the relevant alias, product type, activation or
public status, source price, expiry, related count, discount code or conversion
keyword to distinguish items with the same title. Fields vary with the source
selector; a missing or null field is unknown, not zero or inactive. Keep the actual
returned distinctId for selection. These details do not grant purchase eligibility.
Prices retain the returned amount string and currency, including CP. Point amounts
retain source units; the tool does not guess a branding ratio, base currency or
localized display value. Dates and codes stay literal. Image references are not
fetched. If a used field is malformed, SEGMENT_ENTITY_DETAILS_UNVERIFIED withholds
the rows; if a detail changes between reads, SEGMENT_ENTITIES_CHANGED requires a
fresh observation. Other-target and unknown fields are omitted. Save still resolves
the selected IDs independently and does not copy these display details into its
condition metadata.
