> 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/environments.md).

# Environments

Manage workspace-scoped deployment environments (name, production flag, lifecycle state).

## List Environments

> Returns a paginated list of Environments in the specified project workspace.\
> Defaults to active environments (\`status\` defaults to \`\[ACTIVE]\`).<br>

```json
{"openapi":"3.0.3","info":{"title":"Harness Feature Management & Experimentation API","version":"4.0.0"},"tags":[{"name":"Environments","description":"Manage workspace-scoped deployment environments (name, production flag, lifecycle state)."}],"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":{"EnvironmentListResponse":{"type":"object","description":"Paginated list of Environments matching the query.","required":["data","limit","offset","totalCount"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Environment"}},"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 environments matching the query."}}},"Environment":{"type":"object","description":"A workspace-scoped Environment entity.","required":["id","name","isProduction","createdAt","status"],"properties":{"id":{"type":"string","format":"uuid","description":"Unique system-assigned identifier for the environment."},"name":{"type":"string","description":"Unique environment name within the project. Updatable via PATCH. Use the system-assigned\n`id` as the path parameter in subsequent requests — this field is informational only.\n"},"isProduction":{"type":"boolean","description":"`true` when this environment represents production traffic. Defaults to `false` when\nomitted at creation time.\n"},"createdAt":{"type":"string","format":"date-time","description":"ISO-8601 timestamp when the environment was created."},"status":{"type":"string","enum":["ACTIVE","ARCHIVED"],"description":"Lifecycle status of the environment.\n- `ACTIVE` — environment is live.\n- `ARCHIVED` — environment is no longer active (soft-deleted).\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/environments":{"get":{"tags":["Environments"],"operationId":"listEnvironments","summary":"List Environments","description":"Returns a paginated list of Environments in the specified project workspace.\nDefaults to active environments (`status` defaults to `[ACTIVE]`).\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}],"responses":{"200":{"description":"OK — paginated list of environments returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvironmentListResponse"}}}},"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 an Environment

> Creates a new Environment in the specified project workspace. The environment 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":"Environments","description":"Manage workspace-scoped deployment environments (name, production flag, lifecycle state)."}],"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":{"CreateEnvironmentRequest":{"type":"object","description":"Request body for creating a new Environment.","required":["name"],"properties":{"name":{"type":"string","description":"Unique environment name within the project."},"isProduction":{"type":"boolean","description":"`true` when this environment represents production traffic. Defaults to `false` when\nomitted.\n","default":false}}},"EnvironmentResponse":{"type":"object","description":"Mutation response (create, update): entity plus OPA governance.\n","required":["entity","governance"],"properties":{"entity":{"$ref":"#/components/schemas/Environment"},"governance":{"allOf":[{"$ref":"#/components/schemas/GovernanceResult"}],"description":"OPA governance result for the mutation."}}},"Environment":{"type":"object","description":"A workspace-scoped Environment entity.","required":["id","name","isProduction","createdAt","status"],"properties":{"id":{"type":"string","format":"uuid","description":"Unique system-assigned identifier for the environment."},"name":{"type":"string","description":"Unique environment name within the project. Updatable via PATCH. Use the system-assigned\n`id` as the path parameter in subsequent requests — this field is informational only.\n"},"isProduction":{"type":"boolean","description":"`true` when this environment represents production traffic. Defaults to `false` when\nomitted at creation time.\n"},"createdAt":{"type":"string","format":"date-time","description":"ISO-8601 timestamp when the environment was created."},"status":{"type":"string","enum":["ACTIVE","ARCHIVED"],"description":"Lifecycle status of the environment.\n- `ACTIVE` — environment is live.\n- `ARCHIVED` — environment is no longer active (soft-deleted).\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/environments":{"post":{"tags":["Environments"],"operationId":"createEnvironment","summary":"Create an Environment","description":"Creates a new Environment in the specified project workspace. The environment 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/CreateEnvironmentRequest"}}}},"responses":{"201":{"description":"Created — the environment was successfully created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvironmentResponse"}}}},"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 an Environment

> Returns a single Environment by its system-assigned identifier. Unlike list, this endpoint\
> returns the environment 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":"Environments","description":"Manage workspace-scoped deployment environments (name, production flag, lifecycle state)."}],"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":{"EnvironmentIdPath":{"name":"environment-id","in":"path","required":true,"description":"The system-assigned identifier of the environment. Environment names are free-form\n(may contain spaces) and are not accepted as a path parameter.\n","schema":{"type":"string","format":"uuid","pattern":"^[-_A-Za-z0-9]+$","maxLength":128}},"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":{"Environment":{"type":"object","description":"A workspace-scoped Environment entity.","required":["id","name","isProduction","createdAt","status"],"properties":{"id":{"type":"string","format":"uuid","description":"Unique system-assigned identifier for the environment."},"name":{"type":"string","description":"Unique environment name within the project. Updatable via PATCH. Use the system-assigned\n`id` as the path parameter in subsequent requests — this field is informational only.\n"},"isProduction":{"type":"boolean","description":"`true` when this environment represents production traffic. Defaults to `false` when\nomitted at creation time.\n"},"createdAt":{"type":"string","format":"date-time","description":"ISO-8601 timestamp when the environment was created."},"status":{"type":"string","enum":["ACTIVE","ARCHIVED"],"description":"Lifecycle status of the environment.\n- `ACTIVE` — environment is live.\n- `ARCHIVED` — environment is no longer active (soft-deleted).\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/environments/{environment-id}":{"get":{"tags":["Environments"],"operationId":"getEnvironment","summary":"Get an Environment","description":"Returns a single Environment by its system-assigned identifier. Unlike list, this endpoint\nreturns the environment regardless of lifecycle status (`ACTIVE` or `ARCHIVED`).\n","parameters":[{"$ref":"#/components/parameters/EnvironmentIdPath"},{"$ref":"#/components/parameters/AccountId"},{"$ref":"#/components/parameters/OrganizationIdentifier"},{"$ref":"#/components/parameters/ProjectIdentifier"}],"responses":{"200":{"description":"OK — environment returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Environment"}}}},"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 an Environment

> Soft-deletes an Environment by transitioning it to \`ARCHIVED\`. The environment remains\
> retrievable via GET by id and via LIST when \`status\` includes \`ARCHIVED\`. Returns the OPA\
> governance result for the operation. Deleting an environment that is already \`ARCHIVED\`\
> returns \`404\`. Deleting an environment 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":"Environments","description":"Manage workspace-scoped deployment environments (name, production flag, lifecycle state)."}],"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":{"EnvironmentIdPath":{"name":"environment-id","in":"path","required":true,"description":"The system-assigned identifier of the environment. Environment names are free-form\n(may contain spaces) and are not accepted as a path parameter.\n","schema":{"type":"string","format":"uuid","pattern":"^[-_A-Za-z0-9]+$","maxLength":128}},"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/environments/{environment-id}":{"delete":{"tags":["Environments"],"operationId":"deleteEnvironment","summary":"Delete an Environment","description":"Soft-deletes an Environment by transitioning it to `ARCHIVED`. The environment remains\nretrievable via GET by id and via LIST when `status` includes `ARCHIVED`. Returns the OPA\ngovernance result for the operation. Deleting an environment that is already `ARCHIVED`\nreturns `404`. Deleting an environment that has active dependents returns `409`\n(`hasDependents`).\n","parameters":[{"$ref":"#/components/parameters/EnvironmentIdPath"},{"$ref":"#/components/parameters/AccountId"},{"$ref":"#/components/parameters/OrganizationIdentifier"},{"$ref":"#/components/parameters/ProjectIdentifier"}],"responses":{"200":{"description":"OK — environment 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 an Environment (partial)

> Partially updates an Environment using JSON Merge Patch semantics (RFC 7396). Only fields\
> present in the request body are modified; omitted fields are left unchanged. Sending \`null\`\
> for \`name\` or \`isProduction\` is rejected with \`400\`.\
> \
> Only \`ACTIVE\` environments can be updated. Patching an archived environment returns \`404\`.\
> Renaming to a name already used in the project returns \`409\`.\
> \
> \*\*Updatable fields:\*\* \`name\`, \`isProduction\`.<br>

```json
{"openapi":"3.0.3","info":{"title":"Harness Feature Management & Experimentation API","version":"4.0.0"},"tags":[{"name":"Environments","description":"Manage workspace-scoped deployment environments (name, production flag, lifecycle state)."}],"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":{"EnvironmentIdPath":{"name":"environment-id","in":"path","required":true,"description":"The system-assigned identifier of the environment. Environment names are free-form\n(may contain spaces) and are not accepted as a path parameter.\n","schema":{"type":"string","format":"uuid","pattern":"^[-_A-Za-z0-9]+$","maxLength":128}},"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":{"UpdateEnvironmentRequest":{"type":"object","description":"JSON Merge Patch body (RFC 7396). All fields are optional. Omit a field to leave it\nunchanged. Sending `null` for `name` or `isProduction`, or a blank `name`, is rejected\nwith `400`.\n","properties":{"name":{"type":"string","description":"Updated environment name."},"isProduction":{"type":"boolean","description":"Updated production flag."}}},"EnvironmentResponse":{"type":"object","description":"Mutation response (create, update): entity plus OPA governance.\n","required":["entity","governance"],"properties":{"entity":{"$ref":"#/components/schemas/Environment"},"governance":{"allOf":[{"$ref":"#/components/schemas/GovernanceResult"}],"description":"OPA governance result for the mutation."}}},"Environment":{"type":"object","description":"A workspace-scoped Environment entity.","required":["id","name","isProduction","createdAt","status"],"properties":{"id":{"type":"string","format":"uuid","description":"Unique system-assigned identifier for the environment."},"name":{"type":"string","description":"Unique environment name within the project. Updatable via PATCH. Use the system-assigned\n`id` as the path parameter in subsequent requests — this field is informational only.\n"},"isProduction":{"type":"boolean","description":"`true` when this environment represents production traffic. Defaults to `false` when\nomitted at creation time.\n"},"createdAt":{"type":"string","format":"date-time","description":"ISO-8601 timestamp when the environment was created."},"status":{"type":"string","enum":["ACTIVE","ARCHIVED"],"description":"Lifecycle status of the environment.\n- `ACTIVE` — environment is live.\n- `ARCHIVED` — environment is no longer active (soft-deleted).\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/environments/{environment-id}":{"patch":{"tags":["Environments"],"operationId":"updateEnvironment","summary":"Update an Environment (partial)","description":"Partially updates an Environment using JSON Merge Patch semantics (RFC 7396). Only fields\npresent in the request body are modified; omitted fields are left unchanged. Sending `null`\nfor `name` or `isProduction` is rejected with `400`.\n\nOnly `ACTIVE` environments can be updated. Patching an archived environment returns `404`.\nRenaming to a name already used in the project returns `409`.\n\n**Updatable fields:** `name`, `isProduction`.\n","parameters":[{"$ref":"#/components/parameters/EnvironmentIdPath"},{"$ref":"#/components/parameters/AccountId"},{"$ref":"#/components/parameters/OrganizationIdentifier"},{"$ref":"#/components/parameters/ProjectIdentifier"}],"requestBody":{"required":true,"content":{"application/merge-patch+json":{"schema":{"$ref":"#/components/schemas/UpdateEnvironmentRequest"}}}},"responses":{"200":{"description":"OK — environment updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvironmentResponse"}}}},"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"}}}}}}
```
