> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/api-reference/more-products-apis/feature-management-and-experimentation/segments.md).

# Segments

Manage workspace-scoped STANDARD, LARGE, and RULE\_BASED segment metadata and lifecycle.

## List Segments

> Returns a paginated list of Segments of one kind. \`segment\_type\` is required (\`400\` if\
> omitted). Defaults to active segments (\`status\` defaults to \`\[ACTIVE]\`). More than one\
> \`status\` returns \`400\`. Sorted by name ascending.<br>

```json
{"openapi":"3.0.3","info":{"title":"Harness Feature Management & Experimentation API","version":"4.0.0"},"tags":[{"name":"Segments","description":"Manage workspace-scoped STANDARD, LARGE, and RULE_BASED segment metadata and lifecycle."}],"servers":[{"url":"https://app.harness.io/fme/api","description":"Harness SaaS (production)"},{"url":"https://app3.harness.io/fme/api","description":"Harness SaaS (US-3)"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Harness Service Account Token (SAT) or Personal Access Token (PAT).\nGenerate tokens in Harness under Account Settings → Access Management.\n"}},"parameters":{"AccountId":{"name":"account_id","in":"query","required":true,"description":"Harness account identifier. Required on all endpoints.","schema":{"type":"string","pattern":"^[-_A-Za-z0-9]+$","maxLength":128}},"OrganizationIdentifier":{"name":"organization_identifier","in":"query","required":true,"description":"Harness organization identifier.","schema":{"type":"string","pattern":"^[-_A-Za-z0-9]+$","maxLength":128}},"ProjectIdentifier":{"name":"project_identifier","in":"query","required":true,"description":"Harness project identifier.","schema":{"type":"string","pattern":"^[-_A-Za-z0-9]+$","maxLength":128}},"PaginationLimitParam":{"name":"limit","in":"query","required":false,"description":"Number of items to return per page. Defaults to 100, maximum 100.","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}},"PaginationOffsetParam":{"name":"offset","in":"query","required":false,"description":"Number of items to skip before the first returned result. Defaults to 0.","schema":{"type":"integer","minimum":0,"default":0}},"SegmentType":{"name":"segment_type","in":"query","required":true,"description":"Segment kind (`STANDARD`, `LARGE`, or `RULE_BASED`). Same values as JSON `segmentType`.\nOmitting or sending an unknown value returns `400`. Name lookup and list are always a\nsingle kind.\n","schema":{"$ref":"#/components/schemas/SegmentKind"}}},"schemas":{"SegmentKind":{"type":"string","enum":["STANDARD","LARGE","RULE_BASED"],"description":"Kind of segment (`STANDARD`, `LARGE`, or `RULE_BASED`). Distinct from resource `type`\n(`SEGMENT`).\n"},"SegmentListResponse":{"type":"object","description":"Paginated list of Segments matching the query.","required":["data","limit","offset","totalCount"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Segment"}},"limit":{"type":"integer","description":"The page size used for this response."},"offset":{"type":"integer","description":"The number of items skipped before the first result."},"totalCount":{"type":"integer","description":"Total number of segments matching the query."}}},"Segment":{"type":"object","description":"A workspace-scoped Segment metadata entity (`STANDARD`, `LARGE`, or `RULE_BASED`).","required":["id","name","trafficType","createdAt","status","tags","owners","segmentType"],"properties":{"id":{"type":"string","format":"uuid","description":"Unique system-assigned identifier for the segment."},"name":{"type":"string","description":"Immutable after creation. Unique among active STANDARD and LARGE names in the project.\nIf rule-based segments are enabled for the account, the name must also be unique\nagainst active RULE_BASED names. Resolve with path `segment-name` plus query\n`segment_type`.\n"},"description":{"type":"string","nullable":true,"description":"Human-readable description of this segment."},"trafficType":{"allOf":[{"$ref":"#/components/schemas/NamedReference"}],"description":"Reference to the traffic type used to bucket users."},"createdAt":{"type":"string","format":"date-time","description":"ISO-8601 timestamp when the segment was created."},"status":{"type":"string","enum":["ACTIVE","ARCHIVED"],"description":"Lifecycle status of the segment.\n- `ACTIVE` — segment is live.\n- `ARCHIVED` — segment is no longer active (soft-deleted).\n"},"tags":{"type":"array","description":"Tags associated with this segment.","items":{"$ref":"#/components/schemas/NamedReference"}},"owners":{"type":"array","description":"Users or teams that own this segment. `USER` owners include `email`; `GROUP` owners do\nnot.\n","items":{"$ref":"#/components/schemas/OwnerReference"}},"segmentType":{"$ref":"#/components/schemas/SegmentKind"}}},"NamedReference":{"type":"object","description":"Generic reference to another resource, returned in responses. `id` is the stable\npublic identifier and `name` is the human-readable label.\n","required":["id","name"],"properties":{"id":{"type":"string","description":"Identifier of the referenced resource."},"name":{"type":"string","description":"Human-readable name of the referenced resource."}}},"OwnerReference":{"type":"object","description":"Reference to an owner (user or group), returned in responses. Extends the generic reference\nwith an optional `email`: a `USER` owner MAY carry `email` where the resource populates it;\na `GROUP` owner never has one. Use `id` for subsequent API calls; `name`/`email` are\ninformational (they let clients that keyed on a user's email at write time correlate the\nresponse without a lookup). Shared across FME v4 resources that expose owners.\n","required":["id","type","name"],"properties":{"id":{"type":"string","description":"Identifier of the owner — the Harness user id (for `USER`) or group id (for `GROUP`)."},"type":{"type":"string","enum":["USER","GROUP"],"description":"Owner kind."},"name":{"type":"string","description":"Human-readable display name of the user or group."},"email":{"type":"string","format":"email","nullable":true,"description":"Email address of the owner. Optionally populated for `USER` owners where the resource\nsupports it; `null`/absent for `GROUP` owners and for resources that do not return it.\n"}}},"ErrorResponse":{"type":"object","description":"Standard error response following RFC 7807 Problem Details format (Harness ADR 57).\n","required":["type","status","title","errorType"],"properties":{"type":{"type":"string","format":"uri","description":"URI reference to documentation for this error type."},"status":{"type":"integer","description":"HTTP status code."},"title":{"type":"string","description":"Short human-readable summary of the problem."},"errorType":{"type":"string","description":"Machine-readable error type identifier."},"detail":{"type":"string","description":"Detailed human-readable explanation specific to this occurrence."},"instance":{"type":"string","description":"URI reference identifying the specific occurrence (usually the request path)."},"errors":{"type":"array","description":"List of specific sub-errors (useful for multi-field validation failures). Governance\npolicy failures are also surfaced here — each failing policy is reported as an entry\nwith `errorType: \"governancePolicy\"` — rather than in a separate top-level field.\n","items":{"$ref":"#/components/schemas/ErrorDetail"}}}},"ErrorDetail":{"type":"object","description":"Details about a single sub-error.","required":["errorType","title"],"properties":{"errorType":{"type":"string","description":"Machine-readable error type for this specific error."},"title":{"type":"string","description":"Short summary of this specific error."},"detail":{"type":"string","description":"Detailed explanation of this specific error."},"field":{"type":"string","description":"Name of the request field this error applies to, when the error is field-specific\n(for example a validation failure). Omitted for errors not tied to a single field.\n"}}}},"responses":{"BadRequest":{"description":"Bad Request — validation errors or invalid state transition.\n","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Unauthorized — the request is missing a valid API key, or the key has expired.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Forbidden":{"description":"Forbidden — the caller is authenticated but not permitted to perform this operation.\nReturned when the API can deny the operation without leaking whether a resource exists,\nsuch as create, or write operations where the caller can already read the resource. When\nreturning `403` would reveal resource existence, the API returns `404` instead.\n\nEnvironment-scoped mutations that require approval also return `403`.\n","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"TooManyRequests":{"description":"Too Many Requests — the caller has exceeded the rate limit for this endpoint.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"InternalServerError":{"description":"Internal Server Error — an unexpected error occurred while processing the request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/v4/segments":{"get":{"tags":["Segments"],"operationId":"listSegments","summary":"List Segments","description":"Returns a paginated list of Segments of one kind. `segment_type` is required (`400` if\nomitted). Defaults to active segments (`status` defaults to `[ACTIVE]`). More than one\n`status` returns `400`. Sorted by name ascending.\n","parameters":[{"$ref":"#/components/parameters/AccountId"},{"$ref":"#/components/parameters/OrganizationIdentifier"},{"$ref":"#/components/parameters/ProjectIdentifier"},{"$ref":"#/components/parameters/PaginationLimitParam"},{"$ref":"#/components/parameters/PaginationOffsetParam"},{"$ref":"#/components/parameters/SegmentType"},{"name":"status","in":"query","required":false,"description":"Filter by lifecycle status. Defaults to `[ACTIVE]`. A single value only; more than one\nreturns `400`.\n","schema":{"type":"array","maxItems":1,"items":{"type":"string","enum":["ACTIVE","ARCHIVED"]},"default":["ACTIVE"]},"style":"form","explode":true}],"responses":{"200":{"description":"OK — paginated list of segments returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SegmentListResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## Create a Segment

> Creates a Segment. JSON \`segmentType\` is required. Creating \`RULE\_BASED\` when the account\
> cannot use rule-based segments returns \`400\`.<br>

```json
{"openapi":"3.0.3","info":{"title":"Harness Feature Management & Experimentation API","version":"4.0.0"},"tags":[{"name":"Segments","description":"Manage workspace-scoped STANDARD, LARGE, and RULE_BASED segment metadata and lifecycle."}],"servers":[{"url":"https://app.harness.io/fme/api","description":"Harness SaaS (production)"},{"url":"https://app3.harness.io/fme/api","description":"Harness SaaS (US-3)"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Harness Service Account Token (SAT) or Personal Access Token (PAT).\nGenerate tokens in Harness under Account Settings → Access Management.\n"}},"parameters":{"AccountId":{"name":"account_id","in":"query","required":true,"description":"Harness account identifier. Required on all endpoints.","schema":{"type":"string","pattern":"^[-_A-Za-z0-9]+$","maxLength":128}},"OrganizationIdentifier":{"name":"organization_identifier","in":"query","required":true,"description":"Harness organization identifier.","schema":{"type":"string","pattern":"^[-_A-Za-z0-9]+$","maxLength":128}},"ProjectIdentifier":{"name":"project_identifier","in":"query","required":true,"description":"Harness project identifier.","schema":{"type":"string","pattern":"^[-_A-Za-z0-9]+$","maxLength":128}}},"schemas":{"CreateSegmentRequest":{"type":"object","description":"Request body for creating a Segment. Same fields for every `segmentType`.","required":["name","trafficType","segmentType"],"properties":{"name":{"type":"string","pattern":"^[A-Za-z][-_A-Za-z0-9]*$","maxLength":100,"description":"Unique among active STANDARD and LARGE names in the project. Immutable after creation.\nIf rule-based segments are enabled for the account, the name must also be unique\nagainst active RULE_BASED names.\n"},"description":{"type":"string","description":"Human-readable description of this segment."},"trafficType":{"type":"string","description":"Traffic type used to bucket users, identified by its name (for example `user` or\n`account`). Immutable after creation.\n"},"tags":{"type":"array","description":"Initial tags to associate with the segment.","items":{"$ref":"#/components/schemas/TagReferenceInput"}},"owners":{"type":"array","description":"Initial owners (users or teams) for this segment. If omitted or empty, the project's\ndefault admin team is assigned.\n","items":{"$ref":"#/components/schemas/OwnerReferenceInput"}},"segmentType":{"$ref":"#/components/schemas/SegmentKind"}}},"TagReferenceInput":{"type":"object","description":"Tag input used in request bodies. Identified by `name`.","required":["name"],"properties":{"name":{"type":"string","description":"Tag name."}}},"OwnerReferenceInput":{"oneOf":[{"$ref":"#/components/schemas/UserOwnerReferenceInput"},{"$ref":"#/components/schemas/GroupOwnerReferenceInput"}],"discriminator":{"propertyName":"type","mapping":{"USER":"#/components/schemas/UserOwnerReferenceInput","GROUP":"#/components/schemas/GroupOwnerReferenceInput"}},"description":"Owner input. Use `USER` for users and `GROUP` for groups."},"UserOwnerReferenceInput":{"type":"object","description":"User owner input. Prefer `email`; `id` is also accepted for compatibility when the caller\nalready has the Harness user id.\n","required":["type"],"anyOf":[{"required":["email"]},{"required":["id"]}],"properties":{"type":{"type":"string","enum":["USER"],"description":"Owner type discriminator. Always `USER`."},"id":{"type":"string","description":"Harness user id."},"email":{"type":"string","format":"email","description":"User email address."}}},"GroupOwnerReferenceInput":{"type":"object","description":"Group owner input.","required":["type","identifier"],"properties":{"type":{"type":"string","enum":["GROUP"],"description":"Owner type discriminator. Always `GROUP`."},"identifier":{"type":"string","description":"Group identifier."}}},"SegmentKind":{"type":"string","enum":["STANDARD","LARGE","RULE_BASED"],"description":"Kind of segment (`STANDARD`, `LARGE`, or `RULE_BASED`). Distinct from resource `type`\n(`SEGMENT`).\n"},"SegmentResponse":{"type":"object","description":"Mutation response (create, update): entity plus OPA governance.\n","required":["entity","governance"],"properties":{"entity":{"$ref":"#/components/schemas/Segment"},"governance":{"allOf":[{"$ref":"#/components/schemas/GovernanceResult"}],"description":"OPA governance result for the mutation."}}},"Segment":{"type":"object","description":"A workspace-scoped Segment metadata entity (`STANDARD`, `LARGE`, or `RULE_BASED`).","required":["id","name","trafficType","createdAt","status","tags","owners","segmentType"],"properties":{"id":{"type":"string","format":"uuid","description":"Unique system-assigned identifier for the segment."},"name":{"type":"string","description":"Immutable after creation. Unique among active STANDARD and LARGE names in the project.\nIf rule-based segments are enabled for the account, the name must also be unique\nagainst active RULE_BASED names. Resolve with path `segment-name` plus query\n`segment_type`.\n"},"description":{"type":"string","nullable":true,"description":"Human-readable description of this segment."},"trafficType":{"allOf":[{"$ref":"#/components/schemas/NamedReference"}],"description":"Reference to the traffic type used to bucket users."},"createdAt":{"type":"string","format":"date-time","description":"ISO-8601 timestamp when the segment was created."},"status":{"type":"string","enum":["ACTIVE","ARCHIVED"],"description":"Lifecycle status of the segment.\n- `ACTIVE` — segment is live.\n- `ARCHIVED` — segment is no longer active (soft-deleted).\n"},"tags":{"type":"array","description":"Tags associated with this segment.","items":{"$ref":"#/components/schemas/NamedReference"}},"owners":{"type":"array","description":"Users or teams that own this segment. `USER` owners include `email`; `GROUP` owners do\nnot.\n","items":{"$ref":"#/components/schemas/OwnerReference"}},"segmentType":{"$ref":"#/components/schemas/SegmentKind"}}},"NamedReference":{"type":"object","description":"Generic reference to another resource, returned in responses. `id` is the stable\npublic identifier and `name` is the human-readable label.\n","required":["id","name"],"properties":{"id":{"type":"string","description":"Identifier of the referenced resource."},"name":{"type":"string","description":"Human-readable name of the referenced resource."}}},"OwnerReference":{"type":"object","description":"Reference to an owner (user or group), returned in responses. Extends the generic reference\nwith an optional `email`: a `USER` owner MAY carry `email` where the resource populates it;\na `GROUP` owner never has one. Use `id` for subsequent API calls; `name`/`email` are\ninformational (they let clients that keyed on a user's email at write time correlate the\nresponse without a lookup). Shared across FME v4 resources that expose owners.\n","required":["id","type","name"],"properties":{"id":{"type":"string","description":"Identifier of the owner — the Harness user id (for `USER`) or group id (for `GROUP`)."},"type":{"type":"string","enum":["USER","GROUP"],"description":"Owner kind."},"name":{"type":"string","description":"Human-readable display name of the user or group."},"email":{"type":"string","format":"email","nullable":true,"description":"Email address of the owner. Optionally populated for `USER` owners where the resource\nsupports it; `null`/absent for `GROUP` owners and for resources that do not return it.\n"}}},"GovernanceResult":{"type":"object","description":"OPA policy evaluation result for the operation. `PASS`, `WARNING`, and `ERROR` mean\ngovernance ran; `NONE` means governance was not evaluated (for example off or not linked).\n","required":["status","details"],"properties":{"status":{"type":"string","enum":["PASS","WARNING","ERROR","NONE"],"description":"Overall governance result. `NONE` when governance did not run; otherwise the aggregate\nacross evaluated policies.\n"},"details":{"type":"array","description":"Per-policy results. Empty array when all policies pass cleanly or when status is `NONE`.","items":{"$ref":"#/components/schemas/GovernancePolicyDetail"}}}},"GovernancePolicyDetail":{"type":"object","description":"Per-policy OPA evaluation result.","required":["policyName","status","message"],"properties":{"policyName":{"type":"string","description":"Name of the OPA policy that was evaluated."},"status":{"type":"string","enum":["PASS","WARNING","ERROR"],"description":"Result of evaluating this specific policy."},"message":{"type":"string","description":"Human-readable explanation of the policy result."}}},"ErrorResponse":{"type":"object","description":"Standard error response following RFC 7807 Problem Details format (Harness ADR 57).\n","required":["type","status","title","errorType"],"properties":{"type":{"type":"string","format":"uri","description":"URI reference to documentation for this error type."},"status":{"type":"integer","description":"HTTP status code."},"title":{"type":"string","description":"Short human-readable summary of the problem."},"errorType":{"type":"string","description":"Machine-readable error type identifier."},"detail":{"type":"string","description":"Detailed human-readable explanation specific to this occurrence."},"instance":{"type":"string","description":"URI reference identifying the specific occurrence (usually the request path)."},"errors":{"type":"array","description":"List of specific sub-errors (useful for multi-field validation failures). Governance\npolicy failures are also surfaced here — each failing policy is reported as an entry\nwith `errorType: \"governancePolicy\"` — rather than in a separate top-level field.\n","items":{"$ref":"#/components/schemas/ErrorDetail"}}}},"ErrorDetail":{"type":"object","description":"Details about a single sub-error.","required":["errorType","title"],"properties":{"errorType":{"type":"string","description":"Machine-readable error type for this specific error."},"title":{"type":"string","description":"Short summary of this specific error."},"detail":{"type":"string","description":"Detailed explanation of this specific error."},"field":{"type":"string","description":"Name of the request field this error applies to, when the error is field-specific\n(for example a validation failure). Omitted for errors not tied to a single field.\n"}}}},"responses":{"BadRequest":{"description":"Bad Request — validation errors or invalid state transition.\n","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Unauthorized — the request is missing a valid API key, or the key has expired.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Forbidden":{"description":"Forbidden — the caller is authenticated but not permitted to perform this operation.\nReturned when the API can deny the operation without leaking whether a resource exists,\nsuch as create, or write operations where the caller can already read the resource. When\nreturning `403` would reveal resource existence, the API returns `404` instead.\n\nEnvironment-scoped mutations that require approval also return `403`.\n","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Conflict":{"description":"Conflict — a resource with this identifier already exists, the operation conflicts with an\nopen change request, or the resource cannot be deleted/archived while dependents still\nexist. Discriminate with `errorType`: `resourceAlreadyExists`, `pendingChangeConflict`, or\n`hasDependents`. For `hasDependents`, `detail` is the archiver message when one is\navailable; otherwise `Resource has active dependents`.\n","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"UnprocessableEntity":{"description":"Unprocessable Content — OPA governance policy evaluation returned ERROR (`governanceError`).\nEach failing policy is listed in the `errors` array.\n","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"TooManyRequests":{"description":"Too Many Requests — the caller has exceeded the rate limit for this endpoint.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"InternalServerError":{"description":"Internal Server Error — an unexpected error occurred while processing the request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/v4/segments":{"post":{"tags":["Segments"],"operationId":"createSegment","summary":"Create a Segment","description":"Creates a Segment. JSON `segmentType` is required. Creating `RULE_BASED` when the account\ncannot use rule-based segments returns `400`.\n","parameters":[{"$ref":"#/components/parameters/AccountId"},{"$ref":"#/components/parameters/OrganizationIdentifier"},{"$ref":"#/components/parameters/ProjectIdentifier"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSegmentRequest"}}}},"responses":{"201":{"description":"Created — the segment was successfully created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SegmentResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## Get a Segment

> Active segment by name and \`segment\_type\`. Omitting \`segment\_type\` returns \`400\`.\
> ARCHIVED names return \`404\`; use LIST with \`status=ARCHIVED\` to discover them.<br>

```json
{"openapi":"3.0.3","info":{"title":"Harness Feature Management & Experimentation API","version":"4.0.0"},"tags":[{"name":"Segments","description":"Manage workspace-scoped STANDARD, LARGE, and RULE_BASED segment metadata and lifecycle."}],"servers":[{"url":"https://app.harness.io/fme/api","description":"Harness SaaS (production)"},{"url":"https://app3.harness.io/fme/api","description":"Harness SaaS (US-3)"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Harness Service Account Token (SAT) or Personal Access Token (PAT).\nGenerate tokens in Harness under Account Settings → Access Management.\n"}},"parameters":{"SegmentName":{"name":"segment-name","in":"path","required":true,"description":"The unique name of the segment within the project. Names must begin with a letter and\nmay contain letters, numbers, underscores, and hyphens. Use the same value that was\nsupplied as `name` when the segment was created. System-assigned ids are not accepted.\n","schema":{"type":"string","pattern":"^[A-Za-z][-_A-Za-z0-9]*$","maxLength":100}},"SegmentType":{"name":"segment_type","in":"query","required":true,"description":"Segment kind (`STANDARD`, `LARGE`, or `RULE_BASED`). Same values as JSON `segmentType`.\nOmitting or sending an unknown value returns `400`. Name lookup and list are always a\nsingle kind.\n","schema":{"$ref":"#/components/schemas/SegmentKind"}},"AccountId":{"name":"account_id","in":"query","required":true,"description":"Harness account identifier. Required on all endpoints.","schema":{"type":"string","pattern":"^[-_A-Za-z0-9]+$","maxLength":128}},"OrganizationIdentifier":{"name":"organization_identifier","in":"query","required":true,"description":"Harness organization identifier.","schema":{"type":"string","pattern":"^[-_A-Za-z0-9]+$","maxLength":128}},"ProjectIdentifier":{"name":"project_identifier","in":"query","required":true,"description":"Harness project identifier.","schema":{"type":"string","pattern":"^[-_A-Za-z0-9]+$","maxLength":128}}},"schemas":{"SegmentKind":{"type":"string","enum":["STANDARD","LARGE","RULE_BASED"],"description":"Kind of segment (`STANDARD`, `LARGE`, or `RULE_BASED`). Distinct from resource `type`\n(`SEGMENT`).\n"},"Segment":{"type":"object","description":"A workspace-scoped Segment metadata entity (`STANDARD`, `LARGE`, or `RULE_BASED`).","required":["id","name","trafficType","createdAt","status","tags","owners","segmentType"],"properties":{"id":{"type":"string","format":"uuid","description":"Unique system-assigned identifier for the segment."},"name":{"type":"string","description":"Immutable after creation. Unique among active STANDARD and LARGE names in the project.\nIf rule-based segments are enabled for the account, the name must also be unique\nagainst active RULE_BASED names. Resolve with path `segment-name` plus query\n`segment_type`.\n"},"description":{"type":"string","nullable":true,"description":"Human-readable description of this segment."},"trafficType":{"allOf":[{"$ref":"#/components/schemas/NamedReference"}],"description":"Reference to the traffic type used to bucket users."},"createdAt":{"type":"string","format":"date-time","description":"ISO-8601 timestamp when the segment was created."},"status":{"type":"string","enum":["ACTIVE","ARCHIVED"],"description":"Lifecycle status of the segment.\n- `ACTIVE` — segment is live.\n- `ARCHIVED` — segment is no longer active (soft-deleted).\n"},"tags":{"type":"array","description":"Tags associated with this segment.","items":{"$ref":"#/components/schemas/NamedReference"}},"owners":{"type":"array","description":"Users or teams that own this segment. `USER` owners include `email`; `GROUP` owners do\nnot.\n","items":{"$ref":"#/components/schemas/OwnerReference"}},"segmentType":{"$ref":"#/components/schemas/SegmentKind"}}},"NamedReference":{"type":"object","description":"Generic reference to another resource, returned in responses. `id` is the stable\npublic identifier and `name` is the human-readable label.\n","required":["id","name"],"properties":{"id":{"type":"string","description":"Identifier of the referenced resource."},"name":{"type":"string","description":"Human-readable name of the referenced resource."}}},"OwnerReference":{"type":"object","description":"Reference to an owner (user or group), returned in responses. Extends the generic reference\nwith an optional `email`: a `USER` owner MAY carry `email` where the resource populates it;\na `GROUP` owner never has one. Use `id` for subsequent API calls; `name`/`email` are\ninformational (they let clients that keyed on a user's email at write time correlate the\nresponse without a lookup). Shared across FME v4 resources that expose owners.\n","required":["id","type","name"],"properties":{"id":{"type":"string","description":"Identifier of the owner — the Harness user id (for `USER`) or group id (for `GROUP`)."},"type":{"type":"string","enum":["USER","GROUP"],"description":"Owner kind."},"name":{"type":"string","description":"Human-readable display name of the user or group."},"email":{"type":"string","format":"email","nullable":true,"description":"Email address of the owner. Optionally populated for `USER` owners where the resource\nsupports it; `null`/absent for `GROUP` owners and for resources that do not return it.\n"}}},"ErrorResponse":{"type":"object","description":"Standard error response following RFC 7807 Problem Details format (Harness ADR 57).\n","required":["type","status","title","errorType"],"properties":{"type":{"type":"string","format":"uri","description":"URI reference to documentation for this error type."},"status":{"type":"integer","description":"HTTP status code."},"title":{"type":"string","description":"Short human-readable summary of the problem."},"errorType":{"type":"string","description":"Machine-readable error type identifier."},"detail":{"type":"string","description":"Detailed human-readable explanation specific to this occurrence."},"instance":{"type":"string","description":"URI reference identifying the specific occurrence (usually the request path)."},"errors":{"type":"array","description":"List of specific sub-errors (useful for multi-field validation failures). Governance\npolicy failures are also surfaced here — each failing policy is reported as an entry\nwith `errorType: \"governancePolicy\"` — rather than in a separate top-level field.\n","items":{"$ref":"#/components/schemas/ErrorDetail"}}}},"ErrorDetail":{"type":"object","description":"Details about a single sub-error.","required":["errorType","title"],"properties":{"errorType":{"type":"string","description":"Machine-readable error type for this specific error."},"title":{"type":"string","description":"Short summary of this specific error."},"detail":{"type":"string","description":"Detailed explanation of this specific error."},"field":{"type":"string","description":"Name of the request field this error applies to, when the error is field-specific\n(for example a validation failure). Omitted for errors not tied to a single field.\n"}}}},"responses":{"BadRequest":{"description":"Bad Request — validation errors or invalid state transition.\n","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Unauthorized — the request is missing a valid API key, or the key has expired.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFound":{"description":"Not Found — the requested resource does not exist. Also returned when the caller lacks\naccess to the resource (to avoid leaking resource existence).\n","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"TooManyRequests":{"description":"Too Many Requests — the caller has exceeded the rate limit for this endpoint.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"InternalServerError":{"description":"Internal Server Error — an unexpected error occurred while processing the request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/v4/segments/{segment-name}":{"get":{"tags":["Segments"],"operationId":"getSegment","summary":"Get a Segment","description":"Active segment by name and `segment_type`. Omitting `segment_type` returns `400`.\nARCHIVED names return `404`; use LIST with `status=ARCHIVED` to discover them.\n","parameters":[{"$ref":"#/components/parameters/SegmentName"},{"$ref":"#/components/parameters/SegmentType"},{"$ref":"#/components/parameters/AccountId"},{"$ref":"#/components/parameters/OrganizationIdentifier"},{"$ref":"#/components/parameters/ProjectIdentifier"}],"responses":{"200":{"description":"OK — segment returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Segment"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## Delete a Segment

> Archives a Segment of the given \`segment\_type\` (\`400\` if omitted). Returns the OPA\
> governance result for the operation. Already archived or missing names return \`404\`.\
> Active dependents return \`409\` (\`hasDependents\`).<br>

```json
{"openapi":"3.0.3","info":{"title":"Harness Feature Management & Experimentation API","version":"4.0.0"},"tags":[{"name":"Segments","description":"Manage workspace-scoped STANDARD, LARGE, and RULE_BASED segment metadata and lifecycle."}],"servers":[{"url":"https://app.harness.io/fme/api","description":"Harness SaaS (production)"},{"url":"https://app3.harness.io/fme/api","description":"Harness SaaS (US-3)"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Harness Service Account Token (SAT) or Personal Access Token (PAT).\nGenerate tokens in Harness under Account Settings → Access Management.\n"}},"parameters":{"SegmentName":{"name":"segment-name","in":"path","required":true,"description":"The unique name of the segment within the project. Names must begin with a letter and\nmay contain letters, numbers, underscores, and hyphens. Use the same value that was\nsupplied as `name` when the segment was created. System-assigned ids are not accepted.\n","schema":{"type":"string","pattern":"^[A-Za-z][-_A-Za-z0-9]*$","maxLength":100}},"SegmentType":{"name":"segment_type","in":"query","required":true,"description":"Segment kind (`STANDARD`, `LARGE`, or `RULE_BASED`). Same values as JSON `segmentType`.\nOmitting or sending an unknown value returns `400`. Name lookup and list are always a\nsingle kind.\n","schema":{"$ref":"#/components/schemas/SegmentKind"}},"AccountId":{"name":"account_id","in":"query","required":true,"description":"Harness account identifier. Required on all endpoints.","schema":{"type":"string","pattern":"^[-_A-Za-z0-9]+$","maxLength":128}},"OrganizationIdentifier":{"name":"organization_identifier","in":"query","required":true,"description":"Harness organization identifier.","schema":{"type":"string","pattern":"^[-_A-Za-z0-9]+$","maxLength":128}},"ProjectIdentifier":{"name":"project_identifier","in":"query","required":true,"description":"Harness project identifier.","schema":{"type":"string","pattern":"^[-_A-Za-z0-9]+$","maxLength":128}}},"schemas":{"SegmentKind":{"type":"string","enum":["STANDARD","LARGE","RULE_BASED"],"description":"Kind of segment (`STANDARD`, `LARGE`, or `RULE_BASED`). Distinct from resource `type`\n(`SEGMENT`).\n"},"DeleteResponse":{"type":"object","description":"Response envelope for delete operations. Contains only the OPA governance result — no\nentity is returned. Shared by all FME resources so delete responses are consistent.\n","required":["governance"],"properties":{"governance":{"allOf":[{"$ref":"#/components/schemas/GovernanceResult"}],"description":"OPA governance result for the delete operation."}}},"GovernanceResult":{"type":"object","description":"OPA policy evaluation result for the operation. `PASS`, `WARNING`, and `ERROR` mean\ngovernance ran; `NONE` means governance was not evaluated (for example off or not linked).\n","required":["status","details"],"properties":{"status":{"type":"string","enum":["PASS","WARNING","ERROR","NONE"],"description":"Overall governance result. `NONE` when governance did not run; otherwise the aggregate\nacross evaluated policies.\n"},"details":{"type":"array","description":"Per-policy results. Empty array when all policies pass cleanly or when status is `NONE`.","items":{"$ref":"#/components/schemas/GovernancePolicyDetail"}}}},"GovernancePolicyDetail":{"type":"object","description":"Per-policy OPA evaluation result.","required":["policyName","status","message"],"properties":{"policyName":{"type":"string","description":"Name of the OPA policy that was evaluated."},"status":{"type":"string","enum":["PASS","WARNING","ERROR"],"description":"Result of evaluating this specific policy."},"message":{"type":"string","description":"Human-readable explanation of the policy result."}}},"ErrorResponse":{"type":"object","description":"Standard error response following RFC 7807 Problem Details format (Harness ADR 57).\n","required":["type","status","title","errorType"],"properties":{"type":{"type":"string","format":"uri","description":"URI reference to documentation for this error type."},"status":{"type":"integer","description":"HTTP status code."},"title":{"type":"string","description":"Short human-readable summary of the problem."},"errorType":{"type":"string","description":"Machine-readable error type identifier."},"detail":{"type":"string","description":"Detailed human-readable explanation specific to this occurrence."},"instance":{"type":"string","description":"URI reference identifying the specific occurrence (usually the request path)."},"errors":{"type":"array","description":"List of specific sub-errors (useful for multi-field validation failures). Governance\npolicy failures are also surfaced here — each failing policy is reported as an entry\nwith `errorType: \"governancePolicy\"` — rather than in a separate top-level field.\n","items":{"$ref":"#/components/schemas/ErrorDetail"}}}},"ErrorDetail":{"type":"object","description":"Details about a single sub-error.","required":["errorType","title"],"properties":{"errorType":{"type":"string","description":"Machine-readable error type for this specific error."},"title":{"type":"string","description":"Short summary of this specific error."},"detail":{"type":"string","description":"Detailed explanation of this specific error."},"field":{"type":"string","description":"Name of the request field this error applies to, when the error is field-specific\n(for example a validation failure). Omitted for errors not tied to a single field.\n"}}}},"responses":{"BadRequest":{"description":"Bad Request — validation errors or invalid state transition.\n","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Unauthorized — the request is missing a valid API key, or the key has expired.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Forbidden":{"description":"Forbidden — the caller is authenticated but not permitted to perform this operation.\nReturned when the API can deny the operation without leaking whether a resource exists,\nsuch as create, or write operations where the caller can already read the resource. When\nreturning `403` would reveal resource existence, the API returns `404` instead.\n\nEnvironment-scoped mutations that require approval also return `403`.\n","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFound":{"description":"Not Found — the requested resource does not exist. Also returned when the caller lacks\naccess to the resource (to avoid leaking resource existence).\n","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Conflict":{"description":"Conflict — a resource with this identifier already exists, the operation conflicts with an\nopen change request, or the resource cannot be deleted/archived while dependents still\nexist. Discriminate with `errorType`: `resourceAlreadyExists`, `pendingChangeConflict`, or\n`hasDependents`. For `hasDependents`, `detail` is the archiver message when one is\navailable; otherwise `Resource has active dependents`.\n","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"UnprocessableEntity":{"description":"Unprocessable Content — OPA governance policy evaluation returned ERROR (`governanceError`).\nEach failing policy is listed in the `errors` array.\n","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"TooManyRequests":{"description":"Too Many Requests — the caller has exceeded the rate limit for this endpoint.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"InternalServerError":{"description":"Internal Server Error — an unexpected error occurred while processing the request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/v4/segments/{segment-name}":{"delete":{"tags":["Segments"],"operationId":"deleteSegment","summary":"Delete a Segment","description":"Archives a Segment of the given `segment_type` (`400` if omitted). Returns the OPA\ngovernance result for the operation. Already archived or missing names return `404`.\nActive dependents return `409` (`hasDependents`).\n","parameters":[{"$ref":"#/components/parameters/SegmentName"},{"$ref":"#/components/parameters/SegmentType"},{"$ref":"#/components/parameters/AccountId"},{"$ref":"#/components/parameters/OrganizationIdentifier"},{"$ref":"#/components/parameters/ProjectIdentifier"}],"responses":{"200":{"description":"OK — segment deleted. Returns the governance result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## Update a Segment (partial)

> Partially updates a Segment (RFC 7396). Omit = keep; JSON \`null\` clears \`description\`;\
> \`null\` or \`\[]\` clears \`tags\`/\`owners\`. \`segment\_type\` is required (\`400\` if omitted).\
> Already-archived segments return \`404\`. \`segmentType\` is not patchable.<br>

```json
{"openapi":"3.0.3","info":{"title":"Harness Feature Management & Experimentation API","version":"4.0.0"},"tags":[{"name":"Segments","description":"Manage workspace-scoped STANDARD, LARGE, and RULE_BASED segment metadata and lifecycle."}],"servers":[{"url":"https://app.harness.io/fme/api","description":"Harness SaaS (production)"},{"url":"https://app3.harness.io/fme/api","description":"Harness SaaS (US-3)"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Harness Service Account Token (SAT) or Personal Access Token (PAT).\nGenerate tokens in Harness under Account Settings → Access Management.\n"}},"parameters":{"SegmentName":{"name":"segment-name","in":"path","required":true,"description":"The unique name of the segment within the project. Names must begin with a letter and\nmay contain letters, numbers, underscores, and hyphens. Use the same value that was\nsupplied as `name` when the segment was created. System-assigned ids are not accepted.\n","schema":{"type":"string","pattern":"^[A-Za-z][-_A-Za-z0-9]*$","maxLength":100}},"SegmentType":{"name":"segment_type","in":"query","required":true,"description":"Segment kind (`STANDARD`, `LARGE`, or `RULE_BASED`). Same values as JSON `segmentType`.\nOmitting or sending an unknown value returns `400`. Name lookup and list are always a\nsingle kind.\n","schema":{"$ref":"#/components/schemas/SegmentKind"}},"AccountId":{"name":"account_id","in":"query","required":true,"description":"Harness account identifier. Required on all endpoints.","schema":{"type":"string","pattern":"^[-_A-Za-z0-9]+$","maxLength":128}},"OrganizationIdentifier":{"name":"organization_identifier","in":"query","required":true,"description":"Harness organization identifier.","schema":{"type":"string","pattern":"^[-_A-Za-z0-9]+$","maxLength":128}},"ProjectIdentifier":{"name":"project_identifier","in":"query","required":true,"description":"Harness project identifier.","schema":{"type":"string","pattern":"^[-_A-Za-z0-9]+$","maxLength":128}}},"schemas":{"SegmentKind":{"type":"string","enum":["STANDARD","LARGE","RULE_BASED"],"description":"Kind of segment (`STANDARD`, `LARGE`, or `RULE_BASED`). Distinct from resource `type`\n(`SEGMENT`).\n"},"UpdateSegmentRequest":{"type":"object","additionalProperties":false,"description":"JSON Merge Patch body (RFC 7396) for updating a Segment. All fields are optional. Omit a\nfield to leave it unchanged; send JSON `null` to clear `description`, or `null`/`[]` to clear\n`tags`/`owners`. Present array fields replace the list in full. Kind is selected by query\n`segment_type`. `segmentType` is not patchable. Unknown properties return `400`.\n","properties":{"description":{"type":"string","nullable":true,"description":"Updated human-readable description."},"tags":{"type":"array","nullable":true,"description":"Replacement tag list.","items":{"$ref":"#/components/schemas/TagReferenceInput"}},"owners":{"type":"array","nullable":true,"description":"Replacement owner list.","items":{"$ref":"#/components/schemas/OwnerReferenceInput"}}}},"TagReferenceInput":{"type":"object","description":"Tag input used in request bodies. Identified by `name`.","required":["name"],"properties":{"name":{"type":"string","description":"Tag name."}}},"OwnerReferenceInput":{"oneOf":[{"$ref":"#/components/schemas/UserOwnerReferenceInput"},{"$ref":"#/components/schemas/GroupOwnerReferenceInput"}],"discriminator":{"propertyName":"type","mapping":{"USER":"#/components/schemas/UserOwnerReferenceInput","GROUP":"#/components/schemas/GroupOwnerReferenceInput"}},"description":"Owner input. Use `USER` for users and `GROUP` for groups."},"UserOwnerReferenceInput":{"type":"object","description":"User owner input. Prefer `email`; `id` is also accepted for compatibility when the caller\nalready has the Harness user id.\n","required":["type"],"anyOf":[{"required":["email"]},{"required":["id"]}],"properties":{"type":{"type":"string","enum":["USER"],"description":"Owner type discriminator. Always `USER`."},"id":{"type":"string","description":"Harness user id."},"email":{"type":"string","format":"email","description":"User email address."}}},"GroupOwnerReferenceInput":{"type":"object","description":"Group owner input.","required":["type","identifier"],"properties":{"type":{"type":"string","enum":["GROUP"],"description":"Owner type discriminator. Always `GROUP`."},"identifier":{"type":"string","description":"Group identifier."}}},"SegmentResponse":{"type":"object","description":"Mutation response (create, update): entity plus OPA governance.\n","required":["entity","governance"],"properties":{"entity":{"$ref":"#/components/schemas/Segment"},"governance":{"allOf":[{"$ref":"#/components/schemas/GovernanceResult"}],"description":"OPA governance result for the mutation."}}},"Segment":{"type":"object","description":"A workspace-scoped Segment metadata entity (`STANDARD`, `LARGE`, or `RULE_BASED`).","required":["id","name","trafficType","createdAt","status","tags","owners","segmentType"],"properties":{"id":{"type":"string","format":"uuid","description":"Unique system-assigned identifier for the segment."},"name":{"type":"string","description":"Immutable after creation. Unique among active STANDARD and LARGE names in the project.\nIf rule-based segments are enabled for the account, the name must also be unique\nagainst active RULE_BASED names. Resolve with path `segment-name` plus query\n`segment_type`.\n"},"description":{"type":"string","nullable":true,"description":"Human-readable description of this segment."},"trafficType":{"allOf":[{"$ref":"#/components/schemas/NamedReference"}],"description":"Reference to the traffic type used to bucket users."},"createdAt":{"type":"string","format":"date-time","description":"ISO-8601 timestamp when the segment was created."},"status":{"type":"string","enum":["ACTIVE","ARCHIVED"],"description":"Lifecycle status of the segment.\n- `ACTIVE` — segment is live.\n- `ARCHIVED` — segment is no longer active (soft-deleted).\n"},"tags":{"type":"array","description":"Tags associated with this segment.","items":{"$ref":"#/components/schemas/NamedReference"}},"owners":{"type":"array","description":"Users or teams that own this segment. `USER` owners include `email`; `GROUP` owners do\nnot.\n","items":{"$ref":"#/components/schemas/OwnerReference"}},"segmentType":{"$ref":"#/components/schemas/SegmentKind"}}},"NamedReference":{"type":"object","description":"Generic reference to another resource, returned in responses. `id` is the stable\npublic identifier and `name` is the human-readable label.\n","required":["id","name"],"properties":{"id":{"type":"string","description":"Identifier of the referenced resource."},"name":{"type":"string","description":"Human-readable name of the referenced resource."}}},"OwnerReference":{"type":"object","description":"Reference to an owner (user or group), returned in responses. Extends the generic reference\nwith an optional `email`: a `USER` owner MAY carry `email` where the resource populates it;\na `GROUP` owner never has one. Use `id` for subsequent API calls; `name`/`email` are\ninformational (they let clients that keyed on a user's email at write time correlate the\nresponse without a lookup). Shared across FME v4 resources that expose owners.\n","required":["id","type","name"],"properties":{"id":{"type":"string","description":"Identifier of the owner — the Harness user id (for `USER`) or group id (for `GROUP`)."},"type":{"type":"string","enum":["USER","GROUP"],"description":"Owner kind."},"name":{"type":"string","description":"Human-readable display name of the user or group."},"email":{"type":"string","format":"email","nullable":true,"description":"Email address of the owner. Optionally populated for `USER` owners where the resource\nsupports it; `null`/absent for `GROUP` owners and for resources that do not return it.\n"}}},"GovernanceResult":{"type":"object","description":"OPA policy evaluation result for the operation. `PASS`, `WARNING`, and `ERROR` mean\ngovernance ran; `NONE` means governance was not evaluated (for example off or not linked).\n","required":["status","details"],"properties":{"status":{"type":"string","enum":["PASS","WARNING","ERROR","NONE"],"description":"Overall governance result. `NONE` when governance did not run; otherwise the aggregate\nacross evaluated policies.\n"},"details":{"type":"array","description":"Per-policy results. Empty array when all policies pass cleanly or when status is `NONE`.","items":{"$ref":"#/components/schemas/GovernancePolicyDetail"}}}},"GovernancePolicyDetail":{"type":"object","description":"Per-policy OPA evaluation result.","required":["policyName","status","message"],"properties":{"policyName":{"type":"string","description":"Name of the OPA policy that was evaluated."},"status":{"type":"string","enum":["PASS","WARNING","ERROR"],"description":"Result of evaluating this specific policy."},"message":{"type":"string","description":"Human-readable explanation of the policy result."}}},"ErrorResponse":{"type":"object","description":"Standard error response following RFC 7807 Problem Details format (Harness ADR 57).\n","required":["type","status","title","errorType"],"properties":{"type":{"type":"string","format":"uri","description":"URI reference to documentation for this error type."},"status":{"type":"integer","description":"HTTP status code."},"title":{"type":"string","description":"Short human-readable summary of the problem."},"errorType":{"type":"string","description":"Machine-readable error type identifier."},"detail":{"type":"string","description":"Detailed human-readable explanation specific to this occurrence."},"instance":{"type":"string","description":"URI reference identifying the specific occurrence (usually the request path)."},"errors":{"type":"array","description":"List of specific sub-errors (useful for multi-field validation failures). Governance\npolicy failures are also surfaced here — each failing policy is reported as an entry\nwith `errorType: \"governancePolicy\"` — rather than in a separate top-level field.\n","items":{"$ref":"#/components/schemas/ErrorDetail"}}}},"ErrorDetail":{"type":"object","description":"Details about a single sub-error.","required":["errorType","title"],"properties":{"errorType":{"type":"string","description":"Machine-readable error type for this specific error."},"title":{"type":"string","description":"Short summary of this specific error."},"detail":{"type":"string","description":"Detailed explanation of this specific error."},"field":{"type":"string","description":"Name of the request field this error applies to, when the error is field-specific\n(for example a validation failure). Omitted for errors not tied to a single field.\n"}}}},"responses":{"BadRequest":{"description":"Bad Request — validation errors or invalid state transition.\n","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Unauthorized — the request is missing a valid API key, or the key has expired.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Forbidden":{"description":"Forbidden — the caller is authenticated but not permitted to perform this operation.\nReturned when the API can deny the operation without leaking whether a resource exists,\nsuch as create, or write operations where the caller can already read the resource. When\nreturning `403` would reveal resource existence, the API returns `404` instead.\n\nEnvironment-scoped mutations that require approval also return `403`.\n","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFound":{"description":"Not Found — the requested resource does not exist. Also returned when the caller lacks\naccess to the resource (to avoid leaking resource existence).\n","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"UnprocessableEntity":{"description":"Unprocessable Content — OPA governance policy evaluation returned ERROR (`governanceError`).\nEach failing policy is listed in the `errors` array.\n","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"TooManyRequests":{"description":"Too Many Requests — the caller has exceeded the rate limit for this endpoint.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"InternalServerError":{"description":"Internal Server Error — an unexpected error occurred while processing the request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/v4/segments/{segment-name}":{"patch":{"tags":["Segments"],"operationId":"updateSegment","summary":"Update a Segment (partial)","description":"Partially updates a Segment (RFC 7396). Omit = keep; JSON `null` clears `description`;\n`null` or `[]` clears `tags`/`owners`. `segment_type` is required (`400` if omitted).\nAlready-archived segments return `404`. `segmentType` is not patchable.\n","parameters":[{"$ref":"#/components/parameters/SegmentName"},{"$ref":"#/components/parameters/SegmentType"},{"$ref":"#/components/parameters/AccountId"},{"$ref":"#/components/parameters/OrganizationIdentifier"},{"$ref":"#/components/parameters/ProjectIdentifier"}],"requestBody":{"required":true,"content":{"application/merge-patch+json":{"schema":{"$ref":"#/components/schemas/UpdateSegmentRequest"}}}},"responses":{"200":{"description":"OK — segment updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SegmentResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```
