> 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-flags.md).

# Feature Flags

Manage workspace-scoped feature flag metadata and lifecycle (create, list, get, update, delete, archive, unarchive).

## List Feature Flags

> Returns a paginated list of Feature Flags in the specified project workspace.\
> Defaults to active flags (\`status\` defaults to \`\[ACTIVE]\`). Results can be filtered by\
> status, name, tags, rollout statuses, or feature flag identifiers and are sorted by name\
> in ascending order.<br>

```json
{"openapi":"3.0.3","info":{"title":"Harness Feature Management & Experimentation API","version":"4.0.0"},"tags":[{"name":"Feature Flags","description":"Manage workspace-scoped feature flag metadata and lifecycle (create, list, get, update, delete, archive, unarchive)."}],"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":{"FeatureFlagListResponse":{"type":"object","description":"Paginated list of Feature Flags matching the query.","required":["data","limit","offset","totalCount"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FeatureFlag"}},"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 feature flags matching the query."}}},"FeatureFlag":{"type":"object","description":"A workspace-scoped Feature Flag entity.","required":["id","name","trafficType","createdAt","status","tags","owners"],"properties":{"id":{"type":"string","format":"uuid","description":"Unique system-assigned identifier for the feature flag."},"name":{"type":"string","description":"Unique feature flag name within the project. Immutable after creation — use this as the\npath parameter in subsequent requests.\n"},"description":{"type":"string","nullable":true,"description":"Human-readable description of this feature flag."},"trafficType":{"allOf":[{"$ref":"#/components/schemas/NamedReference"}],"description":"Reference to the traffic type used to bucket users."},"createdAt":{"type":"string","format":"date-time","description":"ISO-8601 timestamp when the feature flag was created."},"status":{"type":"string","enum":["ACTIVE","ARCHIVED"],"description":"Lifecycle status of the feature flag.\n- `ACTIVE` — flag is live.\n- `ARCHIVED` — flag is no longer active and is read-only.\n"},"rolloutStatus":{"allOf":[{"$ref":"#/components/schemas/NamedReference"}],"type":"object","nullable":true,"description":"Rollout status assigned to this feature flag.\n\nThis field is omitted or `null` when no rollout status is assigned. It cannot be set\nwhen creating a feature flag. New feature flags use the workspace default rollout\nstatus. Use PATCH to change it.\n"},"tags":{"type":"array","description":"Tags associated with this feature flag.","items":{"$ref":"#/components/schemas/NamedReference"}},"owners":{"type":"array","description":"Users or teams that own this feature flag. `USER` owners include `email`; `GROUP`\nowners do not.\n","items":{"$ref":"#/components/schemas/OwnerReference"}}}},"NamedReference":{"type":"object","description":"Generic reference to another resource, returned in responses. `id` is the stable\npublic identifier and `name` is the human-readable label.\n","required":["id","name"],"properties":{"id":{"type":"string","description":"Identifier of the referenced resource."},"name":{"type":"string","description":"Human-readable name of the referenced resource."}}},"OwnerReference":{"type":"object","description":"Reference to an owner (user or group), returned in responses. Extends the generic reference\nwith an optional `email`: a `USER` owner MAY carry `email` where the resource populates it;\na `GROUP` owner never has one. Use `id` for subsequent API calls; `name`/`email` are\ninformational (they let clients that keyed on a user's email at write time correlate the\nresponse without a lookup). Shared across FME v4 resources that expose owners.\n","required":["id","type","name"],"properties":{"id":{"type":"string","description":"Identifier of the owner — the Harness user id (for `USER`) or group id (for `GROUP`)."},"type":{"type":"string","enum":["USER","GROUP"],"description":"Owner kind."},"name":{"type":"string","description":"Human-readable display name of the user or group."},"email":{"type":"string","format":"email","nullable":true,"description":"Email address of the owner. Optionally populated for `USER` owners where the resource\nsupports it; `null`/absent for `GROUP` owners and for resources that do not return it.\n"}}},"ErrorResponse":{"type":"object","description":"Standard error response following RFC 7807 Problem Details format (Harness ADR 57).\n","required":["type","status","title","errorType"],"properties":{"type":{"type":"string","format":"uri","description":"URI reference to documentation for this error type."},"status":{"type":"integer","description":"HTTP status code."},"title":{"type":"string","description":"Short human-readable summary of the problem."},"errorType":{"type":"string","description":"Machine-readable error type identifier."},"detail":{"type":"string","description":"Detailed human-readable explanation specific to this occurrence."},"instance":{"type":"string","description":"URI reference identifying the specific occurrence (usually the request path)."},"errors":{"type":"array","description":"List of specific sub-errors (useful for multi-field validation failures). Governance\npolicy failures are also surfaced here — each failing policy is reported as an entry\nwith `errorType: \"governancePolicy\"` — rather than in a separate top-level field.\n","items":{"$ref":"#/components/schemas/ErrorDetail"}}}},"ErrorDetail":{"type":"object","description":"Details about a single sub-error.","required":["errorType","title"],"properties":{"errorType":{"type":"string","description":"Machine-readable error type for this specific error."},"title":{"type":"string","description":"Short summary of this specific error."},"detail":{"type":"string","description":"Detailed explanation of this specific error."},"field":{"type":"string","description":"Name of the request field this error applies to, when the error is field-specific\n(for example a validation failure). Omitted for errors not tied to a single field.\n"}}}},"responses":{"BadRequest":{"description":"Bad Request — validation errors or invalid state transition.\n","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Unauthorized — the request is missing a valid API key, or the key has expired.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Forbidden":{"description":"Forbidden — the caller is authenticated but not permitted to perform this operation.\nReturned when the API can deny the operation without leaking whether a resource exists,\nsuch as create, or write operations where the caller can already read the resource. When\nreturning `403` would reveal resource existence, the API returns `404` instead.\n\nEnvironment-scoped mutations that require approval also return `403`.\n","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"TooManyRequests":{"description":"Too Many Requests — the caller has exceeded the rate limit for this endpoint.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"InternalServerError":{"description":"Internal Server Error — an unexpected error occurred while processing the request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/v4/feature-flags":{"get":{"tags":["Feature Flags"],"operationId":"listFeatureFlags","summary":"List Feature Flags","description":"Returns a paginated list of Feature Flags in the specified project workspace.\nDefaults to active flags (`status` defaults to `[ACTIVE]`). Results can be filtered by\nstatus, name, tags, rollout statuses, or feature flag identifiers and are sorted by name\nin ascending order.\n","parameters":[{"$ref":"#/components/parameters/AccountId"},{"$ref":"#/components/parameters/OrganizationIdentifier"},{"$ref":"#/components/parameters/ProjectIdentifier"},{"$ref":"#/components/parameters/PaginationLimitParam"},{"$ref":"#/components/parameters/PaginationOffsetParam"},{"name":"status","in":"query","required":false,"description":"Filter by lifecycle status. Defaults to `[ACTIVE]`. Explicit values replace the default.\n","schema":{"type":"array","items":{"type":"string","enum":["ACTIVE","ARCHIVED"]},"default":["ACTIVE"]},"style":"form","explode":true},{"name":"name","in":"query","required":false,"description":"Filter by flag name (partial, case-insensitive match).","schema":{"type":"string"}},{"name":"tags","in":"query","required":false,"description":"Filter to flags that have any of the specified tags (by tag name).","schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":true},{"name":"rollout_statuses","in":"query","required":false,"description":"Filter by one or more system-assigned rollout status identifiers.","schema":{"type":"array","items":{"type":"string","format":"uuid"}},"style":"form","explode":true},{"name":"ids","in":"query","required":false,"description":"Filter to specific flag IDs. Useful for bulk lookups.","schema":{"type":"array","items":{"type":"string","format":"uuid"}},"style":"form","explode":true},{"name":"sort","in":"query","required":false,"description":"Sort order. Only `name:asc` is supported. Defaults to `name:asc`.","schema":{"type":"string","enum":["name:asc"],"default":"name:asc"}}],"responses":{"200":{"description":"OK — paginated list of feature flags returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeatureFlagListResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## Create a Feature Flag

> Creates a new Feature Flag in the specified project workspace. The feature flag name must be\
> unique within the project.<br>

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

## Get a Feature Flag

> Returns a single Feature Flag by name. Unlike list, this endpoint returns the flag regardless\
> of lifecycle status (\`ACTIVE\` or \`ARCHIVED\`).<br>

```json
{"openapi":"3.0.3","info":{"title":"Harness Feature Management & Experimentation API","version":"4.0.0"},"tags":[{"name":"Feature Flags","description":"Manage workspace-scoped feature flag metadata and lifecycle (create, list, get, update, delete, archive, unarchive)."}],"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}},"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":{"FeatureFlag":{"type":"object","description":"A workspace-scoped Feature Flag entity.","required":["id","name","trafficType","createdAt","status","tags","owners"],"properties":{"id":{"type":"string","format":"uuid","description":"Unique system-assigned identifier for the feature flag."},"name":{"type":"string","description":"Unique feature flag name within the project. Immutable after creation — use this as the\npath parameter in subsequent requests.\n"},"description":{"type":"string","nullable":true,"description":"Human-readable description of this feature flag."},"trafficType":{"allOf":[{"$ref":"#/components/schemas/NamedReference"}],"description":"Reference to the traffic type used to bucket users."},"createdAt":{"type":"string","format":"date-time","description":"ISO-8601 timestamp when the feature flag was created."},"status":{"type":"string","enum":["ACTIVE","ARCHIVED"],"description":"Lifecycle status of the feature flag.\n- `ACTIVE` — flag is live.\n- `ARCHIVED` — flag is no longer active and is read-only.\n"},"rolloutStatus":{"allOf":[{"$ref":"#/components/schemas/NamedReference"}],"type":"object","nullable":true,"description":"Rollout status assigned to this feature flag.\n\nThis field is omitted or `null` when no rollout status is assigned. It cannot be set\nwhen creating a feature flag. New feature flags use the workspace default rollout\nstatus. Use PATCH to change it.\n"},"tags":{"type":"array","description":"Tags associated with this feature flag.","items":{"$ref":"#/components/schemas/NamedReference"}},"owners":{"type":"array","description":"Users or teams that own this feature flag. `USER` owners include `email`; `GROUP`\nowners do not.\n","items":{"$ref":"#/components/schemas/OwnerReference"}}}},"NamedReference":{"type":"object","description":"Generic reference to another resource, returned in responses. `id` is the stable\npublic identifier and `name` is the human-readable label.\n","required":["id","name"],"properties":{"id":{"type":"string","description":"Identifier of the referenced resource."},"name":{"type":"string","description":"Human-readable name of the referenced resource."}}},"OwnerReference":{"type":"object","description":"Reference to an owner (user or group), returned in responses. Extends the generic reference\nwith an optional `email`: a `USER` owner MAY carry `email` where the resource populates it;\na `GROUP` owner never has one. Use `id` for subsequent API calls; `name`/`email` are\ninformational (they let clients that keyed on a user's email at write time correlate the\nresponse without a lookup). Shared across FME v4 resources that expose owners.\n","required":["id","type","name"],"properties":{"id":{"type":"string","description":"Identifier of the owner — the Harness user id (for `USER`) or group id (for `GROUP`)."},"type":{"type":"string","enum":["USER","GROUP"],"description":"Owner kind."},"name":{"type":"string","description":"Human-readable display name of the user or group."},"email":{"type":"string","format":"email","nullable":true,"description":"Email address of the owner. Optionally populated for `USER` owners where the resource\nsupports it; `null`/absent for `GROUP` owners and for resources that do not return it.\n"}}},"ErrorResponse":{"type":"object","description":"Standard error response following RFC 7807 Problem Details format (Harness ADR 57).\n","required":["type","status","title","errorType"],"properties":{"type":{"type":"string","format":"uri","description":"URI reference to documentation for this error type."},"status":{"type":"integer","description":"HTTP status code."},"title":{"type":"string","description":"Short human-readable summary of the problem."},"errorType":{"type":"string","description":"Machine-readable error type identifier."},"detail":{"type":"string","description":"Detailed human-readable explanation specific to this occurrence."},"instance":{"type":"string","description":"URI reference identifying the specific occurrence (usually the request path)."},"errors":{"type":"array","description":"List of specific sub-errors (useful for multi-field validation failures). Governance\npolicy failures are also surfaced here — each failing policy is reported as an entry\nwith `errorType: \"governancePolicy\"` — rather than in a separate top-level field.\n","items":{"$ref":"#/components/schemas/ErrorDetail"}}}},"ErrorDetail":{"type":"object","description":"Details about a single sub-error.","required":["errorType","title"],"properties":{"errorType":{"type":"string","description":"Machine-readable error type for this specific error."},"title":{"type":"string","description":"Short summary of this specific error."},"detail":{"type":"string","description":"Detailed explanation of this specific error."},"field":{"type":"string","description":"Name of the request field this error applies to, when the error is field-specific\n(for example a validation failure). Omitted for errors not tied to a single field.\n"}}}},"responses":{"BadRequest":{"description":"Bad Request — validation errors or invalid state transition.\n","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Unauthorized — the request is missing a valid API key, or the key has expired.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFound":{"description":"Not Found — the requested resource does not exist. Also returned when the caller lacks\naccess to the resource (to avoid leaking resource existence).\n","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"TooManyRequests":{"description":"Too Many Requests — the caller has exceeded the rate limit for this endpoint.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"InternalServerError":{"description":"Internal Server Error — an unexpected error occurred while processing the request.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/v4/feature-flags/{feature-flag-name}":{"get":{"tags":["Feature Flags"],"operationId":"getFeatureFlag","summary":"Get a Feature Flag","description":"Returns a single Feature Flag by name. Unlike list, this endpoint returns the flag regardless\nof lifecycle status (`ACTIVE` or `ARCHIVED`).\n","parameters":[{"$ref":"#/components/parameters/FeatureFlagName"},{"$ref":"#/components/parameters/AccountId"},{"$ref":"#/components/parameters/OrganizationIdentifier"},{"$ref":"#/components/parameters/ProjectIdentifier"}],"responses":{"200":{"description":"OK — feature flag returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeatureFlag"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## Delete a Feature Flag

> Deletes a Feature Flag. Returns the OPA governance result for the operation. Deleting a\
> flag that has active dependents returns \`409\` (\`hasDependents\`).<br>

```json
{"openapi":"3.0.3","info":{"title":"Harness Feature Management & Experimentation API","version":"4.0.0"},"tags":[{"name":"Feature Flags","description":"Manage workspace-scoped feature flag metadata and lifecycle (create, list, get, update, delete, archive, unarchive)."}],"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}},"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-flags/{feature-flag-name}":{"delete":{"tags":["Feature Flags"],"operationId":"deleteFeatureFlag","summary":"Delete a Feature Flag","description":"Deletes a Feature Flag. Returns the OPA governance result for the operation. Deleting a\nflag that has active dependents returns `409` (`hasDependents`).\n","parameters":[{"$ref":"#/components/parameters/FeatureFlagName"},{"$ref":"#/components/parameters/AccountId"},{"$ref":"#/components/parameters/OrganizationIdentifier"},{"$ref":"#/components/parameters/ProjectIdentifier"}],"responses":{"200":{"description":"OK — feature flag 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 (partial)

> Partially updates a Feature Flag using JSON Merge Patch semantics (RFC 7396). Only fields\
> present in the request body are modified; omitted fields are left unchanged. JSON \`null\` (or\
> \`\[]\` for arrays) clears \`description\`, \`tags\`, and \`owners\`. \`rolloutStatus\` cannot be\
> cleared: omit the field to leave it unchanged; JSON \`null\` returns \`400\`.\
> \
> Only \`ACTIVE\` feature flags can be updated. Patching a non-active flag returns \`400\`\
> (\`invalidState\`). Changing rollout status while an open change request exists returns \`409\`\
> (\`pendingChangeConflict\`).\
> \
> \*\*Updatable fields:\*\* \`description\`, \`tags\`, \`owners\`, \`rolloutStatus\`.<br>

```json
{"openapi":"3.0.3","info":{"title":"Harness Feature Management & Experimentation API","version":"4.0.0"},"tags":[{"name":"Feature Flags","description":"Manage workspace-scoped feature flag metadata and lifecycle (create, list, get, update, delete, archive, unarchive)."}],"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}},"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":{"UpdateFeatureFlagRequest":{"type":"object","description":"JSON Merge Patch body (RFC 7396) for updating a Feature Flag. All fields are optional. Omit a\nfield to leave it unchanged. JSON `null` (or `[]` for arrays) clears `description`, `tags`,\nand `owners`. `rolloutStatus` cannot be cleared: omit to keep; JSON `null` returns `400`.\n","properties":{"description":{"type":"string","nullable":true,"description":"Updated human-readable description."},"tags":{"type":"array","nullable":true,"description":"Replacement tag list.","items":{"$ref":"#/components/schemas/TagReferenceInput"}},"owners":{"type":"array","nullable":true,"description":"Replacement owner list.","items":{"$ref":"#/components/schemas/OwnerReferenceInput"}},"rolloutStatus":{"type":"object","description":"Updated rollout status, identified by its system-assigned `id`. Omit to keep; JSON `null` returns `400`.","required":["id"],"properties":{"id":{"type":"string","format":"uuid","description":"System-assigned identifier for the rollout status."}}}}},"TagReferenceInput":{"type":"object","description":"Tag input used in request bodies. Identified by `name`.","required":["name"],"properties":{"name":{"type":"string","description":"Tag name."}}},"OwnerReferenceInput":{"oneOf":[{"$ref":"#/components/schemas/UserOwnerReferenceInput"},{"$ref":"#/components/schemas/GroupOwnerReferenceInput"}],"discriminator":{"propertyName":"type","mapping":{"USER":"#/components/schemas/UserOwnerReferenceInput","GROUP":"#/components/schemas/GroupOwnerReferenceInput"}},"description":"Owner input. Use `USER` for users and `GROUP` for groups."},"UserOwnerReferenceInput":{"type":"object","description":"User owner input. Prefer `email`; `id` is also accepted for compatibility when the caller\nalready has the Harness user id.\n","required":["type"],"anyOf":[{"required":["email"]},{"required":["id"]}],"properties":{"type":{"type":"string","enum":["USER"],"description":"Owner type discriminator. Always `USER`."},"id":{"type":"string","description":"Harness user id."},"email":{"type":"string","format":"email","description":"User email address."}}},"GroupOwnerReferenceInput":{"type":"object","description":"Group owner input.","required":["type","identifier"],"properties":{"type":{"type":"string","enum":["GROUP"],"description":"Owner type discriminator. Always `GROUP`."},"identifier":{"type":"string","description":"Group identifier."}}},"FeatureFlagResponse":{"type":"object","description":"Mutation response (create, update, archive, unarchive): entity plus OPA governance.\n","required":["entity","governance"],"properties":{"entity":{"$ref":"#/components/schemas/FeatureFlag"},"governance":{"allOf":[{"$ref":"#/components/schemas/GovernanceResult"}],"description":"OPA governance result for the mutation."}}},"FeatureFlag":{"type":"object","description":"A workspace-scoped Feature Flag entity.","required":["id","name","trafficType","createdAt","status","tags","owners"],"properties":{"id":{"type":"string","format":"uuid","description":"Unique system-assigned identifier for the feature flag."},"name":{"type":"string","description":"Unique feature flag name within the project. Immutable after creation — use this as the\npath parameter in subsequent requests.\n"},"description":{"type":"string","nullable":true,"description":"Human-readable description of this feature flag."},"trafficType":{"allOf":[{"$ref":"#/components/schemas/NamedReference"}],"description":"Reference to the traffic type used to bucket users."},"createdAt":{"type":"string","format":"date-time","description":"ISO-8601 timestamp when the feature flag was created."},"status":{"type":"string","enum":["ACTIVE","ARCHIVED"],"description":"Lifecycle status of the feature flag.\n- `ACTIVE` — flag is live.\n- `ARCHIVED` — flag is no longer active and is read-only.\n"},"rolloutStatus":{"allOf":[{"$ref":"#/components/schemas/NamedReference"}],"type":"object","nullable":true,"description":"Rollout status assigned to this feature flag.\n\nThis field is omitted or `null` when no rollout status is assigned. It cannot be set\nwhen creating a feature flag. New feature flags use the workspace default rollout\nstatus. Use PATCH to change it.\n"},"tags":{"type":"array","description":"Tags associated with this feature flag.","items":{"$ref":"#/components/schemas/NamedReference"}},"owners":{"type":"array","description":"Users or teams that own this feature flag. `USER` owners include `email`; `GROUP`\nowners do not.\n","items":{"$ref":"#/components/schemas/OwnerReference"}}}},"NamedReference":{"type":"object","description":"Generic reference to another resource, returned in responses. `id` is the stable\npublic identifier and `name` is the human-readable label.\n","required":["id","name"],"properties":{"id":{"type":"string","description":"Identifier of the referenced resource."},"name":{"type":"string","description":"Human-readable name of the referenced resource."}}},"OwnerReference":{"type":"object","description":"Reference to an owner (user or group), returned in responses. Extends the generic reference\nwith an optional `email`: a `USER` owner MAY carry `email` where the resource populates it;\na `GROUP` owner never has one. Use `id` for subsequent API calls; `name`/`email` are\ninformational (they let clients that keyed on a user's email at write time correlate the\nresponse without a lookup). Shared across FME v4 resources that expose owners.\n","required":["id","type","name"],"properties":{"id":{"type":"string","description":"Identifier of the owner — the Harness user id (for `USER`) or group id (for `GROUP`)."},"type":{"type":"string","enum":["USER","GROUP"],"description":"Owner kind."},"name":{"type":"string","description":"Human-readable display name of the user or group."},"email":{"type":"string","format":"email","nullable":true,"description":"Email address of the owner. Optionally populated for `USER` owners where the resource\nsupports it; `null`/absent for `GROUP` owners and for resources that do not return it.\n"}}},"GovernanceResult":{"type":"object","description":"OPA policy evaluation result for the operation. `PASS`, `WARNING`, and `ERROR` mean\ngovernance ran; `NONE` means governance was not evaluated (for example off or not linked).\n","required":["status","details"],"properties":{"status":{"type":"string","enum":["PASS","WARNING","ERROR","NONE"],"description":"Overall governance result. `NONE` when governance did not run; otherwise the aggregate\nacross evaluated policies.\n"},"details":{"type":"array","description":"Per-policy results. Empty array when all policies pass cleanly or when status is `NONE`.","items":{"$ref":"#/components/schemas/GovernancePolicyDetail"}}}},"GovernancePolicyDetail":{"type":"object","description":"Per-policy OPA evaluation result.","required":["policyName","status","message"],"properties":{"policyName":{"type":"string","description":"Name of the OPA policy that was evaluated."},"status":{"type":"string","enum":["PASS","WARNING","ERROR"],"description":"Result of evaluating this specific policy."},"message":{"type":"string","description":"Human-readable explanation of the policy result."}}},"ErrorResponse":{"type":"object","description":"Standard error response following RFC 7807 Problem Details format (Harness ADR 57).\n","required":["type","status","title","errorType"],"properties":{"type":{"type":"string","format":"uri","description":"URI reference to documentation for this error type."},"status":{"type":"integer","description":"HTTP status code."},"title":{"type":"string","description":"Short human-readable summary of the problem."},"errorType":{"type":"string","description":"Machine-readable error type identifier."},"detail":{"type":"string","description":"Detailed human-readable explanation specific to this occurrence."},"instance":{"type":"string","description":"URI reference identifying the specific occurrence (usually the request path)."},"errors":{"type":"array","description":"List of specific sub-errors (useful for multi-field validation failures). Governance\npolicy failures are also surfaced here — each failing policy is reported as an entry\nwith `errorType: \"governancePolicy\"` — rather than in a separate top-level field.\n","items":{"$ref":"#/components/schemas/ErrorDetail"}}}},"ErrorDetail":{"type":"object","description":"Details about a single sub-error.","required":["errorType","title"],"properties":{"errorType":{"type":"string","description":"Machine-readable error type for this specific error."},"title":{"type":"string","description":"Short summary of this specific error."},"detail":{"type":"string","description":"Detailed explanation of this specific error."},"field":{"type":"string","description":"Name of the request field this error applies to, when the error is field-specific\n(for example a validation failure). Omitted for errors not tied to a single field.\n"}}}},"responses":{"BadRequest":{"description":"Bad Request — validation errors or invalid state transition.\n","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Unauthorized — the request is missing a valid API key, or the key has expired.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Forbidden":{"description":"Forbidden — the caller is authenticated but not permitted to perform this operation.\nReturned when the API can deny the operation without leaking whether a resource exists,\nsuch as create, or write operations where the caller can already read the resource. When\nreturning `403` would reveal resource existence, the API returns `404` instead.\n\nEnvironment-scoped mutations that require approval also return `403`.\n","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFound":{"description":"Not Found — the requested resource does not exist. Also returned when the caller lacks\naccess to the resource (to avoid leaking resource existence).\n","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"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-flags/{feature-flag-name}":{"patch":{"tags":["Feature Flags"],"operationId":"updateFeatureFlag","summary":"Update a Feature Flag (partial)","description":"Partially updates a Feature Flag using JSON Merge Patch semantics (RFC 7396). Only fields\npresent in the request body are modified; omitted fields are left unchanged. JSON `null` (or\n`[]` for arrays) clears `description`, `tags`, and `owners`. `rolloutStatus` cannot be\ncleared: omit the field to leave it unchanged; JSON `null` returns `400`.\n\nOnly `ACTIVE` feature flags can be updated. Patching a non-active flag returns `400`\n(`invalidState`). Changing rollout status while an open change request exists returns `409`\n(`pendingChangeConflict`).\n\n**Updatable fields:** `description`, `tags`, `owners`, `rolloutStatus`.\n","parameters":[{"$ref":"#/components/parameters/FeatureFlagName"},{"$ref":"#/components/parameters/AccountId"},{"$ref":"#/components/parameters/OrganizationIdentifier"},{"$ref":"#/components/parameters/ProjectIdentifier"}],"requestBody":{"required":true,"content":{"application/merge-patch+json":{"schema":{"$ref":"#/components/schemas/UpdateFeatureFlagRequest"}}}},"responses":{"200":{"description":"OK — feature flag updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeatureFlagResponse"}}}},"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"}}}}}}
```

## Archive a Feature Flag

> Archives a Feature Flag and cascades the archived state to all definitions across all\
> environments. Once archived, definitions cannot be modified until the flag is unarchived.\
> Archiving a flag that is already \`ARCHIVED\` returns \`400\` (\`invalidState\`). Archiving a\
> flag that has active dependents returns \`409\` (\`hasDependents\`).<br>

```json
{"openapi":"3.0.3","info":{"title":"Harness Feature Management & Experimentation API","version":"4.0.0"},"tags":[{"name":"Feature Flags","description":"Manage workspace-scoped feature flag metadata and lifecycle (create, list, get, update, delete, archive, unarchive)."}],"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}},"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":{"ArchiveUnarchiveFeatureFlagRequest":{"type":"object","description":"Optional metadata supplied when archiving or unarchiving a feature flag.","properties":{"comment":{"type":"string","description":"Optional comment recorded with the action."}}},"FeatureFlagResponse":{"type":"object","description":"Mutation response (create, update, archive, unarchive): entity plus OPA governance.\n","required":["entity","governance"],"properties":{"entity":{"$ref":"#/components/schemas/FeatureFlag"},"governance":{"allOf":[{"$ref":"#/components/schemas/GovernanceResult"}],"description":"OPA governance result for the mutation."}}},"FeatureFlag":{"type":"object","description":"A workspace-scoped Feature Flag entity.","required":["id","name","trafficType","createdAt","status","tags","owners"],"properties":{"id":{"type":"string","format":"uuid","description":"Unique system-assigned identifier for the feature flag."},"name":{"type":"string","description":"Unique feature flag name within the project. Immutable after creation — use this as the\npath parameter in subsequent requests.\n"},"description":{"type":"string","nullable":true,"description":"Human-readable description of this feature flag."},"trafficType":{"allOf":[{"$ref":"#/components/schemas/NamedReference"}],"description":"Reference to the traffic type used to bucket users."},"createdAt":{"type":"string","format":"date-time","description":"ISO-8601 timestamp when the feature flag was created."},"status":{"type":"string","enum":["ACTIVE","ARCHIVED"],"description":"Lifecycle status of the feature flag.\n- `ACTIVE` — flag is live.\n- `ARCHIVED` — flag is no longer active and is read-only.\n"},"rolloutStatus":{"allOf":[{"$ref":"#/components/schemas/NamedReference"}],"type":"object","nullable":true,"description":"Rollout status assigned to this feature flag.\n\nThis field is omitted or `null` when no rollout status is assigned. It cannot be set\nwhen creating a feature flag. New feature flags use the workspace default rollout\nstatus. Use PATCH to change it.\n"},"tags":{"type":"array","description":"Tags associated with this feature flag.","items":{"$ref":"#/components/schemas/NamedReference"}},"owners":{"type":"array","description":"Users or teams that own this feature flag. `USER` owners include `email`; `GROUP`\nowners do not.\n","items":{"$ref":"#/components/schemas/OwnerReference"}}}},"NamedReference":{"type":"object","description":"Generic reference to another resource, returned in responses. `id` is the stable\npublic identifier and `name` is the human-readable label.\n","required":["id","name"],"properties":{"id":{"type":"string","description":"Identifier of the referenced resource."},"name":{"type":"string","description":"Human-readable name of the referenced resource."}}},"OwnerReference":{"type":"object","description":"Reference to an owner (user or group), returned in responses. Extends the generic reference\nwith an optional `email`: a `USER` owner MAY carry `email` where the resource populates it;\na `GROUP` owner never has one. Use `id` for subsequent API calls; `name`/`email` are\ninformational (they let clients that keyed on a user's email at write time correlate the\nresponse without a lookup). Shared across FME v4 resources that expose owners.\n","required":["id","type","name"],"properties":{"id":{"type":"string","description":"Identifier of the owner — the Harness user id (for `USER`) or group id (for `GROUP`)."},"type":{"type":"string","enum":["USER","GROUP"],"description":"Owner kind."},"name":{"type":"string","description":"Human-readable display name of the user or group."},"email":{"type":"string","format":"email","nullable":true,"description":"Email address of the owner. Optionally populated for `USER` owners where the resource\nsupports it; `null`/absent for `GROUP` owners and for resources that do not return it.\n"}}},"GovernanceResult":{"type":"object","description":"OPA policy evaluation result for the operation. `PASS`, `WARNING`, and `ERROR` mean\ngovernance ran; `NONE` means governance was not evaluated (for example off or not linked).\n","required":["status","details"],"properties":{"status":{"type":"string","enum":["PASS","WARNING","ERROR","NONE"],"description":"Overall governance result. `NONE` when governance did not run; otherwise the aggregate\nacross evaluated policies.\n"},"details":{"type":"array","description":"Per-policy results. Empty array when all policies pass cleanly or when status is `NONE`.","items":{"$ref":"#/components/schemas/GovernancePolicyDetail"}}}},"GovernancePolicyDetail":{"type":"object","description":"Per-policy OPA evaluation result.","required":["policyName","status","message"],"properties":{"policyName":{"type":"string","description":"Name of the OPA policy that was evaluated."},"status":{"type":"string","enum":["PASS","WARNING","ERROR"],"description":"Result of evaluating this specific policy."},"message":{"type":"string","description":"Human-readable explanation of the policy result."}}},"ErrorResponse":{"type":"object","description":"Standard error response following RFC 7807 Problem Details format (Harness ADR 57).\n","required":["type","status","title","errorType"],"properties":{"type":{"type":"string","format":"uri","description":"URI reference to documentation for this error type."},"status":{"type":"integer","description":"HTTP status code."},"title":{"type":"string","description":"Short human-readable summary of the problem."},"errorType":{"type":"string","description":"Machine-readable error type identifier."},"detail":{"type":"string","description":"Detailed human-readable explanation specific to this occurrence."},"instance":{"type":"string","description":"URI reference identifying the specific occurrence (usually the request path)."},"errors":{"type":"array","description":"List of specific sub-errors (useful for multi-field validation failures). Governance\npolicy failures are also surfaced here — each failing policy is reported as an entry\nwith `errorType: \"governancePolicy\"` — rather than in a separate top-level field.\n","items":{"$ref":"#/components/schemas/ErrorDetail"}}}},"ErrorDetail":{"type":"object","description":"Details about a single sub-error.","required":["errorType","title"],"properties":{"errorType":{"type":"string","description":"Machine-readable error type for this specific error."},"title":{"type":"string","description":"Short summary of this specific error."},"detail":{"type":"string","description":"Detailed explanation of this specific error."},"field":{"type":"string","description":"Name of the request field this error applies to, when the error is field-specific\n(for example a validation failure). Omitted for errors not tied to a single field.\n"}}}},"responses":{"BadRequest":{"description":"Bad Request — validation errors or invalid state transition.\n","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Unauthorized — the request is missing a valid API key, or the key has expired.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Forbidden":{"description":"Forbidden — the caller is authenticated but not permitted to perform this operation.\nReturned when the API can deny the operation without leaking whether a resource exists,\nsuch as create, or write operations where the caller can already read the resource. When\nreturning `403` would reveal resource existence, the API returns `404` instead.\n\nEnvironment-scoped mutations that require approval also return `403`.\n","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFound":{"description":"Not Found — the requested resource does not exist. Also returned when the caller lacks\naccess to the resource (to avoid leaking resource existence).\n","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"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-flags/{feature-flag-name}/archive":{"post":{"tags":["Feature Flags"],"operationId":"archiveFeatureFlag","summary":"Archive a Feature Flag","description":"Archives a Feature Flag and cascades the archived state to all definitions across all\nenvironments. Once archived, definitions cannot be modified until the flag is unarchived.\nArchiving a flag that is already `ARCHIVED` returns `400` (`invalidState`). Archiving a\nflag that has active dependents returns `409` (`hasDependents`).\n","parameters":[{"$ref":"#/components/parameters/FeatureFlagName"},{"$ref":"#/components/parameters/AccountId"},{"$ref":"#/components/parameters/OrganizationIdentifier"},{"$ref":"#/components/parameters/ProjectIdentifier"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArchiveUnarchiveFeatureFlagRequest"}}}},"responses":{"200":{"description":"OK — feature flag archived.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeatureFlagResponse"}}}},"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"}}}}}}
```

## Unarchive a Feature Flag

> Restores a previously archived Feature Flag to active state so its definitions can be\
> modified again. Unarchiving a flag that is already \`ACTIVE\` returns \`400\` (\`invalidState\`).<br>

```json
{"openapi":"3.0.3","info":{"title":"Harness Feature Management & Experimentation API","version":"4.0.0"},"tags":[{"name":"Feature Flags","description":"Manage workspace-scoped feature flag metadata and lifecycle (create, list, get, update, delete, archive, unarchive)."}],"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}},"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":{"ArchiveUnarchiveFeatureFlagRequest":{"type":"object","description":"Optional metadata supplied when archiving or unarchiving a feature flag.","properties":{"comment":{"type":"string","description":"Optional comment recorded with the action."}}},"FeatureFlagResponse":{"type":"object","description":"Mutation response (create, update, archive, unarchive): entity plus OPA governance.\n","required":["entity","governance"],"properties":{"entity":{"$ref":"#/components/schemas/FeatureFlag"},"governance":{"allOf":[{"$ref":"#/components/schemas/GovernanceResult"}],"description":"OPA governance result for the mutation."}}},"FeatureFlag":{"type":"object","description":"A workspace-scoped Feature Flag entity.","required":["id","name","trafficType","createdAt","status","tags","owners"],"properties":{"id":{"type":"string","format":"uuid","description":"Unique system-assigned identifier for the feature flag."},"name":{"type":"string","description":"Unique feature flag name within the project. Immutable after creation — use this as the\npath parameter in subsequent requests.\n"},"description":{"type":"string","nullable":true,"description":"Human-readable description of this feature flag."},"trafficType":{"allOf":[{"$ref":"#/components/schemas/NamedReference"}],"description":"Reference to the traffic type used to bucket users."},"createdAt":{"type":"string","format":"date-time","description":"ISO-8601 timestamp when the feature flag was created."},"status":{"type":"string","enum":["ACTIVE","ARCHIVED"],"description":"Lifecycle status of the feature flag.\n- `ACTIVE` — flag is live.\n- `ARCHIVED` — flag is no longer active and is read-only.\n"},"rolloutStatus":{"allOf":[{"$ref":"#/components/schemas/NamedReference"}],"type":"object","nullable":true,"description":"Rollout status assigned to this feature flag.\n\nThis field is omitted or `null` when no rollout status is assigned. It cannot be set\nwhen creating a feature flag. New feature flags use the workspace default rollout\nstatus. Use PATCH to change it.\n"},"tags":{"type":"array","description":"Tags associated with this feature flag.","items":{"$ref":"#/components/schemas/NamedReference"}},"owners":{"type":"array","description":"Users or teams that own this feature flag. `USER` owners include `email`; `GROUP`\nowners do not.\n","items":{"$ref":"#/components/schemas/OwnerReference"}}}},"NamedReference":{"type":"object","description":"Generic reference to another resource, returned in responses. `id` is the stable\npublic identifier and `name` is the human-readable label.\n","required":["id","name"],"properties":{"id":{"type":"string","description":"Identifier of the referenced resource."},"name":{"type":"string","description":"Human-readable name of the referenced resource."}}},"OwnerReference":{"type":"object","description":"Reference to an owner (user or group), returned in responses. Extends the generic reference\nwith an optional `email`: a `USER` owner MAY carry `email` where the resource populates it;\na `GROUP` owner never has one. Use `id` for subsequent API calls; `name`/`email` are\ninformational (they let clients that keyed on a user's email at write time correlate the\nresponse without a lookup). Shared across FME v4 resources that expose owners.\n","required":["id","type","name"],"properties":{"id":{"type":"string","description":"Identifier of the owner — the Harness user id (for `USER`) or group id (for `GROUP`)."},"type":{"type":"string","enum":["USER","GROUP"],"description":"Owner kind."},"name":{"type":"string","description":"Human-readable display name of the user or group."},"email":{"type":"string","format":"email","nullable":true,"description":"Email address of the owner. Optionally populated for `USER` owners where the resource\nsupports it; `null`/absent for `GROUP` owners and for resources that do not return it.\n"}}},"GovernanceResult":{"type":"object","description":"OPA policy evaluation result for the operation. `PASS`, `WARNING`, and `ERROR` mean\ngovernance ran; `NONE` means governance was not evaluated (for example off or not linked).\n","required":["status","details"],"properties":{"status":{"type":"string","enum":["PASS","WARNING","ERROR","NONE"],"description":"Overall governance result. `NONE` when governance did not run; otherwise the aggregate\nacross evaluated policies.\n"},"details":{"type":"array","description":"Per-policy results. Empty array when all policies pass cleanly or when status is `NONE`.","items":{"$ref":"#/components/schemas/GovernancePolicyDetail"}}}},"GovernancePolicyDetail":{"type":"object","description":"Per-policy OPA evaluation result.","required":["policyName","status","message"],"properties":{"policyName":{"type":"string","description":"Name of the OPA policy that was evaluated."},"status":{"type":"string","enum":["PASS","WARNING","ERROR"],"description":"Result of evaluating this specific policy."},"message":{"type":"string","description":"Human-readable explanation of the policy result."}}},"ErrorResponse":{"type":"object","description":"Standard error response following RFC 7807 Problem Details format (Harness ADR 57).\n","required":["type","status","title","errorType"],"properties":{"type":{"type":"string","format":"uri","description":"URI reference to documentation for this error type."},"status":{"type":"integer","description":"HTTP status code."},"title":{"type":"string","description":"Short human-readable summary of the problem."},"errorType":{"type":"string","description":"Machine-readable error type identifier."},"detail":{"type":"string","description":"Detailed human-readable explanation specific to this occurrence."},"instance":{"type":"string","description":"URI reference identifying the specific occurrence (usually the request path)."},"errors":{"type":"array","description":"List of specific sub-errors (useful for multi-field validation failures). Governance\npolicy failures are also surfaced here — each failing policy is reported as an entry\nwith `errorType: \"governancePolicy\"` — rather than in a separate top-level field.\n","items":{"$ref":"#/components/schemas/ErrorDetail"}}}},"ErrorDetail":{"type":"object","description":"Details about a single sub-error.","required":["errorType","title"],"properties":{"errorType":{"type":"string","description":"Machine-readable error type for this specific error."},"title":{"type":"string","description":"Short summary of this specific error."},"detail":{"type":"string","description":"Detailed explanation of this specific error."},"field":{"type":"string","description":"Name of the request field this error applies to, when the error is field-specific\n(for example a validation failure). Omitted for errors not tied to a single field.\n"}}}},"responses":{"BadRequest":{"description":"Bad Request — validation errors or invalid state transition.\n","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Unauthorized — the request is missing a valid API key, or the key has expired.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Forbidden":{"description":"Forbidden — the caller is authenticated but not permitted to perform this operation.\nReturned when the API can deny the operation without leaking whether a resource exists,\nsuch as create, or write operations where the caller can already read the resource. When\nreturning `403` would reveal resource existence, the API returns `404` instead.\n\nEnvironment-scoped mutations that require approval also return `403`.\n","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFound":{"description":"Not Found — the requested resource does not exist. Also returned when the caller lacks\naccess to the resource (to avoid leaking resource existence).\n","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"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-flags/{feature-flag-name}/unarchive":{"post":{"tags":["Feature Flags"],"operationId":"unarchiveFeatureFlag","summary":"Unarchive a Feature Flag","description":"Restores a previously archived Feature Flag to active state so its definitions can be\nmodified again. Unarchiving a flag that is already `ACTIVE` returns `400` (`invalidState`).\n","parameters":[{"$ref":"#/components/parameters/FeatureFlagName"},{"$ref":"#/components/parameters/AccountId"},{"$ref":"#/components/parameters/OrganizationIdentifier"},{"$ref":"#/components/parameters/ProjectIdentifier"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArchiveUnarchiveFeatureFlagRequest"}}}},"responses":{"200":{"description":"OK — feature flag unarchived.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeatureFlagResponse"}}}},"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"}}}}}}
```
