> 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/feature-flag-definitions.md).

# Feature Flag Definitions

Manage environment-specific feature flag definitions (treatments, traffic allocation, targeting).

## List Feature Flag Definitions

> Returns a paginated list of active Feature Flag Definitions across all environments for the\
> Feature Flag specified by \`feature\_flag\_name\`. Returns \`404\` if no Feature Flag with that\
> name exists in the project.<br>

```json
{"openapi":"3.0.3","info":{"title":"Harness Feature Management & Experimentation API","version":"4.0.0"},"tags":[{"name":"Feature Flag Definitions","description":"Manage environment-specific feature flag definitions (treatments, traffic allocation, targeting)."}],"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}}},"schemas":{"FeatureFlagDefinitionListResponse":{"type":"object","description":"Paginated list of active Feature Flag Definitions.","required":["data","limit","offset","totalCount"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FeatureFlagDefinition"}},"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 active feature flag definitions matching the query."}}},"FeatureFlagDefinition":{"type":"object","description":"An environment-specific Feature Flag Definition.","required":["id","featureFlag","environment","trafficType","isKilled","treatments","defaultTreatment","baselineTreatment","trafficAllocation","rules","defaultRule","createdAt","impressions"],"properties":{"id":{"type":"string","format":"uuid","description":"System-assigned identifier for this feature flag definition."},"featureFlag":{"allOf":[{"$ref":"#/components/schemas/NamedReference"}],"description":"Reference to the parent feature flag metadata."},"environment":{"allOf":[{"$ref":"#/components/schemas/NamedReference"}],"description":"Reference to the environment this definition is scoped to."},"trafficType":{"allOf":[{"$ref":"#/components/schemas/NamedReference"}],"description":"Reference to the traffic type used to bucket keys."},"isKilled":{"type":"boolean","readOnly":true,"description":"Whether the flag is killed in this environment. While killed, all traffic receives\n`defaultTreatment` regardless of rules. Response-only — use the dedicated kill/restore\nactions to change it.\n"},"treatments":{"type":"array","minItems":2,"description":"The treatments available for this flag in this environment.","items":{"$ref":"#/components/schemas/Treatment"}},"defaultTreatment":{"allOf":[{"$ref":"#/components/schemas/TreatmentName"}],"description":"Treatment served when the flag is killed, and to traffic outside `trafficAllocation`.\n"},"baselineTreatment":{"allOf":[{"$ref":"#/components/schemas/TreatmentName"}],"description":"Baseline treatment used as the control group for metrics calculations."},"trafficAllocation":{"type":"integer","format":"int32","minimum":0,"maximum":100,"description":"Percentage of total traffic that participates in this flag's evaluation. Traffic\noutside this allocation receives `defaultTreatment`.\n"},"rules":{"type":"array","description":"Ordered targeting rules. Empty means all traffic falls through to `defaultRule`.","items":{"$ref":"#/components/schemas/Rule"}},"defaultRule":{"type":"array","minItems":1,"description":"Distribution applied to in-allocation traffic that matches no targeting rule. Bucket\nsizes must sum to 100.\n","items":{"$ref":"#/components/schemas/Distribution"}},"flagSets":{"type":"array","description":"Flag sets associated with this definition. Empty means the definition belongs to no\nflag set. Assigned on create/PATCH; echoed on GET.\n","items":{"$ref":"#/components/schemas/FlagSetReference"}},"createdAt":{"type":"string","format":"date-time","description":"ISO-8601 timestamp when this definition was created."},"impressions":{"allOf":[{"$ref":"#/components/schemas/Impressions"}],"description":"Traffic/impression freshness data for this definition."}}},"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."}}},"Treatment":{"type":"object","description":"A single treatment (variation) of the feature flag in this environment.\n","required":["name"],"properties":{"name":{"allOf":[{"$ref":"#/components/schemas/TreatmentName"}],"description":"Treatment name. Must start with a letter or digit; remaining characters may be letters,\ndigits, hyphens, underscores, or periods. The reserved name `control` is not allowed.\n"},"description":{"type":"string","nullable":true,"description":"Optional description of this treatment."},"keys":{"type":"array","description":"Keys explicitly assigned to this treatment.","items":{"type":"string"}},"segments":{"type":"array","description":"Standard segment names assigned to this treatment.","items":{"type":"string","pattern":"^[A-Za-z][-_A-Za-z0-9]*$","maxLength":100}},"largeSegments":{"type":"array","description":"Large segment names assigned to this treatment.","items":{"type":"string","pattern":"^[A-Za-z][-_A-Za-z0-9]*$","maxLength":100}},"ruleBasedSegments":{"type":"array","description":"Rule-based segment names assigned to this treatment.","items":{"type":"string","pattern":"^[A-Za-z][-_A-Za-z0-9]*$","maxLength":100}},"configurations":{"type":"string","nullable":true,"description":"Dynamic configuration attached to this treatment, serialized as a JSON string.\n"}}},"TreatmentName":{"type":"string","pattern":"^[a-zA-Z0-9][-_\\.a-zA-Z0-9]*$","description":"Treatment name. Must start with a letter or digit; remaining characters may be letters,\ndigits, hyphens, underscores, or periods.\n"},"Rule":{"type":"object","description":"A targeting rule: a condition and the treatment buckets served on match.\n","required":["condition","buckets"],"properties":{"condition":{"$ref":"#/components/schemas/Condition"},"buckets":{"type":"array","minItems":1,"description":"Treatment buckets served when the condition matches. Sizes must sum to 100.\n","items":{"$ref":"#/components/schemas/Distribution"}}}},"Condition":{"type":"object","description":"The matching condition for a targeting rule. Only the `AND` combiner is supported — all\nmatchers must match. `OR` combination is not supported.\n","required":["combiner","matchers"],"properties":{"combiner":{"type":"string","enum":["AND"],"description":"Matcher combiner. Only `AND` is supported."},"matchers":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/Matcher"}}}},"Matcher":{"description":"A matcher within a targeting condition. Discriminated by `type` — each variant requires\nthe value field(s) that type evaluates. `negate` is optional on every variant (`true`\ninverts the result). `attribute` is required when the matcher evaluates a traffic-type\nattribute; omit it only for key-based list/string matchers (`IN_LIST_STRING`,\n`STARTS_WITH_STRING`, `ENDS_WITH_STRING`, `CONTAINS_STRING`, `MATCHES_STRING`).\n","oneOf":[{"$ref":"#/components/schemas/SegmentMatcher"},{"$ref":"#/components/schemas/SplitMatcher"},{"$ref":"#/components/schemas/BooleanMatcher"},{"$ref":"#/components/schemas/DateMatcher"},{"$ref":"#/components/schemas/BetweenDateMatcher"},{"$ref":"#/components/schemas/SetMatcher"},{"$ref":"#/components/schemas/NumberMatcher"},{"$ref":"#/components/schemas/BetweenNumberMatcher"},{"$ref":"#/components/schemas/InListStringMatcher"},{"$ref":"#/components/schemas/StringListMatcher"},{"$ref":"#/components/schemas/MatchesStringMatcher"},{"$ref":"#/components/schemas/SemverCompareMatcher"},{"$ref":"#/components/schemas/BetweenSemverMatcher"},{"$ref":"#/components/schemas/InListSemverMatcher"}],"discriminator":{"propertyName":"type","mapping":{"IN_SEGMENT":"#/components/schemas/SegmentMatcher","IN_LARGE_SEGMENT":"#/components/schemas/SegmentMatcher","IN_RULE_BASED_SEGMENT":"#/components/schemas/SegmentMatcher","IN_SPLIT":"#/components/schemas/SplitMatcher","BOOLEAN":"#/components/schemas/BooleanMatcher","ON_DATE":"#/components/schemas/DateMatcher","ON_OR_AFTER_DATE":"#/components/schemas/DateMatcher","ON_OR_BEFORE_DATE":"#/components/schemas/DateMatcher","BETWEEN_DATE":"#/components/schemas/BetweenDateMatcher","EQUAL_SET":"#/components/schemas/SetMatcher","ANY_OF_SET":"#/components/schemas/SetMatcher","ALL_OF_SET":"#/components/schemas/SetMatcher","PART_OF_SET":"#/components/schemas/SetMatcher","EQUAL_NUMBER":"#/components/schemas/NumberMatcher","LESS_THAN_OR_EQUAL_NUMBER":"#/components/schemas/NumberMatcher","GREATER_THAN_OR_EQUAL_NUMBER":"#/components/schemas/NumberMatcher","BETWEEN_NUMBER":"#/components/schemas/BetweenNumberMatcher","IN_LIST_STRING":"#/components/schemas/InListStringMatcher","STARTS_WITH_STRING":"#/components/schemas/StringListMatcher","ENDS_WITH_STRING":"#/components/schemas/StringListMatcher","CONTAINS_STRING":"#/components/schemas/StringListMatcher","MATCHES_STRING":"#/components/schemas/MatchesStringMatcher","EQUAL_TO_SEMVER":"#/components/schemas/SemverCompareMatcher","GREATER_THAN_OR_EQUAL_TO_SEMVER":"#/components/schemas/SemverCompareMatcher","LESS_THAN_OR_EQUAL_TO_SEMVER":"#/components/schemas/SemverCompareMatcher","BETWEEN_SEMVER":"#/components/schemas/BetweenSemverMatcher","IN_LIST_SEMVER":"#/components/schemas/InListSemverMatcher"}}},"SegmentMatcher":{"type":"object","additionalProperties":false,"description":"Key is in the named standard, large, or rule-based segment.","required":["type","string"],"properties":{"type":{"type":"string","enum":["IN_SEGMENT","IN_LARGE_SEGMENT","IN_RULE_BASED_SEGMENT"]},"negate":{"type":"boolean"},"string":{"type":"string","description":"Segment name."}}},"SplitMatcher":{"type":"object","additionalProperties":false,"description":"Prerequisite feature-flag (dependency) matcher.","required":["type","depends"],"properties":{"type":{"type":"string","enum":["IN_SPLIT"]},"negate":{"type":"boolean"},"depends":{"$ref":"#/components/schemas/Depends"}}},"Depends":{"type":"object","description":"Feature flag dependency matcher payload.","required":["splitName","treatments"],"properties":{"splitName":{"type":"string","pattern":"^[A-Za-z][-_A-Za-z0-9]*$","maxLength":100,"description":"Name of the prerequisite feature flag."},"treatments":{"type":"array","minItems":1,"description":"Treatments accepted from the prerequisite feature flag.","items":{"$ref":"#/components/schemas/TreatmentName"}}}},"BooleanMatcher":{"type":"object","additionalProperties":false,"description":"Attribute equals a boolean value.","required":["type","attribute","bool"],"properties":{"type":{"type":"string","enum":["BOOLEAN"]},"negate":{"type":"boolean"},"attribute":{"type":"string"},"bool":{"type":"boolean"}}},"DateMatcher":{"type":"object","additionalProperties":false,"description":"Attribute compared to a single epoch-millisecond timestamp.","required":["type","attribute","date"],"properties":{"type":{"type":"string","enum":["ON_DATE","ON_OR_AFTER_DATE","ON_OR_BEFORE_DATE"]},"negate":{"type":"boolean"},"attribute":{"type":"string"},"date":{"type":"integer","format":"int64","description":"Epoch milliseconds."}}},"BetweenDateMatcher":{"type":"object","additionalProperties":false,"description":"Attribute falls in an inclusive epoch-millisecond range.","required":["type","attribute","between"],"properties":{"type":{"type":"string","enum":["BETWEEN_DATE"]},"negate":{"type":"boolean"},"attribute":{"type":"string"},"between":{"$ref":"#/components/schemas/BetweenNumberAttribute"}}},"BetweenNumberAttribute":{"type":"object","description":"Inclusive numeric range for BETWEEN_NUMBER and BETWEEN_DATE matchers. Values are int64 — plain numbers for number matchers, epoch millis for date matchers. String/semver ranges use BetweenStringAttribute.\n","required":["from","to"],"properties":{"from":{"type":"integer","format":"int64"},"to":{"type":"integer","format":"int64"}}},"SetMatcher":{"type":"object","additionalProperties":false,"description":"Attribute set compared to a list of strings.","required":["type","attribute","strings"],"properties":{"type":{"type":"string","enum":["EQUAL_SET","ANY_OF_SET","ALL_OF_SET","PART_OF_SET"]},"negate":{"type":"boolean"},"attribute":{"type":"string"},"strings":{"type":"array","minItems":1,"items":{"type":"string"}}}},"NumberMatcher":{"type":"object","additionalProperties":false,"description":"Attribute compared to a single int64 number.","required":["type","attribute","number"],"properties":{"type":{"type":"string","enum":["EQUAL_NUMBER","LESS_THAN_OR_EQUAL_NUMBER","GREATER_THAN_OR_EQUAL_NUMBER"]},"negate":{"type":"boolean"},"attribute":{"type":"string"},"number":{"type":"integer","format":"int64"}}},"BetweenNumberMatcher":{"type":"object","additionalProperties":false,"description":"Attribute falls in an inclusive numeric range.","required":["type","attribute","between"],"properties":{"type":{"type":"string","enum":["BETWEEN_NUMBER"]},"negate":{"type":"boolean"},"attribute":{"type":"string"},"between":{"$ref":"#/components/schemas/BetweenNumberAttribute"}}},"InListStringMatcher":{"type":"object","additionalProperties":false,"description":"Value is in a string list. Omit `attribute` to match the key; set `attribute` to match\nthat traffic-type attribute.\n","required":["type","strings"],"properties":{"type":{"type":"string","enum":["IN_LIST_STRING"]},"negate":{"type":"boolean"},"attribute":{"type":"string"},"strings":{"type":"array","minItems":1,"items":{"type":"string"}}}},"StringListMatcher":{"type":"object","additionalProperties":false,"description":"Attribute (or key, if `attribute` is omitted) starts with, ends with, or contains any of\nthe listed strings.\n","required":["type","strings"],"properties":{"type":{"type":"string","enum":["STARTS_WITH_STRING","ENDS_WITH_STRING","CONTAINS_STRING"]},"negate":{"type":"boolean"},"attribute":{"type":"string"},"strings":{"type":"array","minItems":1,"items":{"type":"string"}}}},"MatchesStringMatcher":{"type":"object","additionalProperties":false,"description":"Attribute (or key, if `attribute` is omitted) matches a regular expression in `string`.\n","required":["type","string"],"properties":{"type":{"type":"string","enum":["MATCHES_STRING"]},"negate":{"type":"boolean"},"attribute":{"type":"string"},"string":{"type":"string","description":"Regular expression."}}},"SemverCompareMatcher":{"type":"object","additionalProperties":false,"description":"Attribute compared to a single semantic-version string.","required":["type","attribute","string"],"properties":{"type":{"type":"string","enum":["EQUAL_TO_SEMVER","GREATER_THAN_OR_EQUAL_TO_SEMVER","LESS_THAN_OR_EQUAL_TO_SEMVER"]},"negate":{"type":"boolean"},"attribute":{"type":"string"},"string":{"type":"string"}}},"BetweenSemverMatcher":{"type":"object","additionalProperties":false,"description":"Attribute falls in an inclusive semantic-version range.","required":["type","attribute","betweenString"],"properties":{"type":{"type":"string","enum":["BETWEEN_SEMVER"]},"negate":{"type":"boolean"},"attribute":{"type":"string"},"betweenString":{"$ref":"#/components/schemas/BetweenStringAttribute"}}},"BetweenStringAttribute":{"type":"object","description":"Inclusive string range for semantic-version BETWEEN matchers.","required":["from","to"],"properties":{"from":{"type":"string"},"to":{"type":"string"}}},"InListSemverMatcher":{"type":"object","additionalProperties":false,"description":"Attribute semantic version is in the listed versions.","required":["type","attribute","strings"],"properties":{"type":{"type":"string","enum":["IN_LIST_SEMVER"]},"negate":{"type":"boolean"},"attribute":{"type":"string"},"strings":{"type":"array","minItems":1,"items":{"type":"string"}}}},"Distribution":{"type":"object","description":"A percentage bucket assigning a share of traffic to a treatment. The treatment name must\nrefer to a treatment in the same definition.\n","required":["treatment","size"],"properties":{"treatment":{"allOf":[{"$ref":"#/components/schemas/TreatmentName"}],"description":"Treatment name from this definition."},"size":{"type":"integer","format":"int32","minimum":0,"maximum":100,"description":"Percentage of traffic assigned to the treatment (0-100)."}}},"FlagSetReference":{"type":"object","description":"Flag set associated with a feature flag definition. Used on create, update, and GET.\nIdentify the flag set by `id`. `name` is not accepted or returned.\n","required":["id"],"properties":{"id":{"type":"string","format":"uuid","description":"System-assigned identifier for the flag set."}}},"Impressions":{"type":"object","description":"Traffic/impression freshness data for this Feature Flag Definition.\n","required":["lastImpressionAt"],"properties":{"lastImpressionAt":{"type":"string","format":"date-time","nullable":true,"description":"Timestamp of the most recent impression recorded for this definition, or `null` if it\nhas never received traffic.\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"}}}},"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/feature-flag-definitions":{"get":{"tags":["Feature Flag Definitions"],"operationId":"listFeatureFlagDefinitions","summary":"List Feature Flag Definitions","description":"Returns a paginated list of active Feature Flag Definitions across all environments for the\nFeature Flag specified by `feature_flag_name`. Returns `404` if no Feature Flag with that\nname exists in the project.\n","parameters":[{"$ref":"#/components/parameters/AccountId"},{"$ref":"#/components/parameters/OrganizationIdentifier"},{"$ref":"#/components/parameters/ProjectIdentifier"},{"name":"feature_flag_name","in":"query","required":true,"description":"The unique name of the feature flag whose definitions to list. System-assigned\nidentifiers are not accepted.\n","schema":{"type":"string","pattern":"^[A-Za-z][-_A-Za-z0-9]*$","maxLength":100}},{"$ref":"#/components/parameters/PaginationLimitParam"},{"$ref":"#/components/parameters/PaginationOffsetParam"}],"responses":{"200":{"description":"OK — paginated list of feature flag definitions returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeatureFlagDefinitionListResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## Kill a Feature Flag Definition

> Requires \`environment\_id\` as a query parameter. Kills the Feature Flag Definition for the\
> specified feature flag in the specified environment. A killed definition serves the default\
> treatment. Any pending change request for this definition is auto-rejected so the kill can\
> proceed.<br>

```json
{"openapi":"3.0.3","info":{"title":"Harness Feature Management & Experimentation API","version":"4.0.0"},"tags":[{"name":"Feature Flag Definitions","description":"Manage environment-specific feature flag definitions (treatments, traffic allocation, targeting)."}],"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":{"FeatureFlagName":{"name":"feature-flag-name","in":"path","required":true,"description":"The unique name of the feature flag within the project. Names must begin with a letter\nand may contain letters, numbers, underscores, and hyphens. Use the same value that was\nsupplied as `name` when the flag was created. System-assigned ids are not accepted.\n","schema":{"type":"string","pattern":"^[A-Za-z][-_A-Za-z0-9]*$","maxLength":100}},"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}},"EnvironmentId":{"name":"environment_id","in":"query","required":true,"description":"Environment identifier. Scopes the request to a specific environment; combined with the\nresource name in the path it identifies a specific environment-scoped definition (e.g.,\na Feature Flag Definition or a Segment Definition).\n","schema":{"type":"string","format":"uuid","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":{"FeatureFlagDefinitionActionRequest":{"type":"object","description":"Optional metadata supplied when killing, restoring, or reallocating a feature flag definition.","properties":{"comment":{"type":"string","description":"Optional comment recorded with the action."},"title":{"type":"string","description":"Optional title recorded with the action."}}},"FeatureFlagDefinitionResponse":{"type":"object","description":"Feature Flag Definition entity together with the OPA governance result.","required":["entity","governance"],"properties":{"entity":{"$ref":"#/components/schemas/FeatureFlagDefinition"},"governance":{"allOf":[{"$ref":"#/components/schemas/GovernanceResult"}],"description":"OPA governance result for the mutation."}}},"FeatureFlagDefinition":{"type":"object","description":"An environment-specific Feature Flag Definition.","required":["id","featureFlag","environment","trafficType","isKilled","treatments","defaultTreatment","baselineTreatment","trafficAllocation","rules","defaultRule","createdAt","impressions"],"properties":{"id":{"type":"string","format":"uuid","description":"System-assigned identifier for this feature flag definition."},"featureFlag":{"allOf":[{"$ref":"#/components/schemas/NamedReference"}],"description":"Reference to the parent feature flag metadata."},"environment":{"allOf":[{"$ref":"#/components/schemas/NamedReference"}],"description":"Reference to the environment this definition is scoped to."},"trafficType":{"allOf":[{"$ref":"#/components/schemas/NamedReference"}],"description":"Reference to the traffic type used to bucket keys."},"isKilled":{"type":"boolean","readOnly":true,"description":"Whether the flag is killed in this environment. While killed, all traffic receives\n`defaultTreatment` regardless of rules. Response-only — use the dedicated kill/restore\nactions to change it.\n"},"treatments":{"type":"array","minItems":2,"description":"The treatments available for this flag in this environment.","items":{"$ref":"#/components/schemas/Treatment"}},"defaultTreatment":{"allOf":[{"$ref":"#/components/schemas/TreatmentName"}],"description":"Treatment served when the flag is killed, and to traffic outside `trafficAllocation`.\n"},"baselineTreatment":{"allOf":[{"$ref":"#/components/schemas/TreatmentName"}],"description":"Baseline treatment used as the control group for metrics calculations."},"trafficAllocation":{"type":"integer","format":"int32","minimum":0,"maximum":100,"description":"Percentage of total traffic that participates in this flag's evaluation. Traffic\noutside this allocation receives `defaultTreatment`.\n"},"rules":{"type":"array","description":"Ordered targeting rules. Empty means all traffic falls through to `defaultRule`.","items":{"$ref":"#/components/schemas/Rule"}},"defaultRule":{"type":"array","minItems":1,"description":"Distribution applied to in-allocation traffic that matches no targeting rule. Bucket\nsizes must sum to 100.\n","items":{"$ref":"#/components/schemas/Distribution"}},"flagSets":{"type":"array","description":"Flag sets associated with this definition. Empty means the definition belongs to no\nflag set. Assigned on create/PATCH; echoed on GET.\n","items":{"$ref":"#/components/schemas/FlagSetReference"}},"createdAt":{"type":"string","format":"date-time","description":"ISO-8601 timestamp when this definition was created."},"impressions":{"allOf":[{"$ref":"#/components/schemas/Impressions"}],"description":"Traffic/impression freshness data for this definition."}}},"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."}}},"Treatment":{"type":"object","description":"A single treatment (variation) of the feature flag in this environment.\n","required":["name"],"properties":{"name":{"allOf":[{"$ref":"#/components/schemas/TreatmentName"}],"description":"Treatment name. Must start with a letter or digit; remaining characters may be letters,\ndigits, hyphens, underscores, or periods. The reserved name `control` is not allowed.\n"},"description":{"type":"string","nullable":true,"description":"Optional description of this treatment."},"keys":{"type":"array","description":"Keys explicitly assigned to this treatment.","items":{"type":"string"}},"segments":{"type":"array","description":"Standard segment names assigned to this treatment.","items":{"type":"string","pattern":"^[A-Za-z][-_A-Za-z0-9]*$","maxLength":100}},"largeSegments":{"type":"array","description":"Large segment names assigned to this treatment.","items":{"type":"string","pattern":"^[A-Za-z][-_A-Za-z0-9]*$","maxLength":100}},"ruleBasedSegments":{"type":"array","description":"Rule-based segment names assigned to this treatment.","items":{"type":"string","pattern":"^[A-Za-z][-_A-Za-z0-9]*$","maxLength":100}},"configurations":{"type":"string","nullable":true,"description":"Dynamic configuration attached to this treatment, serialized as a JSON string.\n"}}},"TreatmentName":{"type":"string","pattern":"^[a-zA-Z0-9][-_\\.a-zA-Z0-9]*$","description":"Treatment name. Must start with a letter or digit; remaining characters may be letters,\ndigits, hyphens, underscores, or periods.\n"},"Rule":{"type":"object","description":"A targeting rule: a condition and the treatment buckets served on match.\n","required":["condition","buckets"],"properties":{"condition":{"$ref":"#/components/schemas/Condition"},"buckets":{"type":"array","minItems":1,"description":"Treatment buckets served when the condition matches. Sizes must sum to 100.\n","items":{"$ref":"#/components/schemas/Distribution"}}}},"Condition":{"type":"object","description":"The matching condition for a targeting rule. Only the `AND` combiner is supported — all\nmatchers must match. `OR` combination is not supported.\n","required":["combiner","matchers"],"properties":{"combiner":{"type":"string","enum":["AND"],"description":"Matcher combiner. Only `AND` is supported."},"matchers":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/Matcher"}}}},"Matcher":{"description":"A matcher within a targeting condition. Discriminated by `type` — each variant requires\nthe value field(s) that type evaluates. `negate` is optional on every variant (`true`\ninverts the result). `attribute` is required when the matcher evaluates a traffic-type\nattribute; omit it only for key-based list/string matchers (`IN_LIST_STRING`,\n`STARTS_WITH_STRING`, `ENDS_WITH_STRING`, `CONTAINS_STRING`, `MATCHES_STRING`).\n","oneOf":[{"$ref":"#/components/schemas/SegmentMatcher"},{"$ref":"#/components/schemas/SplitMatcher"},{"$ref":"#/components/schemas/BooleanMatcher"},{"$ref":"#/components/schemas/DateMatcher"},{"$ref":"#/components/schemas/BetweenDateMatcher"},{"$ref":"#/components/schemas/SetMatcher"},{"$ref":"#/components/schemas/NumberMatcher"},{"$ref":"#/components/schemas/BetweenNumberMatcher"},{"$ref":"#/components/schemas/InListStringMatcher"},{"$ref":"#/components/schemas/StringListMatcher"},{"$ref":"#/components/schemas/MatchesStringMatcher"},{"$ref":"#/components/schemas/SemverCompareMatcher"},{"$ref":"#/components/schemas/BetweenSemverMatcher"},{"$ref":"#/components/schemas/InListSemverMatcher"}],"discriminator":{"propertyName":"type","mapping":{"IN_SEGMENT":"#/components/schemas/SegmentMatcher","IN_LARGE_SEGMENT":"#/components/schemas/SegmentMatcher","IN_RULE_BASED_SEGMENT":"#/components/schemas/SegmentMatcher","IN_SPLIT":"#/components/schemas/SplitMatcher","BOOLEAN":"#/components/schemas/BooleanMatcher","ON_DATE":"#/components/schemas/DateMatcher","ON_OR_AFTER_DATE":"#/components/schemas/DateMatcher","ON_OR_BEFORE_DATE":"#/components/schemas/DateMatcher","BETWEEN_DATE":"#/components/schemas/BetweenDateMatcher","EQUAL_SET":"#/components/schemas/SetMatcher","ANY_OF_SET":"#/components/schemas/SetMatcher","ALL_OF_SET":"#/components/schemas/SetMatcher","PART_OF_SET":"#/components/schemas/SetMatcher","EQUAL_NUMBER":"#/components/schemas/NumberMatcher","LESS_THAN_OR_EQUAL_NUMBER":"#/components/schemas/NumberMatcher","GREATER_THAN_OR_EQUAL_NUMBER":"#/components/schemas/NumberMatcher","BETWEEN_NUMBER":"#/components/schemas/BetweenNumberMatcher","IN_LIST_STRING":"#/components/schemas/InListStringMatcher","STARTS_WITH_STRING":"#/components/schemas/StringListMatcher","ENDS_WITH_STRING":"#/components/schemas/StringListMatcher","CONTAINS_STRING":"#/components/schemas/StringListMatcher","MATCHES_STRING":"#/components/schemas/MatchesStringMatcher","EQUAL_TO_SEMVER":"#/components/schemas/SemverCompareMatcher","GREATER_THAN_OR_EQUAL_TO_SEMVER":"#/components/schemas/SemverCompareMatcher","LESS_THAN_OR_EQUAL_TO_SEMVER":"#/components/schemas/SemverCompareMatcher","BETWEEN_SEMVER":"#/components/schemas/BetweenSemverMatcher","IN_LIST_SEMVER":"#/components/schemas/InListSemverMatcher"}}},"SegmentMatcher":{"type":"object","additionalProperties":false,"description":"Key is in the named standard, large, or rule-based segment.","required":["type","string"],"properties":{"type":{"type":"string","enum":["IN_SEGMENT","IN_LARGE_SEGMENT","IN_RULE_BASED_SEGMENT"]},"negate":{"type":"boolean"},"string":{"type":"string","description":"Segment name."}}},"SplitMatcher":{"type":"object","additionalProperties":false,"description":"Prerequisite feature-flag (dependency) matcher.","required":["type","depends"],"properties":{"type":{"type":"string","enum":["IN_SPLIT"]},"negate":{"type":"boolean"},"depends":{"$ref":"#/components/schemas/Depends"}}},"Depends":{"type":"object","description":"Feature flag dependency matcher payload.","required":["splitName","treatments"],"properties":{"splitName":{"type":"string","pattern":"^[A-Za-z][-_A-Za-z0-9]*$","maxLength":100,"description":"Name of the prerequisite feature flag."},"treatments":{"type":"array","minItems":1,"description":"Treatments accepted from the prerequisite feature flag.","items":{"$ref":"#/components/schemas/TreatmentName"}}}},"BooleanMatcher":{"type":"object","additionalProperties":false,"description":"Attribute equals a boolean value.","required":["type","attribute","bool"],"properties":{"type":{"type":"string","enum":["BOOLEAN"]},"negate":{"type":"boolean"},"attribute":{"type":"string"},"bool":{"type":"boolean"}}},"DateMatcher":{"type":"object","additionalProperties":false,"description":"Attribute compared to a single epoch-millisecond timestamp.","required":["type","attribute","date"],"properties":{"type":{"type":"string","enum":["ON_DATE","ON_OR_AFTER_DATE","ON_OR_BEFORE_DATE"]},"negate":{"type":"boolean"},"attribute":{"type":"string"},"date":{"type":"integer","format":"int64","description":"Epoch milliseconds."}}},"BetweenDateMatcher":{"type":"object","additionalProperties":false,"description":"Attribute falls in an inclusive epoch-millisecond range.","required":["type","attribute","between"],"properties":{"type":{"type":"string","enum":["BETWEEN_DATE"]},"negate":{"type":"boolean"},"attribute":{"type":"string"},"between":{"$ref":"#/components/schemas/BetweenNumberAttribute"}}},"BetweenNumberAttribute":{"type":"object","description":"Inclusive numeric range for BETWEEN_NUMBER and BETWEEN_DATE matchers. Values are int64 — plain numbers for number matchers, epoch millis for date matchers. String/semver ranges use BetweenStringAttribute.\n","required":["from","to"],"properties":{"from":{"type":"integer","format":"int64"},"to":{"type":"integer","format":"int64"}}},"SetMatcher":{"type":"object","additionalProperties":false,"description":"Attribute set compared to a list of strings.","required":["type","attribute","strings"],"properties":{"type":{"type":"string","enum":["EQUAL_SET","ANY_OF_SET","ALL_OF_SET","PART_OF_SET"]},"negate":{"type":"boolean"},"attribute":{"type":"string"},"strings":{"type":"array","minItems":1,"items":{"type":"string"}}}},"NumberMatcher":{"type":"object","additionalProperties":false,"description":"Attribute compared to a single int64 number.","required":["type","attribute","number"],"properties":{"type":{"type":"string","enum":["EQUAL_NUMBER","LESS_THAN_OR_EQUAL_NUMBER","GREATER_THAN_OR_EQUAL_NUMBER"]},"negate":{"type":"boolean"},"attribute":{"type":"string"},"number":{"type":"integer","format":"int64"}}},"BetweenNumberMatcher":{"type":"object","additionalProperties":false,"description":"Attribute falls in an inclusive numeric range.","required":["type","attribute","between"],"properties":{"type":{"type":"string","enum":["BETWEEN_NUMBER"]},"negate":{"type":"boolean"},"attribute":{"type":"string"},"between":{"$ref":"#/components/schemas/BetweenNumberAttribute"}}},"InListStringMatcher":{"type":"object","additionalProperties":false,"description":"Value is in a string list. Omit `attribute` to match the key; set `attribute` to match\nthat traffic-type attribute.\n","required":["type","strings"],"properties":{"type":{"type":"string","enum":["IN_LIST_STRING"]},"negate":{"type":"boolean"},"attribute":{"type":"string"},"strings":{"type":"array","minItems":1,"items":{"type":"string"}}}},"StringListMatcher":{"type":"object","additionalProperties":false,"description":"Attribute (or key, if `attribute` is omitted) starts with, ends with, or contains any of\nthe listed strings.\n","required":["type","strings"],"properties":{"type":{"type":"string","enum":["STARTS_WITH_STRING","ENDS_WITH_STRING","CONTAINS_STRING"]},"negate":{"type":"boolean"},"attribute":{"type":"string"},"strings":{"type":"array","minItems":1,"items":{"type":"string"}}}},"MatchesStringMatcher":{"type":"object","additionalProperties":false,"description":"Attribute (or key, if `attribute` is omitted) matches a regular expression in `string`.\n","required":["type","string"],"properties":{"type":{"type":"string","enum":["MATCHES_STRING"]},"negate":{"type":"boolean"},"attribute":{"type":"string"},"string":{"type":"string","description":"Regular expression."}}},"SemverCompareMatcher":{"type":"object","additionalProperties":false,"description":"Attribute compared to a single semantic-version string.","required":["type","attribute","string"],"properties":{"type":{"type":"string","enum":["EQUAL_TO_SEMVER","GREATER_THAN_OR_EQUAL_TO_SEMVER","LESS_THAN_OR_EQUAL_TO_SEMVER"]},"negate":{"type":"boolean"},"attribute":{"type":"string"},"string":{"type":"string"}}},"BetweenSemverMatcher":{"type":"object","additionalProperties":false,"description":"Attribute falls in an inclusive semantic-version range.","required":["type","attribute","betweenString"],"properties":{"type":{"type":"string","enum":["BETWEEN_SEMVER"]},"negate":{"type":"boolean"},"attribute":{"type":"string"},"betweenString":{"$ref":"#/components/schemas/BetweenStringAttribute"}}},"BetweenStringAttribute":{"type":"object","description":"Inclusive string range for semantic-version BETWEEN matchers.","required":["from","to"],"properties":{"from":{"type":"string"},"to":{"type":"string"}}},"InListSemverMatcher":{"type":"object","additionalProperties":false,"description":"Attribute semantic version is in the listed versions.","required":["type","attribute","strings"],"properties":{"type":{"type":"string","enum":["IN_LIST_SEMVER"]},"negate":{"type":"boolean"},"attribute":{"type":"string"},"strings":{"type":"array","minItems":1,"items":{"type":"string"}}}},"Distribution":{"type":"object","description":"A percentage bucket assigning a share of traffic to a treatment. The treatment name must\nrefer to a treatment in the same definition.\n","required":["treatment","size"],"properties":{"treatment":{"allOf":[{"$ref":"#/components/schemas/TreatmentName"}],"description":"Treatment name from this definition."},"size":{"type":"integer","format":"int32","minimum":0,"maximum":100,"description":"Percentage of traffic assigned to the treatment (0-100)."}}},"FlagSetReference":{"type":"object","description":"Flag set associated with a feature flag definition. Used on create, update, and GET.\nIdentify the flag set by `id`. `name` is not accepted or returned.\n","required":["id"],"properties":{"id":{"type":"string","format":"uuid","description":"System-assigned identifier for the flag set."}}},"Impressions":{"type":"object","description":"Traffic/impression freshness data for this Feature Flag Definition.\n","required":["lastImpressionAt"],"properties":{"lastImpressionAt":{"type":"string","format":"date-time","nullable":true,"description":"Timestamp of the most recent impression recorded for this definition, or `null` if it\nhas never received traffic.\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/feature-flag-definitions/{feature-flag-name}/kill":{"post":{"tags":["Feature Flag Definitions"],"operationId":"killFeatureFlagDefinition","summary":"Kill a Feature Flag Definition","description":"Requires `environment_id` as a query parameter. Kills the Feature Flag Definition for the\nspecified feature flag in the specified environment. A killed definition serves the default\ntreatment. Any pending change request for this definition is auto-rejected so the kill can\nproceed.\n","parameters":[{"$ref":"#/components/parameters/FeatureFlagName"},{"$ref":"#/components/parameters/AccountId"},{"$ref":"#/components/parameters/EnvironmentId"},{"$ref":"#/components/parameters/OrganizationIdentifier"},{"$ref":"#/components/parameters/ProjectIdentifier"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeatureFlagDefinitionActionRequest"}}}},"responses":{"200":{"description":"OK — feature flag definition killed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeatureFlagDefinitionResponse"}}}},"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"}}}}}}
```

## Restore a Feature Flag Definition

> Requires \`environment\_id\` as a query parameter. Restores the Feature Flag Definition for\
> the specified feature flag in the specified environment after it was killed. Returns \`409\`\
> when a pending change request already exists for this definition, \`400\` (\`invalidState\`)\
> when the definition is not currently killed, and \`403\` when the environment requires\
> approval.<br>

```json
{"openapi":"3.0.3","info":{"title":"Harness Feature Management & Experimentation API","version":"4.0.0"},"tags":[{"name":"Feature Flag Definitions","description":"Manage environment-specific feature flag definitions (treatments, traffic allocation, targeting)."}],"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":{"FeatureFlagName":{"name":"feature-flag-name","in":"path","required":true,"description":"The unique name of the feature flag within the project. Names must begin with a letter\nand may contain letters, numbers, underscores, and hyphens. Use the same value that was\nsupplied as `name` when the flag was created. System-assigned ids are not accepted.\n","schema":{"type":"string","pattern":"^[A-Za-z][-_A-Za-z0-9]*$","maxLength":100}},"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}},"EnvironmentId":{"name":"environment_id","in":"query","required":true,"description":"Environment identifier. Scopes the request to a specific environment; combined with the\nresource name in the path it identifies a specific environment-scoped definition (e.g.,\na Feature Flag Definition or a Segment Definition).\n","schema":{"type":"string","format":"uuid","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":{"FeatureFlagDefinitionActionRequest":{"type":"object","description":"Optional metadata supplied when killing, restoring, or reallocating a feature flag definition.","properties":{"comment":{"type":"string","description":"Optional comment recorded with the action."},"title":{"type":"string","description":"Optional title recorded with the action."}}},"FeatureFlagDefinitionResponse":{"type":"object","description":"Feature Flag Definition entity together with the OPA governance result.","required":["entity","governance"],"properties":{"entity":{"$ref":"#/components/schemas/FeatureFlagDefinition"},"governance":{"allOf":[{"$ref":"#/components/schemas/GovernanceResult"}],"description":"OPA governance result for the mutation."}}},"FeatureFlagDefinition":{"type":"object","description":"An environment-specific Feature Flag Definition.","required":["id","featureFlag","environment","trafficType","isKilled","treatments","defaultTreatment","baselineTreatment","trafficAllocation","rules","defaultRule","createdAt","impressions"],"properties":{"id":{"type":"string","format":"uuid","description":"System-assigned identifier for this feature flag definition."},"featureFlag":{"allOf":[{"$ref":"#/components/schemas/NamedReference"}],"description":"Reference to the parent feature flag metadata."},"environment":{"allOf":[{"$ref":"#/components/schemas/NamedReference"}],"description":"Reference to the environment this definition is scoped to."},"trafficType":{"allOf":[{"$ref":"#/components/schemas/NamedReference"}],"description":"Reference to the traffic type used to bucket keys."},"isKilled":{"type":"boolean","readOnly":true,"description":"Whether the flag is killed in this environment. While killed, all traffic receives\n`defaultTreatment` regardless of rules. Response-only — use the dedicated kill/restore\nactions to change it.\n"},"treatments":{"type":"array","minItems":2,"description":"The treatments available for this flag in this environment.","items":{"$ref":"#/components/schemas/Treatment"}},"defaultTreatment":{"allOf":[{"$ref":"#/components/schemas/TreatmentName"}],"description":"Treatment served when the flag is killed, and to traffic outside `trafficAllocation`.\n"},"baselineTreatment":{"allOf":[{"$ref":"#/components/schemas/TreatmentName"}],"description":"Baseline treatment used as the control group for metrics calculations."},"trafficAllocation":{"type":"integer","format":"int32","minimum":0,"maximum":100,"description":"Percentage of total traffic that participates in this flag's evaluation. Traffic\noutside this allocation receives `defaultTreatment`.\n"},"rules":{"type":"array","description":"Ordered targeting rules. Empty means all traffic falls through to `defaultRule`.","items":{"$ref":"#/components/schemas/Rule"}},"defaultRule":{"type":"array","minItems":1,"description":"Distribution applied to in-allocation traffic that matches no targeting rule. Bucket\nsizes must sum to 100.\n","items":{"$ref":"#/components/schemas/Distribution"}},"flagSets":{"type":"array","description":"Flag sets associated with this definition. Empty means the definition belongs to no\nflag set. Assigned on create/PATCH; echoed on GET.\n","items":{"$ref":"#/components/schemas/FlagSetReference"}},"createdAt":{"type":"string","format":"date-time","description":"ISO-8601 timestamp when this definition was created."},"impressions":{"allOf":[{"$ref":"#/components/schemas/Impressions"}],"description":"Traffic/impression freshness data for this definition."}}},"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."}}},"Treatment":{"type":"object","description":"A single treatment (variation) of the feature flag in this environment.\n","required":["name"],"properties":{"name":{"allOf":[{"$ref":"#/components/schemas/TreatmentName"}],"description":"Treatment name. Must start with a letter or digit; remaining characters may be letters,\ndigits, hyphens, underscores, or periods. The reserved name `control` is not allowed.\n"},"description":{"type":"string","nullable":true,"description":"Optional description of this treatment."},"keys":{"type":"array","description":"Keys explicitly assigned to this treatment.","items":{"type":"string"}},"segments":{"type":"array","description":"Standard segment names assigned to this treatment.","items":{"type":"string","pattern":"^[A-Za-z][-_A-Za-z0-9]*$","maxLength":100}},"largeSegments":{"type":"array","description":"Large segment names assigned to this treatment.","items":{"type":"string","pattern":"^[A-Za-z][-_A-Za-z0-9]*$","maxLength":100}},"ruleBasedSegments":{"type":"array","description":"Rule-based segment names assigned to this treatment.","items":{"type":"string","pattern":"^[A-Za-z][-_A-Za-z0-9]*$","maxLength":100}},"configurations":{"type":"string","nullable":true,"description":"Dynamic configuration attached to this treatment, serialized as a JSON string.\n"}}},"TreatmentName":{"type":"string","pattern":"^[a-zA-Z0-9][-_\\.a-zA-Z0-9]*$","description":"Treatment name. Must start with a letter or digit; remaining characters may be letters,\ndigits, hyphens, underscores, or periods.\n"},"Rule":{"type":"object","description":"A targeting rule: a condition and the treatment buckets served on match.\n","required":["condition","buckets"],"properties":{"condition":{"$ref":"#/components/schemas/Condition"},"buckets":{"type":"array","minItems":1,"description":"Treatment buckets served when the condition matches. Sizes must sum to 100.\n","items":{"$ref":"#/components/schemas/Distribution"}}}},"Condition":{"type":"object","description":"The matching condition for a targeting rule. Only the `AND` combiner is supported — all\nmatchers must match. `OR` combination is not supported.\n","required":["combiner","matchers"],"properties":{"combiner":{"type":"string","enum":["AND"],"description":"Matcher combiner. Only `AND` is supported."},"matchers":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/Matcher"}}}},"Matcher":{"description":"A matcher within a targeting condition. Discriminated by `type` — each variant requires\nthe value field(s) that type evaluates. `negate` is optional on every variant (`true`\ninverts the result). `attribute` is required when the matcher evaluates a traffic-type\nattribute; omit it only for key-based list/string matchers (`IN_LIST_STRING`,\n`STARTS_WITH_STRING`, `ENDS_WITH_STRING`, `CONTAINS_STRING`, `MATCHES_STRING`).\n","oneOf":[{"$ref":"#/components/schemas/SegmentMatcher"},{"$ref":"#/components/schemas/SplitMatcher"},{"$ref":"#/components/schemas/BooleanMatcher"},{"$ref":"#/components/schemas/DateMatcher"},{"$ref":"#/components/schemas/BetweenDateMatcher"},{"$ref":"#/components/schemas/SetMatcher"},{"$ref":"#/components/schemas/NumberMatcher"},{"$ref":"#/components/schemas/BetweenNumberMatcher"},{"$ref":"#/components/schemas/InListStringMatcher"},{"$ref":"#/components/schemas/StringListMatcher"},{"$ref":"#/components/schemas/MatchesStringMatcher"},{"$ref":"#/components/schemas/SemverCompareMatcher"},{"$ref":"#/components/schemas/BetweenSemverMatcher"},{"$ref":"#/components/schemas/InListSemverMatcher"}],"discriminator":{"propertyName":"type","mapping":{"IN_SEGMENT":"#/components/schemas/SegmentMatcher","IN_LARGE_SEGMENT":"#/components/schemas/SegmentMatcher","IN_RULE_BASED_SEGMENT":"#/components/schemas/SegmentMatcher","IN_SPLIT":"#/components/schemas/SplitMatcher","BOOLEAN":"#/components/schemas/BooleanMatcher","ON_DATE":"#/components/schemas/DateMatcher","ON_OR_AFTER_DATE":"#/components/schemas/DateMatcher","ON_OR_BEFORE_DATE":"#/components/schemas/DateMatcher","BETWEEN_DATE":"#/components/schemas/BetweenDateMatcher","EQUAL_SET":"#/components/schemas/SetMatcher","ANY_OF_SET":"#/components/schemas/SetMatcher","ALL_OF_SET":"#/components/schemas/SetMatcher","PART_OF_SET":"#/components/schemas/SetMatcher","EQUAL_NUMBER":"#/components/schemas/NumberMatcher","LESS_THAN_OR_EQUAL_NUMBER":"#/components/schemas/NumberMatcher","GREATER_THAN_OR_EQUAL_NUMBER":"#/components/schemas/NumberMatcher","BETWEEN_NUMBER":"#/components/schemas/BetweenNumberMatcher","IN_LIST_STRING":"#/components/schemas/InListStringMatcher","STARTS_WITH_STRING":"#/components/schemas/StringListMatcher","ENDS_WITH_STRING":"#/components/schemas/StringListMatcher","CONTAINS_STRING":"#/components/schemas/StringListMatcher","MATCHES_STRING":"#/components/schemas/MatchesStringMatcher","EQUAL_TO_SEMVER":"#/components/schemas/SemverCompareMatcher","GREATER_THAN_OR_EQUAL_TO_SEMVER":"#/components/schemas/SemverCompareMatcher","LESS_THAN_OR_EQUAL_TO_SEMVER":"#/components/schemas/SemverCompareMatcher","BETWEEN_SEMVER":"#/components/schemas/BetweenSemverMatcher","IN_LIST_SEMVER":"#/components/schemas/InListSemverMatcher"}}},"SegmentMatcher":{"type":"object","additionalProperties":false,"description":"Key is in the named standard, large, or rule-based segment.","required":["type","string"],"properties":{"type":{"type":"string","enum":["IN_SEGMENT","IN_LARGE_SEGMENT","IN_RULE_BASED_SEGMENT"]},"negate":{"type":"boolean"},"string":{"type":"string","description":"Segment name."}}},"SplitMatcher":{"type":"object","additionalProperties":false,"description":"Prerequisite feature-flag (dependency) matcher.","required":["type","depends"],"properties":{"type":{"type":"string","enum":["IN_SPLIT"]},"negate":{"type":"boolean"},"depends":{"$ref":"#/components/schemas/Depends"}}},"Depends":{"type":"object","description":"Feature flag dependency matcher payload.","required":["splitName","treatments"],"properties":{"splitName":{"type":"string","pattern":"^[A-Za-z][-_A-Za-z0-9]*$","maxLength":100,"description":"Name of the prerequisite feature flag."},"treatments":{"type":"array","minItems":1,"description":"Treatments accepted from the prerequisite feature flag.","items":{"$ref":"#/components/schemas/TreatmentName"}}}},"BooleanMatcher":{"type":"object","additionalProperties":false,"description":"Attribute equals a boolean value.","required":["type","attribute","bool"],"properties":{"type":{"type":"string","enum":["BOOLEAN"]},"negate":{"type":"boolean"},"attribute":{"type":"string"},"bool":{"type":"boolean"}}},"DateMatcher":{"type":"object","additionalProperties":false,"description":"Attribute compared to a single epoch-millisecond timestamp.","required":["type","attribute","date"],"properties":{"type":{"type":"string","enum":["ON_DATE","ON_OR_AFTER_DATE","ON_OR_BEFORE_DATE"]},"negate":{"type":"boolean"},"attribute":{"type":"string"},"date":{"type":"integer","format":"int64","description":"Epoch milliseconds."}}},"BetweenDateMatcher":{"type":"object","additionalProperties":false,"description":"Attribute falls in an inclusive epoch-millisecond range.","required":["type","attribute","between"],"properties":{"type":{"type":"string","enum":["BETWEEN_DATE"]},"negate":{"type":"boolean"},"attribute":{"type":"string"},"between":{"$ref":"#/components/schemas/BetweenNumberAttribute"}}},"BetweenNumberAttribute":{"type":"object","description":"Inclusive numeric range for BETWEEN_NUMBER and BETWEEN_DATE matchers. Values are int64 — plain numbers for number matchers, epoch millis for date matchers. String/semver ranges use BetweenStringAttribute.\n","required":["from","to"],"properties":{"from":{"type":"integer","format":"int64"},"to":{"type":"integer","format":"int64"}}},"SetMatcher":{"type":"object","additionalProperties":false,"description":"Attribute set compared to a list of strings.","required":["type","attribute","strings"],"properties":{"type":{"type":"string","enum":["EQUAL_SET","ANY_OF_SET","ALL_OF_SET","PART_OF_SET"]},"negate":{"type":"boolean"},"attribute":{"type":"string"},"strings":{"type":"array","minItems":1,"items":{"type":"string"}}}},"NumberMatcher":{"type":"object","additionalProperties":false,"description":"Attribute compared to a single int64 number.","required":["type","attribute","number"],"properties":{"type":{"type":"string","enum":["EQUAL_NUMBER","LESS_THAN_OR_EQUAL_NUMBER","GREATER_THAN_OR_EQUAL_NUMBER"]},"negate":{"type":"boolean"},"attribute":{"type":"string"},"number":{"type":"integer","format":"int64"}}},"BetweenNumberMatcher":{"type":"object","additionalProperties":false,"description":"Attribute falls in an inclusive numeric range.","required":["type","attribute","between"],"properties":{"type":{"type":"string","enum":["BETWEEN_NUMBER"]},"negate":{"type":"boolean"},"attribute":{"type":"string"},"between":{"$ref":"#/components/schemas/BetweenNumberAttribute"}}},"InListStringMatcher":{"type":"object","additionalProperties":false,"description":"Value is in a string list. Omit `attribute` to match the key; set `attribute` to match\nthat traffic-type attribute.\n","required":["type","strings"],"properties":{"type":{"type":"string","enum":["IN_LIST_STRING"]},"negate":{"type":"boolean"},"attribute":{"type":"string"},"strings":{"type":"array","minItems":1,"items":{"type":"string"}}}},"StringListMatcher":{"type":"object","additionalProperties":false,"description":"Attribute (or key, if `attribute` is omitted) starts with, ends with, or contains any of\nthe listed strings.\n","required":["type","strings"],"properties":{"type":{"type":"string","enum":["STARTS_WITH_STRING","ENDS_WITH_STRING","CONTAINS_STRING"]},"negate":{"type":"boolean"},"attribute":{"type":"string"},"strings":{"type":"array","minItems":1,"items":{"type":"string"}}}},"MatchesStringMatcher":{"type":"object","additionalProperties":false,"description":"Attribute (or key, if `attribute` is omitted) matches a regular expression in `string`.\n","required":["type","string"],"properties":{"type":{"type":"string","enum":["MATCHES_STRING"]},"negate":{"type":"boolean"},"attribute":{"type":"string"},"string":{"type":"string","description":"Regular expression."}}},"SemverCompareMatcher":{"type":"object","additionalProperties":false,"description":"Attribute compared to a single semantic-version string.","required":["type","attribute","string"],"properties":{"type":{"type":"string","enum":["EQUAL_TO_SEMVER","GREATER_THAN_OR_EQUAL_TO_SEMVER","LESS_THAN_OR_EQUAL_TO_SEMVER"]},"negate":{"type":"boolean"},"attribute":{"type":"string"},"string":{"type":"string"}}},"BetweenSemverMatcher":{"type":"object","additionalProperties":false,"description":"Attribute falls in an inclusive semantic-version range.","required":["type","attribute","betweenString"],"properties":{"type":{"type":"string","enum":["BETWEEN_SEMVER"]},"negate":{"type":"boolean"},"attribute":{"type":"string"},"betweenString":{"$ref":"#/components/schemas/BetweenStringAttribute"}}},"BetweenStringAttribute":{"type":"object","description":"Inclusive string range for semantic-version BETWEEN matchers.","required":["from","to"],"properties":{"from":{"type":"string"},"to":{"type":"string"}}},"InListSemverMatcher":{"type":"object","additionalProperties":false,"description":"Attribute semantic version is in the listed versions.","required":["type","attribute","strings"],"properties":{"type":{"type":"string","enum":["IN_LIST_SEMVER"]},"negate":{"type":"boolean"},"attribute":{"type":"string"},"strings":{"type":"array","minItems":1,"items":{"type":"string"}}}},"Distribution":{"type":"object","description":"A percentage bucket assigning a share of traffic to a treatment. The treatment name must\nrefer to a treatment in the same definition.\n","required":["treatment","size"],"properties":{"treatment":{"allOf":[{"$ref":"#/components/schemas/TreatmentName"}],"description":"Treatment name from this definition."},"size":{"type":"integer","format":"int32","minimum":0,"maximum":100,"description":"Percentage of traffic assigned to the treatment (0-100)."}}},"FlagSetReference":{"type":"object","description":"Flag set associated with a feature flag definition. Used on create, update, and GET.\nIdentify the flag set by `id`. `name` is not accepted or returned.\n","required":["id"],"properties":{"id":{"type":"string","format":"uuid","description":"System-assigned identifier for the flag set."}}},"Impressions":{"type":"object","description":"Traffic/impression freshness data for this Feature Flag Definition.\n","required":["lastImpressionAt"],"properties":{"lastImpressionAt":{"type":"string","format":"date-time","nullable":true,"description":"Timestamp of the most recent impression recorded for this definition, or `null` if it\nhas never received traffic.\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"}}}},"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/feature-flag-definitions/{feature-flag-name}/restore":{"post":{"tags":["Feature Flag Definitions"],"operationId":"restoreFeatureFlagDefinition","summary":"Restore a Feature Flag Definition","description":"Requires `environment_id` as a query parameter. Restores the Feature Flag Definition for\nthe specified feature flag in the specified environment after it was killed. Returns `409`\nwhen a pending change request already exists for this definition, `400` (`invalidState`)\nwhen the definition is not currently killed, and `403` when the environment requires\napproval.\n","parameters":[{"$ref":"#/components/parameters/FeatureFlagName"},{"$ref":"#/components/parameters/AccountId"},{"$ref":"#/components/parameters/EnvironmentId"},{"$ref":"#/components/parameters/OrganizationIdentifier"},{"$ref":"#/components/parameters/ProjectIdentifier"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeatureFlagDefinitionActionRequest"}}}},"responses":{"200":{"description":"OK — feature flag definition restored.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeatureFlagDefinitionResponse"}}}},"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"}}}}}}
```

## Reallocate traffic for a Feature Flag Definition

> Requires \`environment\_id\` as a query parameter. Re-hashes the traffic distribution for this\
> definition so keys may move between treatment buckets. Cannot be called while the\
> definition is killed (\`400\` \`invalidState\`). Unlike other mutations, reallocate does not\
> check for pending change requests and does not require approvals.<br>

```json
{"openapi":"3.0.3","info":{"title":"Harness Feature Management & Experimentation API","version":"4.0.0"},"tags":[{"name":"Feature Flag Definitions","description":"Manage environment-specific feature flag definitions (treatments, traffic allocation, targeting)."}],"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":{"FeatureFlagName":{"name":"feature-flag-name","in":"path","required":true,"description":"The unique name of the feature flag within the project. Names must begin with a letter\nand may contain letters, numbers, underscores, and hyphens. Use the same value that was\nsupplied as `name` when the flag was created. System-assigned ids are not accepted.\n","schema":{"type":"string","pattern":"^[A-Za-z][-_A-Za-z0-9]*$","maxLength":100}},"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}},"EnvironmentId":{"name":"environment_id","in":"query","required":true,"description":"Environment identifier. Scopes the request to a specific environment; combined with the\nresource name in the path it identifies a specific environment-scoped definition (e.g.,\na Feature Flag Definition or a Segment Definition).\n","schema":{"type":"string","format":"uuid","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":{"FeatureFlagDefinitionActionRequest":{"type":"object","description":"Optional metadata supplied when killing, restoring, or reallocating a feature flag definition.","properties":{"comment":{"type":"string","description":"Optional comment recorded with the action."},"title":{"type":"string","description":"Optional title recorded with the action."}}},"FeatureFlagDefinitionResponse":{"type":"object","description":"Feature Flag Definition entity together with the OPA governance result.","required":["entity","governance"],"properties":{"entity":{"$ref":"#/components/schemas/FeatureFlagDefinition"},"governance":{"allOf":[{"$ref":"#/components/schemas/GovernanceResult"}],"description":"OPA governance result for the mutation."}}},"FeatureFlagDefinition":{"type":"object","description":"An environment-specific Feature Flag Definition.","required":["id","featureFlag","environment","trafficType","isKilled","treatments","defaultTreatment","baselineTreatment","trafficAllocation","rules","defaultRule","createdAt","impressions"],"properties":{"id":{"type":"string","format":"uuid","description":"System-assigned identifier for this feature flag definition."},"featureFlag":{"allOf":[{"$ref":"#/components/schemas/NamedReference"}],"description":"Reference to the parent feature flag metadata."},"environment":{"allOf":[{"$ref":"#/components/schemas/NamedReference"}],"description":"Reference to the environment this definition is scoped to."},"trafficType":{"allOf":[{"$ref":"#/components/schemas/NamedReference"}],"description":"Reference to the traffic type used to bucket keys."},"isKilled":{"type":"boolean","readOnly":true,"description":"Whether the flag is killed in this environment. While killed, all traffic receives\n`defaultTreatment` regardless of rules. Response-only — use the dedicated kill/restore\nactions to change it.\n"},"treatments":{"type":"array","minItems":2,"description":"The treatments available for this flag in this environment.","items":{"$ref":"#/components/schemas/Treatment"}},"defaultTreatment":{"allOf":[{"$ref":"#/components/schemas/TreatmentName"}],"description":"Treatment served when the flag is killed, and to traffic outside `trafficAllocation`.\n"},"baselineTreatment":{"allOf":[{"$ref":"#/components/schemas/TreatmentName"}],"description":"Baseline treatment used as the control group for metrics calculations."},"trafficAllocation":{"type":"integer","format":"int32","minimum":0,"maximum":100,"description":"Percentage of total traffic that participates in this flag's evaluation. Traffic\noutside this allocation receives `defaultTreatment`.\n"},"rules":{"type":"array","description":"Ordered targeting rules. Empty means all traffic falls through to `defaultRule`.","items":{"$ref":"#/components/schemas/Rule"}},"defaultRule":{"type":"array","minItems":1,"description":"Distribution applied to in-allocation traffic that matches no targeting rule. Bucket\nsizes must sum to 100.\n","items":{"$ref":"#/components/schemas/Distribution"}},"flagSets":{"type":"array","description":"Flag sets associated with this definition. Empty means the definition belongs to no\nflag set. Assigned on create/PATCH; echoed on GET.\n","items":{"$ref":"#/components/schemas/FlagSetReference"}},"createdAt":{"type":"string","format":"date-time","description":"ISO-8601 timestamp when this definition was created."},"impressions":{"allOf":[{"$ref":"#/components/schemas/Impressions"}],"description":"Traffic/impression freshness data for this definition."}}},"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."}}},"Treatment":{"type":"object","description":"A single treatment (variation) of the feature flag in this environment.\n","required":["name"],"properties":{"name":{"allOf":[{"$ref":"#/components/schemas/TreatmentName"}],"description":"Treatment name. Must start with a letter or digit; remaining characters may be letters,\ndigits, hyphens, underscores, or periods. The reserved name `control` is not allowed.\n"},"description":{"type":"string","nullable":true,"description":"Optional description of this treatment."},"keys":{"type":"array","description":"Keys explicitly assigned to this treatment.","items":{"type":"string"}},"segments":{"type":"array","description":"Standard segment names assigned to this treatment.","items":{"type":"string","pattern":"^[A-Za-z][-_A-Za-z0-9]*$","maxLength":100}},"largeSegments":{"type":"array","description":"Large segment names assigned to this treatment.","items":{"type":"string","pattern":"^[A-Za-z][-_A-Za-z0-9]*$","maxLength":100}},"ruleBasedSegments":{"type":"array","description":"Rule-based segment names assigned to this treatment.","items":{"type":"string","pattern":"^[A-Za-z][-_A-Za-z0-9]*$","maxLength":100}},"configurations":{"type":"string","nullable":true,"description":"Dynamic configuration attached to this treatment, serialized as a JSON string.\n"}}},"TreatmentName":{"type":"string","pattern":"^[a-zA-Z0-9][-_\\.a-zA-Z0-9]*$","description":"Treatment name. Must start with a letter or digit; remaining characters may be letters,\ndigits, hyphens, underscores, or periods.\n"},"Rule":{"type":"object","description":"A targeting rule: a condition and the treatment buckets served on match.\n","required":["condition","buckets"],"properties":{"condition":{"$ref":"#/components/schemas/Condition"},"buckets":{"type":"array","minItems":1,"description":"Treatment buckets served when the condition matches. Sizes must sum to 100.\n","items":{"$ref":"#/components/schemas/Distribution"}}}},"Condition":{"type":"object","description":"The matching condition for a targeting rule. Only the `AND` combiner is supported — all\nmatchers must match. `OR` combination is not supported.\n","required":["combiner","matchers"],"properties":{"combiner":{"type":"string","enum":["AND"],"description":"Matcher combiner. Only `AND` is supported."},"matchers":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/Matcher"}}}},"Matcher":{"description":"A matcher within a targeting condition. Discriminated by `type` — each variant requires\nthe value field(s) that type evaluates. `negate` is optional on every variant (`true`\ninverts the result). `attribute` is required when the matcher evaluates a traffic-type\nattribute; omit it only for key-based list/string matchers (`IN_LIST_STRING`,\n`STARTS_WITH_STRING`, `ENDS_WITH_STRING`, `CONTAINS_STRING`, `MATCHES_STRING`).\n","oneOf":[{"$ref":"#/components/schemas/SegmentMatcher"},{"$ref":"#/components/schemas/SplitMatcher"},{"$ref":"#/components/schemas/BooleanMatcher"},{"$ref":"#/components/schemas/DateMatcher"},{"$ref":"#/components/schemas/BetweenDateMatcher"},{"$ref":"#/components/schemas/SetMatcher"},{"$ref":"#/components/schemas/NumberMatcher"},{"$ref":"#/components/schemas/BetweenNumberMatcher"},{"$ref":"#/components/schemas/InListStringMatcher"},{"$ref":"#/components/schemas/StringListMatcher"},{"$ref":"#/components/schemas/MatchesStringMatcher"},{"$ref":"#/components/schemas/SemverCompareMatcher"},{"$ref":"#/components/schemas/BetweenSemverMatcher"},{"$ref":"#/components/schemas/InListSemverMatcher"}],"discriminator":{"propertyName":"type","mapping":{"IN_SEGMENT":"#/components/schemas/SegmentMatcher","IN_LARGE_SEGMENT":"#/components/schemas/SegmentMatcher","IN_RULE_BASED_SEGMENT":"#/components/schemas/SegmentMatcher","IN_SPLIT":"#/components/schemas/SplitMatcher","BOOLEAN":"#/components/schemas/BooleanMatcher","ON_DATE":"#/components/schemas/DateMatcher","ON_OR_AFTER_DATE":"#/components/schemas/DateMatcher","ON_OR_BEFORE_DATE":"#/components/schemas/DateMatcher","BETWEEN_DATE":"#/components/schemas/BetweenDateMatcher","EQUAL_SET":"#/components/schemas/SetMatcher","ANY_OF_SET":"#/components/schemas/SetMatcher","ALL_OF_SET":"#/components/schemas/SetMatcher","PART_OF_SET":"#/components/schemas/SetMatcher","EQUAL_NUMBER":"#/components/schemas/NumberMatcher","LESS_THAN_OR_EQUAL_NUMBER":"#/components/schemas/NumberMatcher","GREATER_THAN_OR_EQUAL_NUMBER":"#/components/schemas/NumberMatcher","BETWEEN_NUMBER":"#/components/schemas/BetweenNumberMatcher","IN_LIST_STRING":"#/components/schemas/InListStringMatcher","STARTS_WITH_STRING":"#/components/schemas/StringListMatcher","ENDS_WITH_STRING":"#/components/schemas/StringListMatcher","CONTAINS_STRING":"#/components/schemas/StringListMatcher","MATCHES_STRING":"#/components/schemas/MatchesStringMatcher","EQUAL_TO_SEMVER":"#/components/schemas/SemverCompareMatcher","GREATER_THAN_OR_EQUAL_TO_SEMVER":"#/components/schemas/SemverCompareMatcher","LESS_THAN_OR_EQUAL_TO_SEMVER":"#/components/schemas/SemverCompareMatcher","BETWEEN_SEMVER":"#/components/schemas/BetweenSemverMatcher","IN_LIST_SEMVER":"#/components/schemas/InListSemverMatcher"}}},"SegmentMatcher":{"type":"object","additionalProperties":false,"description":"Key is in the named standard, large, or rule-based segment.","required":["type","string"],"properties":{"type":{"type":"string","enum":["IN_SEGMENT","IN_LARGE_SEGMENT","IN_RULE_BASED_SEGMENT"]},"negate":{"type":"boolean"},"string":{"type":"string","description":"Segment name."}}},"SplitMatcher":{"type":"object","additionalProperties":false,"description":"Prerequisite feature-flag (dependency) matcher.","required":["type","depends"],"properties":{"type":{"type":"string","enum":["IN_SPLIT"]},"negate":{"type":"boolean"},"depends":{"$ref":"#/components/schemas/Depends"}}},"Depends":{"type":"object","description":"Feature flag dependency matcher payload.","required":["splitName","treatments"],"properties":{"splitName":{"type":"string","pattern":"^[A-Za-z][-_A-Za-z0-9]*$","maxLength":100,"description":"Name of the prerequisite feature flag."},"treatments":{"type":"array","minItems":1,"description":"Treatments accepted from the prerequisite feature flag.","items":{"$ref":"#/components/schemas/TreatmentName"}}}},"BooleanMatcher":{"type":"object","additionalProperties":false,"description":"Attribute equals a boolean value.","required":["type","attribute","bool"],"properties":{"type":{"type":"string","enum":["BOOLEAN"]},"negate":{"type":"boolean"},"attribute":{"type":"string"},"bool":{"type":"boolean"}}},"DateMatcher":{"type":"object","additionalProperties":false,"description":"Attribute compared to a single epoch-millisecond timestamp.","required":["type","attribute","date"],"properties":{"type":{"type":"string","enum":["ON_DATE","ON_OR_AFTER_DATE","ON_OR_BEFORE_DATE"]},"negate":{"type":"boolean"},"attribute":{"type":"string"},"date":{"type":"integer","format":"int64","description":"Epoch milliseconds."}}},"BetweenDateMatcher":{"type":"object","additionalProperties":false,"description":"Attribute falls in an inclusive epoch-millisecond range.","required":["type","attribute","between"],"properties":{"type":{"type":"string","enum":["BETWEEN_DATE"]},"negate":{"type":"boolean"},"attribute":{"type":"string"},"between":{"$ref":"#/components/schemas/BetweenNumberAttribute"}}},"BetweenNumberAttribute":{"type":"object","description":"Inclusive numeric range for BETWEEN_NUMBER and BETWEEN_DATE matchers. Values are int64 — plain numbers for number matchers, epoch millis for date matchers. String/semver ranges use BetweenStringAttribute.\n","required":["from","to"],"properties":{"from":{"type":"integer","format":"int64"},"to":{"type":"integer","format":"int64"}}},"SetMatcher":{"type":"object","additionalProperties":false,"description":"Attribute set compared to a list of strings.","required":["type","attribute","strings"],"properties":{"type":{"type":"string","enum":["EQUAL_SET","ANY_OF_SET","ALL_OF_SET","PART_OF_SET"]},"negate":{"type":"boolean"},"attribute":{"type":"string"},"strings":{"type":"array","minItems":1,"items":{"type":"string"}}}},"NumberMatcher":{"type":"object","additionalProperties":false,"description":"Attribute compared to a single int64 number.","required":["type","attribute","number"],"properties":{"type":{"type":"string","enum":["EQUAL_NUMBER","LESS_THAN_OR_EQUAL_NUMBER","GREATER_THAN_OR_EQUAL_NUMBER"]},"negate":{"type":"boolean"},"attribute":{"type":"string"},"number":{"type":"integer","format":"int64"}}},"BetweenNumberMatcher":{"type":"object","additionalProperties":false,"description":"Attribute falls in an inclusive numeric range.","required":["type","attribute","between"],"properties":{"type":{"type":"string","enum":["BETWEEN_NUMBER"]},"negate":{"type":"boolean"},"attribute":{"type":"string"},"between":{"$ref":"#/components/schemas/BetweenNumberAttribute"}}},"InListStringMatcher":{"type":"object","additionalProperties":false,"description":"Value is in a string list. Omit `attribute` to match the key; set `attribute` to match\nthat traffic-type attribute.\n","required":["type","strings"],"properties":{"type":{"type":"string","enum":["IN_LIST_STRING"]},"negate":{"type":"boolean"},"attribute":{"type":"string"},"strings":{"type":"array","minItems":1,"items":{"type":"string"}}}},"StringListMatcher":{"type":"object","additionalProperties":false,"description":"Attribute (or key, if `attribute` is omitted) starts with, ends with, or contains any of\nthe listed strings.\n","required":["type","strings"],"properties":{"type":{"type":"string","enum":["STARTS_WITH_STRING","ENDS_WITH_STRING","CONTAINS_STRING"]},"negate":{"type":"boolean"},"attribute":{"type":"string"},"strings":{"type":"array","minItems":1,"items":{"type":"string"}}}},"MatchesStringMatcher":{"type":"object","additionalProperties":false,"description":"Attribute (or key, if `attribute` is omitted) matches a regular expression in `string`.\n","required":["type","string"],"properties":{"type":{"type":"string","enum":["MATCHES_STRING"]},"negate":{"type":"boolean"},"attribute":{"type":"string"},"string":{"type":"string","description":"Regular expression."}}},"SemverCompareMatcher":{"type":"object","additionalProperties":false,"description":"Attribute compared to a single semantic-version string.","required":["type","attribute","string"],"properties":{"type":{"type":"string","enum":["EQUAL_TO_SEMVER","GREATER_THAN_OR_EQUAL_TO_SEMVER","LESS_THAN_OR_EQUAL_TO_SEMVER"]},"negate":{"type":"boolean"},"attribute":{"type":"string"},"string":{"type":"string"}}},"BetweenSemverMatcher":{"type":"object","additionalProperties":false,"description":"Attribute falls in an inclusive semantic-version range.","required":["type","attribute","betweenString"],"properties":{"type":{"type":"string","enum":["BETWEEN_SEMVER"]},"negate":{"type":"boolean"},"attribute":{"type":"string"},"betweenString":{"$ref":"#/components/schemas/BetweenStringAttribute"}}},"BetweenStringAttribute":{"type":"object","description":"Inclusive string range for semantic-version BETWEEN matchers.","required":["from","to"],"properties":{"from":{"type":"string"},"to":{"type":"string"}}},"InListSemverMatcher":{"type":"object","additionalProperties":false,"description":"Attribute semantic version is in the listed versions.","required":["type","attribute","strings"],"properties":{"type":{"type":"string","enum":["IN_LIST_SEMVER"]},"negate":{"type":"boolean"},"attribute":{"type":"string"},"strings":{"type":"array","minItems":1,"items":{"type":"string"}}}},"Distribution":{"type":"object","description":"A percentage bucket assigning a share of traffic to a treatment. The treatment name must\nrefer to a treatment in the same definition.\n","required":["treatment","size"],"properties":{"treatment":{"allOf":[{"$ref":"#/components/schemas/TreatmentName"}],"description":"Treatment name from this definition."},"size":{"type":"integer","format":"int32","minimum":0,"maximum":100,"description":"Percentage of traffic assigned to the treatment (0-100)."}}},"FlagSetReference":{"type":"object","description":"Flag set associated with a feature flag definition. Used on create, update, and GET.\nIdentify the flag set by `id`. `name` is not accepted or returned.\n","required":["id"],"properties":{"id":{"type":"string","format":"uuid","description":"System-assigned identifier for the flag set."}}},"Impressions":{"type":"object","description":"Traffic/impression freshness data for this Feature Flag Definition.\n","required":["lastImpressionAt"],"properties":{"lastImpressionAt":{"type":"string","format":"date-time","nullable":true,"description":"Timestamp of the most recent impression recorded for this definition, or `null` if it\nhas never received traffic.\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/feature-flag-definitions/{feature-flag-name}/reallocate":{"post":{"tags":["Feature Flag Definitions"],"operationId":"reallocateFeatureFlagDefinition","summary":"Reallocate traffic for a Feature Flag Definition","description":"Requires `environment_id` as a query parameter. Re-hashes the traffic distribution for this\ndefinition so keys may move between treatment buckets. Cannot be called while the\ndefinition is killed (`400` `invalidState`). Unlike other mutations, reallocate does not\ncheck for pending change requests and does not require approvals.\n","parameters":[{"$ref":"#/components/parameters/FeatureFlagName"},{"$ref":"#/components/parameters/AccountId"},{"$ref":"#/components/parameters/EnvironmentId"},{"$ref":"#/components/parameters/OrganizationIdentifier"},{"$ref":"#/components/parameters/ProjectIdentifier"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeatureFlagDefinitionActionRequest"}}}},"responses":{"200":{"description":"OK — feature flag definition reallocated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeatureFlagDefinitionResponse"}}}},"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"}}}}}}
```

## Get a Feature Flag Definition

> Requires \`environment\_id\` as a query parameter. Returns a single Feature Flag Definition\
> for the specified feature flag in the specified environment.<br>

```json
{"openapi":"3.0.3","info":{"title":"Harness Feature Management & Experimentation API","version":"4.0.0"},"tags":[{"name":"Feature Flag Definitions","description":"Manage environment-specific feature flag definitions (treatments, traffic allocation, targeting)."}],"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":{"FeatureFlagName":{"name":"feature-flag-name","in":"path","required":true,"description":"The unique name of the feature flag within the project. Names must begin with a letter\nand may contain letters, numbers, underscores, and hyphens. Use the same value that was\nsupplied as `name` when the flag was created. System-assigned ids are not accepted.\n","schema":{"type":"string","pattern":"^[A-Za-z][-_A-Za-z0-9]*$","maxLength":100}},"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}},"EnvironmentId":{"name":"environment_id","in":"query","required":true,"description":"Environment identifier. Scopes the request to a specific environment; combined with the\nresource name in the path it identifies a specific environment-scoped definition (e.g.,\na Feature Flag Definition or a Segment Definition).\n","schema":{"type":"string","format":"uuid","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":{"FeatureFlagDefinition":{"type":"object","description":"An environment-specific Feature Flag Definition.","required":["id","featureFlag","environment","trafficType","isKilled","treatments","defaultTreatment","baselineTreatment","trafficAllocation","rules","defaultRule","createdAt","impressions"],"properties":{"id":{"type":"string","format":"uuid","description":"System-assigned identifier for this feature flag definition."},"featureFlag":{"allOf":[{"$ref":"#/components/schemas/NamedReference"}],"description":"Reference to the parent feature flag metadata."},"environment":{"allOf":[{"$ref":"#/components/schemas/NamedReference"}],"description":"Reference to the environment this definition is scoped to."},"trafficType":{"allOf":[{"$ref":"#/components/schemas/NamedReference"}],"description":"Reference to the traffic type used to bucket keys."},"isKilled":{"type":"boolean","readOnly":true,"description":"Whether the flag is killed in this environment. While killed, all traffic receives\n`defaultTreatment` regardless of rules. Response-only — use the dedicated kill/restore\nactions to change it.\n"},"treatments":{"type":"array","minItems":2,"description":"The treatments available for this flag in this environment.","items":{"$ref":"#/components/schemas/Treatment"}},"defaultTreatment":{"allOf":[{"$ref":"#/components/schemas/TreatmentName"}],"description":"Treatment served when the flag is killed, and to traffic outside `trafficAllocation`.\n"},"baselineTreatment":{"allOf":[{"$ref":"#/components/schemas/TreatmentName"}],"description":"Baseline treatment used as the control group for metrics calculations."},"trafficAllocation":{"type":"integer","format":"int32","minimum":0,"maximum":100,"description":"Percentage of total traffic that participates in this flag's evaluation. Traffic\noutside this allocation receives `defaultTreatment`.\n"},"rules":{"type":"array","description":"Ordered targeting rules. Empty means all traffic falls through to `defaultRule`.","items":{"$ref":"#/components/schemas/Rule"}},"defaultRule":{"type":"array","minItems":1,"description":"Distribution applied to in-allocation traffic that matches no targeting rule. Bucket\nsizes must sum to 100.\n","items":{"$ref":"#/components/schemas/Distribution"}},"flagSets":{"type":"array","description":"Flag sets associated with this definition. Empty means the definition belongs to no\nflag set. Assigned on create/PATCH; echoed on GET.\n","items":{"$ref":"#/components/schemas/FlagSetReference"}},"createdAt":{"type":"string","format":"date-time","description":"ISO-8601 timestamp when this definition was created."},"impressions":{"allOf":[{"$ref":"#/components/schemas/Impressions"}],"description":"Traffic/impression freshness data for this definition."}}},"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."}}},"Treatment":{"type":"object","description":"A single treatment (variation) of the feature flag in this environment.\n","required":["name"],"properties":{"name":{"allOf":[{"$ref":"#/components/schemas/TreatmentName"}],"description":"Treatment name. Must start with a letter or digit; remaining characters may be letters,\ndigits, hyphens, underscores, or periods. The reserved name `control` is not allowed.\n"},"description":{"type":"string","nullable":true,"description":"Optional description of this treatment."},"keys":{"type":"array","description":"Keys explicitly assigned to this treatment.","items":{"type":"string"}},"segments":{"type":"array","description":"Standard segment names assigned to this treatment.","items":{"type":"string","pattern":"^[A-Za-z][-_A-Za-z0-9]*$","maxLength":100}},"largeSegments":{"type":"array","description":"Large segment names assigned to this treatment.","items":{"type":"string","pattern":"^[A-Za-z][-_A-Za-z0-9]*$","maxLength":100}},"ruleBasedSegments":{"type":"array","description":"Rule-based segment names assigned to this treatment.","items":{"type":"string","pattern":"^[A-Za-z][-_A-Za-z0-9]*$","maxLength":100}},"configurations":{"type":"string","nullable":true,"description":"Dynamic configuration attached to this treatment, serialized as a JSON string.\n"}}},"TreatmentName":{"type":"string","pattern":"^[a-zA-Z0-9][-_\\.a-zA-Z0-9]*$","description":"Treatment name. Must start with a letter or digit; remaining characters may be letters,\ndigits, hyphens, underscores, or periods.\n"},"Rule":{"type":"object","description":"A targeting rule: a condition and the treatment buckets served on match.\n","required":["condition","buckets"],"properties":{"condition":{"$ref":"#/components/schemas/Condition"},"buckets":{"type":"array","minItems":1,"description":"Treatment buckets served when the condition matches. Sizes must sum to 100.\n","items":{"$ref":"#/components/schemas/Distribution"}}}},"Condition":{"type":"object","description":"The matching condition for a targeting rule. Only the `AND` combiner is supported — all\nmatchers must match. `OR` combination is not supported.\n","required":["combiner","matchers"],"properties":{"combiner":{"type":"string","enum":["AND"],"description":"Matcher combiner. Only `AND` is supported."},"matchers":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/Matcher"}}}},"Matcher":{"description":"A matcher within a targeting condition. Discriminated by `type` — each variant requires\nthe value field(s) that type evaluates. `negate` is optional on every variant (`true`\ninverts the result). `attribute` is required when the matcher evaluates a traffic-type\nattribute; omit it only for key-based list/string matchers (`IN_LIST_STRING`,\n`STARTS_WITH_STRING`, `ENDS_WITH_STRING`, `CONTAINS_STRING`, `MATCHES_STRING`).\n","oneOf":[{"$ref":"#/components/schemas/SegmentMatcher"},{"$ref":"#/components/schemas/SplitMatcher"},{"$ref":"#/components/schemas/BooleanMatcher"},{"$ref":"#/components/schemas/DateMatcher"},{"$ref":"#/components/schemas/BetweenDateMatcher"},{"$ref":"#/components/schemas/SetMatcher"},{"$ref":"#/components/schemas/NumberMatcher"},{"$ref":"#/components/schemas/BetweenNumberMatcher"},{"$ref":"#/components/schemas/InListStringMatcher"},{"$ref":"#/components/schemas/StringListMatcher"},{"$ref":"#/components/schemas/MatchesStringMatcher"},{"$ref":"#/components/schemas/SemverCompareMatcher"},{"$ref":"#/components/schemas/BetweenSemverMatcher"},{"$ref":"#/components/schemas/InListSemverMatcher"}],"discriminator":{"propertyName":"type","mapping":{"IN_SEGMENT":"#/components/schemas/SegmentMatcher","IN_LARGE_SEGMENT":"#/components/schemas/SegmentMatcher","IN_RULE_BASED_SEGMENT":"#/components/schemas/SegmentMatcher","IN_SPLIT":"#/components/schemas/SplitMatcher","BOOLEAN":"#/components/schemas/BooleanMatcher","ON_DATE":"#/components/schemas/DateMatcher","ON_OR_AFTER_DATE":"#/components/schemas/DateMatcher","ON_OR_BEFORE_DATE":"#/components/schemas/DateMatcher","BETWEEN_DATE":"#/components/schemas/BetweenDateMatcher","EQUAL_SET":"#/components/schemas/SetMatcher","ANY_OF_SET":"#/components/schemas/SetMatcher","ALL_OF_SET":"#/components/schemas/SetMatcher","PART_OF_SET":"#/components/schemas/SetMatcher","EQUAL_NUMBER":"#/components/schemas/NumberMatcher","LESS_THAN_OR_EQUAL_NUMBER":"#/components/schemas/NumberMatcher","GREATER_THAN_OR_EQUAL_NUMBER":"#/components/schemas/NumberMatcher","BETWEEN_NUMBER":"#/components/schemas/BetweenNumberMatcher","IN_LIST_STRING":"#/components/schemas/InListStringMatcher","STARTS_WITH_STRING":"#/components/schemas/StringListMatcher","ENDS_WITH_STRING":"#/components/schemas/StringListMatcher","CONTAINS_STRING":"#/components/schemas/StringListMatcher","MATCHES_STRING":"#/components/schemas/MatchesStringMatcher","EQUAL_TO_SEMVER":"#/components/schemas/SemverCompareMatcher","GREATER_THAN_OR_EQUAL_TO_SEMVER":"#/components/schemas/SemverCompareMatcher","LESS_THAN_OR_EQUAL_TO_SEMVER":"#/components/schemas/SemverCompareMatcher","BETWEEN_SEMVER":"#/components/schemas/BetweenSemverMatcher","IN_LIST_SEMVER":"#/components/schemas/InListSemverMatcher"}}},"SegmentMatcher":{"type":"object","additionalProperties":false,"description":"Key is in the named standard, large, or rule-based segment.","required":["type","string"],"properties":{"type":{"type":"string","enum":["IN_SEGMENT","IN_LARGE_SEGMENT","IN_RULE_BASED_SEGMENT"]},"negate":{"type":"boolean"},"string":{"type":"string","description":"Segment name."}}},"SplitMatcher":{"type":"object","additionalProperties":false,"description":"Prerequisite feature-flag (dependency) matcher.","required":["type","depends"],"properties":{"type":{"type":"string","enum":["IN_SPLIT"]},"negate":{"type":"boolean"},"depends":{"$ref":"#/components/schemas/Depends"}}},"Depends":{"type":"object","description":"Feature flag dependency matcher payload.","required":["splitName","treatments"],"properties":{"splitName":{"type":"string","pattern":"^[A-Za-z][-_A-Za-z0-9]*$","maxLength":100,"description":"Name of the prerequisite feature flag."},"treatments":{"type":"array","minItems":1,"description":"Treatments accepted from the prerequisite feature flag.","items":{"$ref":"#/components/schemas/TreatmentName"}}}},"BooleanMatcher":{"type":"object","additionalProperties":false,"description":"Attribute equals a boolean value.","required":["type","attribute","bool"],"properties":{"type":{"type":"string","enum":["BOOLEAN"]},"negate":{"type":"boolean"},"attribute":{"type":"string"},"bool":{"type":"boolean"}}},"DateMatcher":{"type":"object","additionalProperties":false,"description":"Attribute compared to a single epoch-millisecond timestamp.","required":["type","attribute","date"],"properties":{"type":{"type":"string","enum":["ON_DATE","ON_OR_AFTER_DATE","ON_OR_BEFORE_DATE"]},"negate":{"type":"boolean"},"attribute":{"type":"string"},"date":{"type":"integer","format":"int64","description":"Epoch milliseconds."}}},"BetweenDateMatcher":{"type":"object","additionalProperties":false,"description":"Attribute falls in an inclusive epoch-millisecond range.","required":["type","attribute","between"],"properties":{"type":{"type":"string","enum":["BETWEEN_DATE"]},"negate":{"type":"boolean"},"attribute":{"type":"string"},"between":{"$ref":"#/components/schemas/BetweenNumberAttribute"}}},"BetweenNumberAttribute":{"type":"object","description":"Inclusive numeric range for BETWEEN_NUMBER and BETWEEN_DATE matchers. Values are int64 — plain numbers for number matchers, epoch millis for date matchers. String/semver ranges use BetweenStringAttribute.\n","required":["from","to"],"properties":{"from":{"type":"integer","format":"int64"},"to":{"type":"integer","format":"int64"}}},"SetMatcher":{"type":"object","additionalProperties":false,"description":"Attribute set compared to a list of strings.","required":["type","attribute","strings"],"properties":{"type":{"type":"string","enum":["EQUAL_SET","ANY_OF_SET","ALL_OF_SET","PART_OF_SET"]},"negate":{"type":"boolean"},"attribute":{"type":"string"},"strings":{"type":"array","minItems":1,"items":{"type":"string"}}}},"NumberMatcher":{"type":"object","additionalProperties":false,"description":"Attribute compared to a single int64 number.","required":["type","attribute","number"],"properties":{"type":{"type":"string","enum":["EQUAL_NUMBER","LESS_THAN_OR_EQUAL_NUMBER","GREATER_THAN_OR_EQUAL_NUMBER"]},"negate":{"type":"boolean"},"attribute":{"type":"string"},"number":{"type":"integer","format":"int64"}}},"BetweenNumberMatcher":{"type":"object","additionalProperties":false,"description":"Attribute falls in an inclusive numeric range.","required":["type","attribute","between"],"properties":{"type":{"type":"string","enum":["BETWEEN_NUMBER"]},"negate":{"type":"boolean"},"attribute":{"type":"string"},"between":{"$ref":"#/components/schemas/BetweenNumberAttribute"}}},"InListStringMatcher":{"type":"object","additionalProperties":false,"description":"Value is in a string list. Omit `attribute` to match the key; set `attribute` to match\nthat traffic-type attribute.\n","required":["type","strings"],"properties":{"type":{"type":"string","enum":["IN_LIST_STRING"]},"negate":{"type":"boolean"},"attribute":{"type":"string"},"strings":{"type":"array","minItems":1,"items":{"type":"string"}}}},"StringListMatcher":{"type":"object","additionalProperties":false,"description":"Attribute (or key, if `attribute` is omitted) starts with, ends with, or contains any of\nthe listed strings.\n","required":["type","strings"],"properties":{"type":{"type":"string","enum":["STARTS_WITH_STRING","ENDS_WITH_STRING","CONTAINS_STRING"]},"negate":{"type":"boolean"},"attribute":{"type":"string"},"strings":{"type":"array","minItems":1,"items":{"type":"string"}}}},"MatchesStringMatcher":{"type":"object","additionalProperties":false,"description":"Attribute (or key, if `attribute` is omitted) matches a regular expression in `string`.\n","required":["type","string"],"properties":{"type":{"type":"string","enum":["MATCHES_STRING"]},"negate":{"type":"boolean"},"attribute":{"type":"string"},"string":{"type":"string","description":"Regular expression."}}},"SemverCompareMatcher":{"type":"object","additionalProperties":false,"description":"Attribute compared to a single semantic-version string.","required":["type","attribute","string"],"properties":{"type":{"type":"string","enum":["EQUAL_TO_SEMVER","GREATER_THAN_OR_EQUAL_TO_SEMVER","LESS_THAN_OR_EQUAL_TO_SEMVER"]},"negate":{"type":"boolean"},"attribute":{"type":"string"},"string":{"type":"string"}}},"BetweenSemverMatcher":{"type":"object","additionalProperties":false,"description":"Attribute falls in an inclusive semantic-version range.","required":["type","attribute","betweenString"],"properties":{"type":{"type":"string","enum":["BETWEEN_SEMVER"]},"negate":{"type":"boolean"},"attribute":{"type":"string"},"betweenString":{"$ref":"#/components/schemas/BetweenStringAttribute"}}},"BetweenStringAttribute":{"type":"object","description":"Inclusive string range for semantic-version BETWEEN matchers.","required":["from","to"],"properties":{"from":{"type":"string"},"to":{"type":"string"}}},"InListSemverMatcher":{"type":"object","additionalProperties":false,"description":"Attribute semantic version is in the listed versions.","required":["type","attribute","strings"],"properties":{"type":{"type":"string","enum":["IN_LIST_SEMVER"]},"negate":{"type":"boolean"},"attribute":{"type":"string"},"strings":{"type":"array","minItems":1,"items":{"type":"string"}}}},"Distribution":{"type":"object","description":"A percentage bucket assigning a share of traffic to a treatment. The treatment name must\nrefer to a treatment in the same definition.\n","required":["treatment","size"],"properties":{"treatment":{"allOf":[{"$ref":"#/components/schemas/TreatmentName"}],"description":"Treatment name from this definition."},"size":{"type":"integer","format":"int32","minimum":0,"maximum":100,"description":"Percentage of traffic assigned to the treatment (0-100)."}}},"FlagSetReference":{"type":"object","description":"Flag set associated with a feature flag definition. Used on create, update, and GET.\nIdentify the flag set by `id`. `name` is not accepted or returned.\n","required":["id"],"properties":{"id":{"type":"string","format":"uuid","description":"System-assigned identifier for the flag set."}}},"Impressions":{"type":"object","description":"Traffic/impression freshness data for this Feature Flag Definition.\n","required":["lastImpressionAt"],"properties":{"lastImpressionAt":{"type":"string","format":"date-time","nullable":true,"description":"Timestamp of the most recent impression recorded for this definition, or `null` if it\nhas never received traffic.\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/feature-flag-definitions/{feature-flag-name}":{"get":{"tags":["Feature Flag Definitions"],"operationId":"getFeatureFlagDefinition","summary":"Get a Feature Flag Definition","description":"Requires `environment_id` as a query parameter. Returns a single Feature Flag Definition\nfor the specified feature flag in the specified environment.\n","parameters":[{"$ref":"#/components/parameters/FeatureFlagName"},{"$ref":"#/components/parameters/AccountId"},{"$ref":"#/components/parameters/EnvironmentId"},{"$ref":"#/components/parameters/OrganizationIdentifier"},{"$ref":"#/components/parameters/ProjectIdentifier"}],"responses":{"200":{"description":"OK — feature flag definition returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeatureFlagDefinition"}}}},"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"}}}}}}
```

## Create a Feature Flag Definition

> Requires \`environment\_id\` as a query parameter. Creates a new Feature Flag Definition for\
> the specified feature flag in the specified environment. A definition must not already exist\
> for this feature flag + environment combination (\`409\` on conflict). When the environment\
> requires approval, returns \`403\`. Optional \`flagSets\` associates the definition with\
> existing flag sets by id.<br>

```json
{"openapi":"3.0.3","info":{"title":"Harness Feature Management & Experimentation API","version":"4.0.0"},"tags":[{"name":"Feature Flag Definitions","description":"Manage environment-specific feature flag definitions (treatments, traffic allocation, targeting)."}],"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":{"FeatureFlagName":{"name":"feature-flag-name","in":"path","required":true,"description":"The unique name of the feature flag within the project. Names must begin with a letter\nand may contain letters, numbers, underscores, and hyphens. Use the same value that was\nsupplied as `name` when the flag was created. System-assigned ids are not accepted.\n","schema":{"type":"string","pattern":"^[A-Za-z][-_A-Za-z0-9]*$","maxLength":100}},"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}},"EnvironmentId":{"name":"environment_id","in":"query","required":true,"description":"Environment identifier. Scopes the request to a specific environment; combined with the\nresource name in the path it identifies a specific environment-scoped definition (e.g.,\na Feature Flag Definition or a Segment Definition).\n","schema":{"type":"string","format":"uuid","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":{"CreateFeatureFlagDefinitionRequest":{"type":"object","description":"Request body for creating a Feature Flag Definition for the specified feature flag in the\nspecified environment.\n","required":["treatments","defaultTreatment","defaultRule"],"properties":{"treatments":{"type":"array","minItems":2,"description":"The treatments (variations) for this flag in this environment.\n","items":{"$ref":"#/components/schemas/TreatmentInput"}},"defaultTreatment":{"allOf":[{"$ref":"#/components/schemas/TreatmentName"}],"description":"Treatment served when the flag is killed, and to traffic outside `trafficAllocation`.\n"},"baselineTreatment":{"allOf":[{"$ref":"#/components/schemas/TreatmentName"}],"description":"Treatment used as the baseline for metrics calculations. Optional; when omitted the\nserver defaults it to `defaultTreatment`.\n"},"trafficAllocation":{"type":"integer","format":"int32","minimum":0,"maximum":100,"default":100,"description":"Percentage of traffic exposed to targeting (traffic allocation). Defaults to 100."},"rules":{"type":"array","description":"Ordered targeting rules evaluated before `defaultRule`.","items":{"$ref":"#/components/schemas/RuleInput"}},"defaultRule":{"type":"array","minItems":1,"description":"Distribution served to in-allocation traffic that matches no targeting rule. Bucket\nsizes must sum to 100. Required on create — callers must supply at least one bucket\n(typically 100% on `defaultTreatment`).\n","items":{"$ref":"#/components/schemas/DistributionInput"}},"flagSets":{"type":"array","description":"Flag sets to associate with this definition. Optional; omit or `[]` means no\nassociations. Each item is `{id, type}` with `type` = `FLAG_SET`.\n","items":{"$ref":"#/components/schemas/FlagSetReference"}},"comment":{"type":"string","description":"Optional audit comment recorded with the create."},"title":{"type":"string","description":"Optional audit title recorded with the create."}}},"TreatmentInput":{"type":"object","description":"Treatment input used in create and patch request bodies. The default treatment is selected\nwith the request-level `defaultTreatment` field.\n","required":["name"],"properties":{"name":{"allOf":[{"$ref":"#/components/schemas/TreatmentName"}],"description":"Treatment name. Must start with a letter or digit; remaining characters may be letters,\ndigits, hyphens, underscores, or periods. The reserved name `control` is not allowed.\n"},"description":{"type":"string","nullable":true,"description":"Optional description of this treatment."},"keys":{"type":"array","description":"Keys explicitly assigned to this treatment.","items":{"type":"string"}},"segments":{"type":"array","description":"Standard segment names assigned to this treatment.","items":{"type":"string","pattern":"^[A-Za-z][-_A-Za-z0-9]*$","maxLength":100}},"largeSegments":{"type":"array","description":"Large segment names assigned to this treatment.","items":{"type":"string","pattern":"^[A-Za-z][-_A-Za-z0-9]*$","maxLength":100}},"ruleBasedSegments":{"type":"array","description":"Rule-based segment names assigned to this treatment.","items":{"type":"string","pattern":"^[A-Za-z][-_A-Za-z0-9]*$","maxLength":100}},"configurations":{"type":"string","nullable":true,"description":"Dynamic configuration attached to this treatment, serialized as a JSON string.\n"}}},"TreatmentName":{"type":"string","pattern":"^[a-zA-Z0-9][-_\\.a-zA-Z0-9]*$","description":"Treatment name. Must start with a letter or digit; remaining characters may be letters,\ndigits, hyphens, underscores, or periods.\n"},"RuleInput":{"type":"object","description":"Targeting rule for create/patch request bodies. Buckets use `DistributionInput`.","required":["condition","buckets"],"properties":{"condition":{"$ref":"#/components/schemas/ConditionInput"},"buckets":{"type":"array","minItems":1,"description":"Treatment buckets served when the condition matches. Sizes must sum to 100.\n","items":{"$ref":"#/components/schemas/DistributionInput"}}}},"ConditionInput":{"type":"object","description":"Targeting condition for create/patch request bodies. If `combiner` is omitted, the server\ntreats it as `AND`.\n","required":["matchers"],"properties":{"combiner":{"type":"string","enum":["AND"],"default":"AND","description":"Matcher combiner. Only `AND` is supported; defaults to `AND` when omitted."},"matchers":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/Matcher"}}}},"Matcher":{"description":"A matcher within a targeting condition. Discriminated by `type` — each variant requires\nthe value field(s) that type evaluates. `negate` is optional on every variant (`true`\ninverts the result). `attribute` is required when the matcher evaluates a traffic-type\nattribute; omit it only for key-based list/string matchers (`IN_LIST_STRING`,\n`STARTS_WITH_STRING`, `ENDS_WITH_STRING`, `CONTAINS_STRING`, `MATCHES_STRING`).\n","oneOf":[{"$ref":"#/components/schemas/SegmentMatcher"},{"$ref":"#/components/schemas/SplitMatcher"},{"$ref":"#/components/schemas/BooleanMatcher"},{"$ref":"#/components/schemas/DateMatcher"},{"$ref":"#/components/schemas/BetweenDateMatcher"},{"$ref":"#/components/schemas/SetMatcher"},{"$ref":"#/components/schemas/NumberMatcher"},{"$ref":"#/components/schemas/BetweenNumberMatcher"},{"$ref":"#/components/schemas/InListStringMatcher"},{"$ref":"#/components/schemas/StringListMatcher"},{"$ref":"#/components/schemas/MatchesStringMatcher"},{"$ref":"#/components/schemas/SemverCompareMatcher"},{"$ref":"#/components/schemas/BetweenSemverMatcher"},{"$ref":"#/components/schemas/InListSemverMatcher"}],"discriminator":{"propertyName":"type","mapping":{"IN_SEGMENT":"#/components/schemas/SegmentMatcher","IN_LARGE_SEGMENT":"#/components/schemas/SegmentMatcher","IN_RULE_BASED_SEGMENT":"#/components/schemas/SegmentMatcher","IN_SPLIT":"#/components/schemas/SplitMatcher","BOOLEAN":"#/components/schemas/BooleanMatcher","ON_DATE":"#/components/schemas/DateMatcher","ON_OR_AFTER_DATE":"#/components/schemas/DateMatcher","ON_OR_BEFORE_DATE":"#/components/schemas/DateMatcher","BETWEEN_DATE":"#/components/schemas/BetweenDateMatcher","EQUAL_SET":"#/components/schemas/SetMatcher","ANY_OF_SET":"#/components/schemas/SetMatcher","ALL_OF_SET":"#/components/schemas/SetMatcher","PART_OF_SET":"#/components/schemas/SetMatcher","EQUAL_NUMBER":"#/components/schemas/NumberMatcher","LESS_THAN_OR_EQUAL_NUMBER":"#/components/schemas/NumberMatcher","GREATER_THAN_OR_EQUAL_NUMBER":"#/components/schemas/NumberMatcher","BETWEEN_NUMBER":"#/components/schemas/BetweenNumberMatcher","IN_LIST_STRING":"#/components/schemas/InListStringMatcher","STARTS_WITH_STRING":"#/components/schemas/StringListMatcher","ENDS_WITH_STRING":"#/components/schemas/StringListMatcher","CONTAINS_STRING":"#/components/schemas/StringListMatcher","MATCHES_STRING":"#/components/schemas/MatchesStringMatcher","EQUAL_TO_SEMVER":"#/components/schemas/SemverCompareMatcher","GREATER_THAN_OR_EQUAL_TO_SEMVER":"#/components/schemas/SemverCompareMatcher","LESS_THAN_OR_EQUAL_TO_SEMVER":"#/components/schemas/SemverCompareMatcher","BETWEEN_SEMVER":"#/components/schemas/BetweenSemverMatcher","IN_LIST_SEMVER":"#/components/schemas/InListSemverMatcher"}}},"SegmentMatcher":{"type":"object","additionalProperties":false,"description":"Key is in the named standard, large, or rule-based segment.","required":["type","string"],"properties":{"type":{"type":"string","enum":["IN_SEGMENT","IN_LARGE_SEGMENT","IN_RULE_BASED_SEGMENT"]},"negate":{"type":"boolean"},"string":{"type":"string","description":"Segment name."}}},"SplitMatcher":{"type":"object","additionalProperties":false,"description":"Prerequisite feature-flag (dependency) matcher.","required":["type","depends"],"properties":{"type":{"type":"string","enum":["IN_SPLIT"]},"negate":{"type":"boolean"},"depends":{"$ref":"#/components/schemas/Depends"}}},"Depends":{"type":"object","description":"Feature flag dependency matcher payload.","required":["splitName","treatments"],"properties":{"splitName":{"type":"string","pattern":"^[A-Za-z][-_A-Za-z0-9]*$","maxLength":100,"description":"Name of the prerequisite feature flag."},"treatments":{"type":"array","minItems":1,"description":"Treatments accepted from the prerequisite feature flag.","items":{"$ref":"#/components/schemas/TreatmentName"}}}},"BooleanMatcher":{"type":"object","additionalProperties":false,"description":"Attribute equals a boolean value.","required":["type","attribute","bool"],"properties":{"type":{"type":"string","enum":["BOOLEAN"]},"negate":{"type":"boolean"},"attribute":{"type":"string"},"bool":{"type":"boolean"}}},"DateMatcher":{"type":"object","additionalProperties":false,"description":"Attribute compared to a single epoch-millisecond timestamp.","required":["type","attribute","date"],"properties":{"type":{"type":"string","enum":["ON_DATE","ON_OR_AFTER_DATE","ON_OR_BEFORE_DATE"]},"negate":{"type":"boolean"},"attribute":{"type":"string"},"date":{"type":"integer","format":"int64","description":"Epoch milliseconds."}}},"BetweenDateMatcher":{"type":"object","additionalProperties":false,"description":"Attribute falls in an inclusive epoch-millisecond range.","required":["type","attribute","between"],"properties":{"type":{"type":"string","enum":["BETWEEN_DATE"]},"negate":{"type":"boolean"},"attribute":{"type":"string"},"between":{"$ref":"#/components/schemas/BetweenNumberAttribute"}}},"BetweenNumberAttribute":{"type":"object","description":"Inclusive numeric range for BETWEEN_NUMBER and BETWEEN_DATE matchers. Values are int64 — plain numbers for number matchers, epoch millis for date matchers. String/semver ranges use BetweenStringAttribute.\n","required":["from","to"],"properties":{"from":{"type":"integer","format":"int64"},"to":{"type":"integer","format":"int64"}}},"SetMatcher":{"type":"object","additionalProperties":false,"description":"Attribute set compared to a list of strings.","required":["type","attribute","strings"],"properties":{"type":{"type":"string","enum":["EQUAL_SET","ANY_OF_SET","ALL_OF_SET","PART_OF_SET"]},"negate":{"type":"boolean"},"attribute":{"type":"string"},"strings":{"type":"array","minItems":1,"items":{"type":"string"}}}},"NumberMatcher":{"type":"object","additionalProperties":false,"description":"Attribute compared to a single int64 number.","required":["type","attribute","number"],"properties":{"type":{"type":"string","enum":["EQUAL_NUMBER","LESS_THAN_OR_EQUAL_NUMBER","GREATER_THAN_OR_EQUAL_NUMBER"]},"negate":{"type":"boolean"},"attribute":{"type":"string"},"number":{"type":"integer","format":"int64"}}},"BetweenNumberMatcher":{"type":"object","additionalProperties":false,"description":"Attribute falls in an inclusive numeric range.","required":["type","attribute","between"],"properties":{"type":{"type":"string","enum":["BETWEEN_NUMBER"]},"negate":{"type":"boolean"},"attribute":{"type":"string"},"between":{"$ref":"#/components/schemas/BetweenNumberAttribute"}}},"InListStringMatcher":{"type":"object","additionalProperties":false,"description":"Value is in a string list. Omit `attribute` to match the key; set `attribute` to match\nthat traffic-type attribute.\n","required":["type","strings"],"properties":{"type":{"type":"string","enum":["IN_LIST_STRING"]},"negate":{"type":"boolean"},"attribute":{"type":"string"},"strings":{"type":"array","minItems":1,"items":{"type":"string"}}}},"StringListMatcher":{"type":"object","additionalProperties":false,"description":"Attribute (or key, if `attribute` is omitted) starts with, ends with, or contains any of\nthe listed strings.\n","required":["type","strings"],"properties":{"type":{"type":"string","enum":["STARTS_WITH_STRING","ENDS_WITH_STRING","CONTAINS_STRING"]},"negate":{"type":"boolean"},"attribute":{"type":"string"},"strings":{"type":"array","minItems":1,"items":{"type":"string"}}}},"MatchesStringMatcher":{"type":"object","additionalProperties":false,"description":"Attribute (or key, if `attribute` is omitted) matches a regular expression in `string`.\n","required":["type","string"],"properties":{"type":{"type":"string","enum":["MATCHES_STRING"]},"negate":{"type":"boolean"},"attribute":{"type":"string"},"string":{"type":"string","description":"Regular expression."}}},"SemverCompareMatcher":{"type":"object","additionalProperties":false,"description":"Attribute compared to a single semantic-version string.","required":["type","attribute","string"],"properties":{"type":{"type":"string","enum":["EQUAL_TO_SEMVER","GREATER_THAN_OR_EQUAL_TO_SEMVER","LESS_THAN_OR_EQUAL_TO_SEMVER"]},"negate":{"type":"boolean"},"attribute":{"type":"string"},"string":{"type":"string"}}},"BetweenSemverMatcher":{"type":"object","additionalProperties":false,"description":"Attribute falls in an inclusive semantic-version range.","required":["type","attribute","betweenString"],"properties":{"type":{"type":"string","enum":["BETWEEN_SEMVER"]},"negate":{"type":"boolean"},"attribute":{"type":"string"},"betweenString":{"$ref":"#/components/schemas/BetweenStringAttribute"}}},"BetweenStringAttribute":{"type":"object","description":"Inclusive string range for semantic-version BETWEEN matchers.","required":["from","to"],"properties":{"from":{"type":"string"},"to":{"type":"string"}}},"InListSemverMatcher":{"type":"object","additionalProperties":false,"description":"Attribute semantic version is in the listed versions.","required":["type","attribute","strings"],"properties":{"type":{"type":"string","enum":["IN_LIST_SEMVER"]},"negate":{"type":"boolean"},"attribute":{"type":"string"},"strings":{"type":"array","minItems":1,"items":{"type":"string"}}}},"DistributionInput":{"type":"object","description":"Distribution input used in create and patch request bodies. The treatment name must refer\nto a treatment in the same request/definition.\n","required":["treatment","size"],"properties":{"treatment":{"allOf":[{"$ref":"#/components/schemas/TreatmentName"}],"description":"Treatment name from this definition."},"size":{"type":"integer","format":"int32","minimum":0,"maximum":100,"description":"Percentage of traffic assigned to the treatment (0-100)."}}},"FlagSetReference":{"type":"object","description":"Flag set associated with a feature flag definition. Used on create, update, and GET.\nIdentify the flag set by `id`. `name` is not accepted or returned.\n","required":["id"],"properties":{"id":{"type":"string","format":"uuid","description":"System-assigned identifier for the flag set."}}},"FeatureFlagDefinitionResponse":{"type":"object","description":"Feature Flag Definition entity together with the OPA governance result.","required":["entity","governance"],"properties":{"entity":{"$ref":"#/components/schemas/FeatureFlagDefinition"},"governance":{"allOf":[{"$ref":"#/components/schemas/GovernanceResult"}],"description":"OPA governance result for the mutation."}}},"FeatureFlagDefinition":{"type":"object","description":"An environment-specific Feature Flag Definition.","required":["id","featureFlag","environment","trafficType","isKilled","treatments","defaultTreatment","baselineTreatment","trafficAllocation","rules","defaultRule","createdAt","impressions"],"properties":{"id":{"type":"string","format":"uuid","description":"System-assigned identifier for this feature flag definition."},"featureFlag":{"allOf":[{"$ref":"#/components/schemas/NamedReference"}],"description":"Reference to the parent feature flag metadata."},"environment":{"allOf":[{"$ref":"#/components/schemas/NamedReference"}],"description":"Reference to the environment this definition is scoped to."},"trafficType":{"allOf":[{"$ref":"#/components/schemas/NamedReference"}],"description":"Reference to the traffic type used to bucket keys."},"isKilled":{"type":"boolean","readOnly":true,"description":"Whether the flag is killed in this environment. While killed, all traffic receives\n`defaultTreatment` regardless of rules. Response-only — use the dedicated kill/restore\nactions to change it.\n"},"treatments":{"type":"array","minItems":2,"description":"The treatments available for this flag in this environment.","items":{"$ref":"#/components/schemas/Treatment"}},"defaultTreatment":{"allOf":[{"$ref":"#/components/schemas/TreatmentName"}],"description":"Treatment served when the flag is killed, and to traffic outside `trafficAllocation`.\n"},"baselineTreatment":{"allOf":[{"$ref":"#/components/schemas/TreatmentName"}],"description":"Baseline treatment used as the control group for metrics calculations."},"trafficAllocation":{"type":"integer","format":"int32","minimum":0,"maximum":100,"description":"Percentage of total traffic that participates in this flag's evaluation. Traffic\noutside this allocation receives `defaultTreatment`.\n"},"rules":{"type":"array","description":"Ordered targeting rules. Empty means all traffic falls through to `defaultRule`.","items":{"$ref":"#/components/schemas/Rule"}},"defaultRule":{"type":"array","minItems":1,"description":"Distribution applied to in-allocation traffic that matches no targeting rule. Bucket\nsizes must sum to 100.\n","items":{"$ref":"#/components/schemas/Distribution"}},"flagSets":{"type":"array","description":"Flag sets associated with this definition. Empty means the definition belongs to no\nflag set. Assigned on create/PATCH; echoed on GET.\n","items":{"$ref":"#/components/schemas/FlagSetReference"}},"createdAt":{"type":"string","format":"date-time","description":"ISO-8601 timestamp when this definition was created."},"impressions":{"allOf":[{"$ref":"#/components/schemas/Impressions"}],"description":"Traffic/impression freshness data for this definition."}}},"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."}}},"Treatment":{"type":"object","description":"A single treatment (variation) of the feature flag in this environment.\n","required":["name"],"properties":{"name":{"allOf":[{"$ref":"#/components/schemas/TreatmentName"}],"description":"Treatment name. Must start with a letter or digit; remaining characters may be letters,\ndigits, hyphens, underscores, or periods. The reserved name `control` is not allowed.\n"},"description":{"type":"string","nullable":true,"description":"Optional description of this treatment."},"keys":{"type":"array","description":"Keys explicitly assigned to this treatment.","items":{"type":"string"}},"segments":{"type":"array","description":"Standard segment names assigned to this treatment.","items":{"type":"string","pattern":"^[A-Za-z][-_A-Za-z0-9]*$","maxLength":100}},"largeSegments":{"type":"array","description":"Large segment names assigned to this treatment.","items":{"type":"string","pattern":"^[A-Za-z][-_A-Za-z0-9]*$","maxLength":100}},"ruleBasedSegments":{"type":"array","description":"Rule-based segment names assigned to this treatment.","items":{"type":"string","pattern":"^[A-Za-z][-_A-Za-z0-9]*$","maxLength":100}},"configurations":{"type":"string","nullable":true,"description":"Dynamic configuration attached to this treatment, serialized as a JSON string.\n"}}},"Rule":{"type":"object","description":"A targeting rule: a condition and the treatment buckets served on match.\n","required":["condition","buckets"],"properties":{"condition":{"$ref":"#/components/schemas/Condition"},"buckets":{"type":"array","minItems":1,"description":"Treatment buckets served when the condition matches. Sizes must sum to 100.\n","items":{"$ref":"#/components/schemas/Distribution"}}}},"Condition":{"type":"object","description":"The matching condition for a targeting rule. Only the `AND` combiner is supported — all\nmatchers must match. `OR` combination is not supported.\n","required":["combiner","matchers"],"properties":{"combiner":{"type":"string","enum":["AND"],"description":"Matcher combiner. Only `AND` is supported."},"matchers":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/Matcher"}}}},"Distribution":{"type":"object","description":"A percentage bucket assigning a share of traffic to a treatment. The treatment name must\nrefer to a treatment in the same definition.\n","required":["treatment","size"],"properties":{"treatment":{"allOf":[{"$ref":"#/components/schemas/TreatmentName"}],"description":"Treatment name from this definition."},"size":{"type":"integer","format":"int32","minimum":0,"maximum":100,"description":"Percentage of traffic assigned to the treatment (0-100)."}}},"Impressions":{"type":"object","description":"Traffic/impression freshness data for this Feature Flag Definition.\n","required":["lastImpressionAt"],"properties":{"lastImpressionAt":{"type":"string","format":"date-time","nullable":true,"description":"Timestamp of the most recent impression recorded for this definition, or `null` if it\nhas never received traffic.\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"}}}},"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/feature-flag-definitions/{feature-flag-name}":{"post":{"tags":["Feature Flag Definitions"],"operationId":"createFeatureFlagDefinition","summary":"Create a Feature Flag Definition","description":"Requires `environment_id` as a query parameter. Creates a new Feature Flag Definition for\nthe specified feature flag in the specified environment. A definition must not already exist\nfor this feature flag + environment combination (`409` on conflict). When the environment\nrequires approval, returns `403`. Optional `flagSets` associates the definition with\nexisting flag sets by id.\n","parameters":[{"$ref":"#/components/parameters/FeatureFlagName"},{"$ref":"#/components/parameters/AccountId"},{"$ref":"#/components/parameters/EnvironmentId"},{"$ref":"#/components/parameters/OrganizationIdentifier"},{"$ref":"#/components/parameters/ProjectIdentifier"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateFeatureFlagDefinitionRequest"}}}},"responses":{"201":{"description":"Created — the feature flag definition was successfully created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeatureFlagDefinitionResponse"}}}},"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"}}}}}}
```

## Delete a Feature Flag Definition

> Requires \`environment\_id\` as a query parameter. Deletes a Feature Flag Definition for the\
> specified feature flag in the specified environment. Returns the OPA governance result.\
> Returns \`409\` when a pending change request already exists (\`pendingChangeConflict\`) or\
> when the definition has active dependents (\`hasDependents\`). When the environment requires\
> approval, returns \`403\`.<br>

```json
{"openapi":"3.0.3","info":{"title":"Harness Feature Management & Experimentation API","version":"4.0.0"},"tags":[{"name":"Feature Flag Definitions","description":"Manage environment-specific feature flag definitions (treatments, traffic allocation, targeting)."}],"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":{"FeatureFlagName":{"name":"feature-flag-name","in":"path","required":true,"description":"The unique name of the feature flag within the project. Names must begin with a letter\nand may contain letters, numbers, underscores, and hyphens. Use the same value that was\nsupplied as `name` when the flag was created. System-assigned ids are not accepted.\n","schema":{"type":"string","pattern":"^[A-Za-z][-_A-Za-z0-9]*$","maxLength":100}},"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}},"EnvironmentId":{"name":"environment_id","in":"query","required":true,"description":"Environment identifier. Scopes the request to a specific environment; combined with the\nresource name in the path it identifies a specific environment-scoped definition (e.g.,\na Feature Flag Definition or a Segment Definition).\n","schema":{"type":"string","format":"uuid","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":{"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/feature-flag-definitions/{feature-flag-name}":{"delete":{"tags":["Feature Flag Definitions"],"operationId":"deleteFeatureFlagDefinition","summary":"Delete a Feature Flag Definition","description":"Requires `environment_id` as a query parameter. Deletes a Feature Flag Definition for the\nspecified feature flag in the specified environment. Returns the OPA governance result.\nReturns `409` when a pending change request already exists (`pendingChangeConflict`) or\nwhen the definition has active dependents (`hasDependents`). When the environment requires\napproval, returns `403`.\n","parameters":[{"$ref":"#/components/parameters/FeatureFlagName"},{"$ref":"#/components/parameters/AccountId"},{"$ref":"#/components/parameters/EnvironmentId"},{"$ref":"#/components/parameters/OrganizationIdentifier"},{"$ref":"#/components/parameters/ProjectIdentifier"}],"responses":{"200":{"description":"OK — feature flag definition 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 Feature Flag Definition (partial)

> Requires \`environment\_id\` as a query parameter. Partially updates a Feature Flag Definition\
> using JSON Merge Patch semantics (RFC 7396). Field-level omit / replace / null rules are\
> defined on \`UpdateFeatureFlagDefinitionRequest\`.\
> \
> Returns \`409\` when a pending change request already exists for this definition. When the\
> environment requires approval, returns \`403\`.\
> \
> \*\*Updatable fields:\*\* \`treatments\`, \`defaultTreatment\`, \`baselineTreatment\`,\
> \`trafficAllocation\`, \`rules\`, \`defaultRule\`, \`flagSets\`, \`comment\`, \`title\`.<br>

```json
{"openapi":"3.0.3","info":{"title":"Harness Feature Management & Experimentation API","version":"4.0.0"},"tags":[{"name":"Feature Flag Definitions","description":"Manage environment-specific feature flag definitions (treatments, traffic allocation, targeting)."}],"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":{"FeatureFlagName":{"name":"feature-flag-name","in":"path","required":true,"description":"The unique name of the feature flag within the project. Names must begin with a letter\nand may contain letters, numbers, underscores, and hyphens. Use the same value that was\nsupplied as `name` when the flag was created. System-assigned ids are not accepted.\n","schema":{"type":"string","pattern":"^[A-Za-z][-_A-Za-z0-9]*$","maxLength":100}},"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}},"EnvironmentId":{"name":"environment_id","in":"query","required":true,"description":"Environment identifier. Scopes the request to a specific environment; combined with the\nresource name in the path it identifies a specific environment-scoped definition (e.g.,\na Feature Flag Definition or a Segment Definition).\n","schema":{"type":"string","format":"uuid","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":{"UpdateFeatureFlagDefinitionRequest":{"type":"object","description":"JSON Merge Patch body (RFC 7396). Omit a field to leave it unchanged. Array fields\n(`treatments`, `rules`, `defaultRule`, `flagSets`) are replaced in full when present;\n`null` for those arrays is a validation error (`400`). `flagSets: []` is a full replace\nwith no associations (clears membership). Scalar fields (`defaultTreatment`,\n`baselineTreatment`, `trafficAllocation`, `comment`, `title`) are non-clearable and\nset-only — omitting the field and sending JSON `null` both leave the existing value\nunchanged (`null` is treated the same as omit); there is no invent-clear, and there is no\nway to clear these fields via this endpoint.\n","properties":{"treatments":{"type":"array","minItems":2,"description":"Full replacement of the treatment list.","items":{"$ref":"#/components/schemas/TreatmentInput"}},"defaultTreatment":{"allOf":[{"$ref":"#/components/schemas/TreatmentName"}],"description":"Updated default treatment."},"baselineTreatment":{"allOf":[{"$ref":"#/components/schemas/TreatmentName"}],"description":"Updated baseline treatment."},"trafficAllocation":{"type":"integer","format":"int32","minimum":0,"maximum":100,"description":"Updated traffic allocation percentage."},"rules":{"type":"array","description":"Full replacement of the ordered targeting rules.","items":{"$ref":"#/components/schemas/RuleInput"}},"defaultRule":{"type":"array","minItems":1,"description":"Full replacement of the default distribution. Empty `[]` and `null` are rejected\n(`400`).\n","items":{"$ref":"#/components/schemas/DistributionInput"}},"flagSets":{"type":"array","description":"Full replacement of flag-set associations. Omit to leave unchanged. Present array\n(including `[]`) replaces membership; `null` is a validation error (`400`).\n","items":{"$ref":"#/components/schemas/FlagSetReference"}},"comment":{"type":"string","description":"Optional audit comment recorded with the update."},"title":{"type":"string","description":"Optional audit title recorded with the update."}}},"TreatmentInput":{"type":"object","description":"Treatment input used in create and patch request bodies. The default treatment is selected\nwith the request-level `defaultTreatment` field.\n","required":["name"],"properties":{"name":{"allOf":[{"$ref":"#/components/schemas/TreatmentName"}],"description":"Treatment name. Must start with a letter or digit; remaining characters may be letters,\ndigits, hyphens, underscores, or periods. The reserved name `control` is not allowed.\n"},"description":{"type":"string","nullable":true,"description":"Optional description of this treatment."},"keys":{"type":"array","description":"Keys explicitly assigned to this treatment.","items":{"type":"string"}},"segments":{"type":"array","description":"Standard segment names assigned to this treatment.","items":{"type":"string","pattern":"^[A-Za-z][-_A-Za-z0-9]*$","maxLength":100}},"largeSegments":{"type":"array","description":"Large segment names assigned to this treatment.","items":{"type":"string","pattern":"^[A-Za-z][-_A-Za-z0-9]*$","maxLength":100}},"ruleBasedSegments":{"type":"array","description":"Rule-based segment names assigned to this treatment.","items":{"type":"string","pattern":"^[A-Za-z][-_A-Za-z0-9]*$","maxLength":100}},"configurations":{"type":"string","nullable":true,"description":"Dynamic configuration attached to this treatment, serialized as a JSON string.\n"}}},"TreatmentName":{"type":"string","pattern":"^[a-zA-Z0-9][-_\\.a-zA-Z0-9]*$","description":"Treatment name. Must start with a letter or digit; remaining characters may be letters,\ndigits, hyphens, underscores, or periods.\n"},"RuleInput":{"type":"object","description":"Targeting rule for create/patch request bodies. Buckets use `DistributionInput`.","required":["condition","buckets"],"properties":{"condition":{"$ref":"#/components/schemas/ConditionInput"},"buckets":{"type":"array","minItems":1,"description":"Treatment buckets served when the condition matches. Sizes must sum to 100.\n","items":{"$ref":"#/components/schemas/DistributionInput"}}}},"ConditionInput":{"type":"object","description":"Targeting condition for create/patch request bodies. If `combiner` is omitted, the server\ntreats it as `AND`.\n","required":["matchers"],"properties":{"combiner":{"type":"string","enum":["AND"],"default":"AND","description":"Matcher combiner. Only `AND` is supported; defaults to `AND` when omitted."},"matchers":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/Matcher"}}}},"Matcher":{"description":"A matcher within a targeting condition. Discriminated by `type` — each variant requires\nthe value field(s) that type evaluates. `negate` is optional on every variant (`true`\ninverts the result). `attribute` is required when the matcher evaluates a traffic-type\nattribute; omit it only for key-based list/string matchers (`IN_LIST_STRING`,\n`STARTS_WITH_STRING`, `ENDS_WITH_STRING`, `CONTAINS_STRING`, `MATCHES_STRING`).\n","oneOf":[{"$ref":"#/components/schemas/SegmentMatcher"},{"$ref":"#/components/schemas/SplitMatcher"},{"$ref":"#/components/schemas/BooleanMatcher"},{"$ref":"#/components/schemas/DateMatcher"},{"$ref":"#/components/schemas/BetweenDateMatcher"},{"$ref":"#/components/schemas/SetMatcher"},{"$ref":"#/components/schemas/NumberMatcher"},{"$ref":"#/components/schemas/BetweenNumberMatcher"},{"$ref":"#/components/schemas/InListStringMatcher"},{"$ref":"#/components/schemas/StringListMatcher"},{"$ref":"#/components/schemas/MatchesStringMatcher"},{"$ref":"#/components/schemas/SemverCompareMatcher"},{"$ref":"#/components/schemas/BetweenSemverMatcher"},{"$ref":"#/components/schemas/InListSemverMatcher"}],"discriminator":{"propertyName":"type","mapping":{"IN_SEGMENT":"#/components/schemas/SegmentMatcher","IN_LARGE_SEGMENT":"#/components/schemas/SegmentMatcher","IN_RULE_BASED_SEGMENT":"#/components/schemas/SegmentMatcher","IN_SPLIT":"#/components/schemas/SplitMatcher","BOOLEAN":"#/components/schemas/BooleanMatcher","ON_DATE":"#/components/schemas/DateMatcher","ON_OR_AFTER_DATE":"#/components/schemas/DateMatcher","ON_OR_BEFORE_DATE":"#/components/schemas/DateMatcher","BETWEEN_DATE":"#/components/schemas/BetweenDateMatcher","EQUAL_SET":"#/components/schemas/SetMatcher","ANY_OF_SET":"#/components/schemas/SetMatcher","ALL_OF_SET":"#/components/schemas/SetMatcher","PART_OF_SET":"#/components/schemas/SetMatcher","EQUAL_NUMBER":"#/components/schemas/NumberMatcher","LESS_THAN_OR_EQUAL_NUMBER":"#/components/schemas/NumberMatcher","GREATER_THAN_OR_EQUAL_NUMBER":"#/components/schemas/NumberMatcher","BETWEEN_NUMBER":"#/components/schemas/BetweenNumberMatcher","IN_LIST_STRING":"#/components/schemas/InListStringMatcher","STARTS_WITH_STRING":"#/components/schemas/StringListMatcher","ENDS_WITH_STRING":"#/components/schemas/StringListMatcher","CONTAINS_STRING":"#/components/schemas/StringListMatcher","MATCHES_STRING":"#/components/schemas/MatchesStringMatcher","EQUAL_TO_SEMVER":"#/components/schemas/SemverCompareMatcher","GREATER_THAN_OR_EQUAL_TO_SEMVER":"#/components/schemas/SemverCompareMatcher","LESS_THAN_OR_EQUAL_TO_SEMVER":"#/components/schemas/SemverCompareMatcher","BETWEEN_SEMVER":"#/components/schemas/BetweenSemverMatcher","IN_LIST_SEMVER":"#/components/schemas/InListSemverMatcher"}}},"SegmentMatcher":{"type":"object","additionalProperties":false,"description":"Key is in the named standard, large, or rule-based segment.","required":["type","string"],"properties":{"type":{"type":"string","enum":["IN_SEGMENT","IN_LARGE_SEGMENT","IN_RULE_BASED_SEGMENT"]},"negate":{"type":"boolean"},"string":{"type":"string","description":"Segment name."}}},"SplitMatcher":{"type":"object","additionalProperties":false,"description":"Prerequisite feature-flag (dependency) matcher.","required":["type","depends"],"properties":{"type":{"type":"string","enum":["IN_SPLIT"]},"negate":{"type":"boolean"},"depends":{"$ref":"#/components/schemas/Depends"}}},"Depends":{"type":"object","description":"Feature flag dependency matcher payload.","required":["splitName","treatments"],"properties":{"splitName":{"type":"string","pattern":"^[A-Za-z][-_A-Za-z0-9]*$","maxLength":100,"description":"Name of the prerequisite feature flag."},"treatments":{"type":"array","minItems":1,"description":"Treatments accepted from the prerequisite feature flag.","items":{"$ref":"#/components/schemas/TreatmentName"}}}},"BooleanMatcher":{"type":"object","additionalProperties":false,"description":"Attribute equals a boolean value.","required":["type","attribute","bool"],"properties":{"type":{"type":"string","enum":["BOOLEAN"]},"negate":{"type":"boolean"},"attribute":{"type":"string"},"bool":{"type":"boolean"}}},"DateMatcher":{"type":"object","additionalProperties":false,"description":"Attribute compared to a single epoch-millisecond timestamp.","required":["type","attribute","date"],"properties":{"type":{"type":"string","enum":["ON_DATE","ON_OR_AFTER_DATE","ON_OR_BEFORE_DATE"]},"negate":{"type":"boolean"},"attribute":{"type":"string"},"date":{"type":"integer","format":"int64","description":"Epoch milliseconds."}}},"BetweenDateMatcher":{"type":"object","additionalProperties":false,"description":"Attribute falls in an inclusive epoch-millisecond range.","required":["type","attribute","between"],"properties":{"type":{"type":"string","enum":["BETWEEN_DATE"]},"negate":{"type":"boolean"},"attribute":{"type":"string"},"between":{"$ref":"#/components/schemas/BetweenNumberAttribute"}}},"BetweenNumberAttribute":{"type":"object","description":"Inclusive numeric range for BETWEEN_NUMBER and BETWEEN_DATE matchers. Values are int64 — plain numbers for number matchers, epoch millis for date matchers. String/semver ranges use BetweenStringAttribute.\n","required":["from","to"],"properties":{"from":{"type":"integer","format":"int64"},"to":{"type":"integer","format":"int64"}}},"SetMatcher":{"type":"object","additionalProperties":false,"description":"Attribute set compared to a list of strings.","required":["type","attribute","strings"],"properties":{"type":{"type":"string","enum":["EQUAL_SET","ANY_OF_SET","ALL_OF_SET","PART_OF_SET"]},"negate":{"type":"boolean"},"attribute":{"type":"string"},"strings":{"type":"array","minItems":1,"items":{"type":"string"}}}},"NumberMatcher":{"type":"object","additionalProperties":false,"description":"Attribute compared to a single int64 number.","required":["type","attribute","number"],"properties":{"type":{"type":"string","enum":["EQUAL_NUMBER","LESS_THAN_OR_EQUAL_NUMBER","GREATER_THAN_OR_EQUAL_NUMBER"]},"negate":{"type":"boolean"},"attribute":{"type":"string"},"number":{"type":"integer","format":"int64"}}},"BetweenNumberMatcher":{"type":"object","additionalProperties":false,"description":"Attribute falls in an inclusive numeric range.","required":["type","attribute","between"],"properties":{"type":{"type":"string","enum":["BETWEEN_NUMBER"]},"negate":{"type":"boolean"},"attribute":{"type":"string"},"between":{"$ref":"#/components/schemas/BetweenNumberAttribute"}}},"InListStringMatcher":{"type":"object","additionalProperties":false,"description":"Value is in a string list. Omit `attribute` to match the key; set `attribute` to match\nthat traffic-type attribute.\n","required":["type","strings"],"properties":{"type":{"type":"string","enum":["IN_LIST_STRING"]},"negate":{"type":"boolean"},"attribute":{"type":"string"},"strings":{"type":"array","minItems":1,"items":{"type":"string"}}}},"StringListMatcher":{"type":"object","additionalProperties":false,"description":"Attribute (or key, if `attribute` is omitted) starts with, ends with, or contains any of\nthe listed strings.\n","required":["type","strings"],"properties":{"type":{"type":"string","enum":["STARTS_WITH_STRING","ENDS_WITH_STRING","CONTAINS_STRING"]},"negate":{"type":"boolean"},"attribute":{"type":"string"},"strings":{"type":"array","minItems":1,"items":{"type":"string"}}}},"MatchesStringMatcher":{"type":"object","additionalProperties":false,"description":"Attribute (or key, if `attribute` is omitted) matches a regular expression in `string`.\n","required":["type","string"],"properties":{"type":{"type":"string","enum":["MATCHES_STRING"]},"negate":{"type":"boolean"},"attribute":{"type":"string"},"string":{"type":"string","description":"Regular expression."}}},"SemverCompareMatcher":{"type":"object","additionalProperties":false,"description":"Attribute compared to a single semantic-version string.","required":["type","attribute","string"],"properties":{"type":{"type":"string","enum":["EQUAL_TO_SEMVER","GREATER_THAN_OR_EQUAL_TO_SEMVER","LESS_THAN_OR_EQUAL_TO_SEMVER"]},"negate":{"type":"boolean"},"attribute":{"type":"string"},"string":{"type":"string"}}},"BetweenSemverMatcher":{"type":"object","additionalProperties":false,"description":"Attribute falls in an inclusive semantic-version range.","required":["type","attribute","betweenString"],"properties":{"type":{"type":"string","enum":["BETWEEN_SEMVER"]},"negate":{"type":"boolean"},"attribute":{"type":"string"},"betweenString":{"$ref":"#/components/schemas/BetweenStringAttribute"}}},"BetweenStringAttribute":{"type":"object","description":"Inclusive string range for semantic-version BETWEEN matchers.","required":["from","to"],"properties":{"from":{"type":"string"},"to":{"type":"string"}}},"InListSemverMatcher":{"type":"object","additionalProperties":false,"description":"Attribute semantic version is in the listed versions.","required":["type","attribute","strings"],"properties":{"type":{"type":"string","enum":["IN_LIST_SEMVER"]},"negate":{"type":"boolean"},"attribute":{"type":"string"},"strings":{"type":"array","minItems":1,"items":{"type":"string"}}}},"DistributionInput":{"type":"object","description":"Distribution input used in create and patch request bodies. The treatment name must refer\nto a treatment in the same request/definition.\n","required":["treatment","size"],"properties":{"treatment":{"allOf":[{"$ref":"#/components/schemas/TreatmentName"}],"description":"Treatment name from this definition."},"size":{"type":"integer","format":"int32","minimum":0,"maximum":100,"description":"Percentage of traffic assigned to the treatment (0-100)."}}},"FlagSetReference":{"type":"object","description":"Flag set associated with a feature flag definition. Used on create, update, and GET.\nIdentify the flag set by `id`. `name` is not accepted or returned.\n","required":["id"],"properties":{"id":{"type":"string","format":"uuid","description":"System-assigned identifier for the flag set."}}},"FeatureFlagDefinitionResponse":{"type":"object","description":"Feature Flag Definition entity together with the OPA governance result.","required":["entity","governance"],"properties":{"entity":{"$ref":"#/components/schemas/FeatureFlagDefinition"},"governance":{"allOf":[{"$ref":"#/components/schemas/GovernanceResult"}],"description":"OPA governance result for the mutation."}}},"FeatureFlagDefinition":{"type":"object","description":"An environment-specific Feature Flag Definition.","required":["id","featureFlag","environment","trafficType","isKilled","treatments","defaultTreatment","baselineTreatment","trafficAllocation","rules","defaultRule","createdAt","impressions"],"properties":{"id":{"type":"string","format":"uuid","description":"System-assigned identifier for this feature flag definition."},"featureFlag":{"allOf":[{"$ref":"#/components/schemas/NamedReference"}],"description":"Reference to the parent feature flag metadata."},"environment":{"allOf":[{"$ref":"#/components/schemas/NamedReference"}],"description":"Reference to the environment this definition is scoped to."},"trafficType":{"allOf":[{"$ref":"#/components/schemas/NamedReference"}],"description":"Reference to the traffic type used to bucket keys."},"isKilled":{"type":"boolean","readOnly":true,"description":"Whether the flag is killed in this environment. While killed, all traffic receives\n`defaultTreatment` regardless of rules. Response-only — use the dedicated kill/restore\nactions to change it.\n"},"treatments":{"type":"array","minItems":2,"description":"The treatments available for this flag in this environment.","items":{"$ref":"#/components/schemas/Treatment"}},"defaultTreatment":{"allOf":[{"$ref":"#/components/schemas/TreatmentName"}],"description":"Treatment served when the flag is killed, and to traffic outside `trafficAllocation`.\n"},"baselineTreatment":{"allOf":[{"$ref":"#/components/schemas/TreatmentName"}],"description":"Baseline treatment used as the control group for metrics calculations."},"trafficAllocation":{"type":"integer","format":"int32","minimum":0,"maximum":100,"description":"Percentage of total traffic that participates in this flag's evaluation. Traffic\noutside this allocation receives `defaultTreatment`.\n"},"rules":{"type":"array","description":"Ordered targeting rules. Empty means all traffic falls through to `defaultRule`.","items":{"$ref":"#/components/schemas/Rule"}},"defaultRule":{"type":"array","minItems":1,"description":"Distribution applied to in-allocation traffic that matches no targeting rule. Bucket\nsizes must sum to 100.\n","items":{"$ref":"#/components/schemas/Distribution"}},"flagSets":{"type":"array","description":"Flag sets associated with this definition. Empty means the definition belongs to no\nflag set. Assigned on create/PATCH; echoed on GET.\n","items":{"$ref":"#/components/schemas/FlagSetReference"}},"createdAt":{"type":"string","format":"date-time","description":"ISO-8601 timestamp when this definition was created."},"impressions":{"allOf":[{"$ref":"#/components/schemas/Impressions"}],"description":"Traffic/impression freshness data for this definition."}}},"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."}}},"Treatment":{"type":"object","description":"A single treatment (variation) of the feature flag in this environment.\n","required":["name"],"properties":{"name":{"allOf":[{"$ref":"#/components/schemas/TreatmentName"}],"description":"Treatment name. Must start with a letter or digit; remaining characters may be letters,\ndigits, hyphens, underscores, or periods. The reserved name `control` is not allowed.\n"},"description":{"type":"string","nullable":true,"description":"Optional description of this treatment."},"keys":{"type":"array","description":"Keys explicitly assigned to this treatment.","items":{"type":"string"}},"segments":{"type":"array","description":"Standard segment names assigned to this treatment.","items":{"type":"string","pattern":"^[A-Za-z][-_A-Za-z0-9]*$","maxLength":100}},"largeSegments":{"type":"array","description":"Large segment names assigned to this treatment.","items":{"type":"string","pattern":"^[A-Za-z][-_A-Za-z0-9]*$","maxLength":100}},"ruleBasedSegments":{"type":"array","description":"Rule-based segment names assigned to this treatment.","items":{"type":"string","pattern":"^[A-Za-z][-_A-Za-z0-9]*$","maxLength":100}},"configurations":{"type":"string","nullable":true,"description":"Dynamic configuration attached to this treatment, serialized as a JSON string.\n"}}},"Rule":{"type":"object","description":"A targeting rule: a condition and the treatment buckets served on match.\n","required":["condition","buckets"],"properties":{"condition":{"$ref":"#/components/schemas/Condition"},"buckets":{"type":"array","minItems":1,"description":"Treatment buckets served when the condition matches. Sizes must sum to 100.\n","items":{"$ref":"#/components/schemas/Distribution"}}}},"Condition":{"type":"object","description":"The matching condition for a targeting rule. Only the `AND` combiner is supported — all\nmatchers must match. `OR` combination is not supported.\n","required":["combiner","matchers"],"properties":{"combiner":{"type":"string","enum":["AND"],"description":"Matcher combiner. Only `AND` is supported."},"matchers":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/Matcher"}}}},"Distribution":{"type":"object","description":"A percentage bucket assigning a share of traffic to a treatment. The treatment name must\nrefer to a treatment in the same definition.\n","required":["treatment","size"],"properties":{"treatment":{"allOf":[{"$ref":"#/components/schemas/TreatmentName"}],"description":"Treatment name from this definition."},"size":{"type":"integer","format":"int32","minimum":0,"maximum":100,"description":"Percentage of traffic assigned to the treatment (0-100)."}}},"Impressions":{"type":"object","description":"Traffic/impression freshness data for this Feature Flag Definition.\n","required":["lastImpressionAt"],"properties":{"lastImpressionAt":{"type":"string","format":"date-time","nullable":true,"description":"Timestamp of the most recent impression recorded for this definition, or `null` if it\nhas never received traffic.\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"}}}},"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/feature-flag-definitions/{feature-flag-name}":{"patch":{"tags":["Feature Flag Definitions"],"operationId":"updateFeatureFlagDefinition","summary":"Update a Feature Flag Definition (partial)","description":"Requires `environment_id` as a query parameter. Partially updates a Feature Flag Definition\nusing JSON Merge Patch semantics (RFC 7396). Field-level omit / replace / null rules are\ndefined on `UpdateFeatureFlagDefinitionRequest`.\n\nReturns `409` when a pending change request already exists for this definition. When the\nenvironment requires approval, returns `403`.\n\n**Updatable fields:** `treatments`, `defaultTreatment`, `baselineTreatment`,\n`trafficAllocation`, `rules`, `defaultRule`, `flagSets`, `comment`, `title`.\n","parameters":[{"$ref":"#/components/parameters/FeatureFlagName"},{"$ref":"#/components/parameters/AccountId"},{"$ref":"#/components/parameters/EnvironmentId"},{"$ref":"#/components/parameters/OrganizationIdentifier"},{"$ref":"#/components/parameters/ProjectIdentifier"}],"requestBody":{"required":true,"content":{"application/merge-patch+json":{"schema":{"$ref":"#/components/schemas/UpdateFeatureFlagDefinitionRequest"}}}},"responses":{"200":{"description":"OK — feature flag definition partially updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeatureFlagDefinitionResponse"}}}},"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"}}}}}}
```
