---
title: "Update Environment"
method: PATCH
path: "/api/v3/meta/workspaces/{workspaceId}/environments/{environmentId}"
tags: ["Environments"]
---

# Update Environment

`PATCH /api/v3/meta/workspaces/{workspaceId}/environments/{environmentId}`

## Request

- Base URL: `https://app.nocodb.com`
- URL: `https://app.nocodb.com/api/v3/meta/workspaces/{workspaceId}/environments/{environmentId}`
- Auth: one of:
  - API key in header `xc-token`
  - HTTP bearer
- TypeScript: <https://skmtc.dev/nocodb/apis/nocodb-v3/docs/api/v3/meta/workspaces/:workspaceId/environments/:environmentId/patch.ts> (a function with typed inputs; its response is checked against the schema)

Update a custom environment’s title, description, color or order. The `key` slug is frozen at create time — renaming the title never re-derives it, so references to the environment stay valid. The built-in environments (`production` / `staging`) cannot be edited, and org-scoped environments cannot be edited from the workspace routes.

Requires **Workspace Owner** or **Workspace Creator** role.

**Note**: Environment APIs are available only with self-hosted **Enterprise** plans and cloud-hosted plans. Creating custom environments requires a plan that includes the custom-environments feature.

## Path parameters

- `workspaceId` string, required
- `environmentId` string, required

## Request body

- EnvironmentUpdateV3Req: Environment update request for v3 API. Only `title`, `description`, `color` and `order` are editable — the `key` slug is frozen at create time and renaming the title never re-derives it. The built-in environments (`production` / `staging`) cannot be updated.
  - `title` string: New environment name. The `key` slug is NOT re-derived on rename.
  - `description` string: Optional description shown on the environment card / editor
  - `color` string: Solid color (hex) used for the environment’s dot / badge
  - `order` number: Display position among environments. Write-only — it is persisted but is not returned on any environment response.

## Response `200`

Updated environment

- EnvironmentV3: Environment for v3 API — a named stage (production / staging / custom) that resolves per-environment integration configuration. The built-in `production` and `staging` environments are virtual: they exist for every workspace and organization without a stored row, are locked, and use their reserved key as `id`.
  - `id` string, required: Environment ID. Custom environments use a generated ID; the built-in environments use their reserved key (`production` / `staging`).
  - `key` string, required: Stable slug auto-derived from the title at create time and frozen thereafter — renaming the title never changes it. Used to reference the environment.
  - `title` string, required: Human-readable environment name
  - `description` string, nullable: Optional description shown on the environment card / editor
  - `color` string, nullable: Solid color (hex) used for the environment’s dot / badge
  - `is_default` boolean, required: True only for the built-in `production` environment — the fallback whose configuration is the integration’s own config.
  - `is_locked` boolean, required: True for the built-in environments (`production` / `staging`) — they cannot be renamed or deleted.
  - `workspace_id` string: Present on workspace-scoped custom environments. At most one of `workspace_id` / `org_id` is set; both are absent on the virtual built-in environments.
  - `org_id` string: Present on organization-scoped environments, which are shared by all of the organization’s workspaces.
  - `created_at` string, date-time: Creation timestamp (absent on the virtual built-in environments)
  - `updated_at` string, date-time: Last update timestamp (absent on the virtual built-in environments)
  - `created_by` string: ID of the user who created the environment (absent on the virtual built-in environments)

## Other responses

- `400`: Bad request.
- `404`: Environment not found.
- `500`: The server encountered an unexpected error while processing the request.

## Changes

- **2026-10-13** `2ba4267a99d7`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/nocodb/apis/nocodb-v3/changes/api/v3/meta/workspaces/:workspaceId/environments/:environmentId/patch.md)

---

[API](https://skmtc.dev/nocodb/apis/nocodb-v3.md) - [All operations](https://skmtc.dev/nocodb/apis/nocodb-v3/llms.txt) - [OpenAPI document](https://skmtc.dev/nocodb/apis/nocodb-v3/revisions/62a735aaf849?raw)