NOnocodb
Environments

Create Environment

Changed on

Create a custom environment in a workspace. The stable key slug is auto-derived from the title server-side (lowercased, non-alphanumeric runs collapsed to -, capped at 50 characters) and frozen thereafter — clients never send a key. Titles that collide with a built-in environment name (Production / Staging) or derive to a key already in use are rejected.

Requires Workspace Owner or Workspace Creator role. Plan-gated: the plan must include the custom-environments feature and the workspace must be within its custom-environment limit.

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.

post/api/v3/meta/workspaces/{workspaceId}/environments

Request

Path parameters

workspaceIdstring required

Workspace ID

Request body

titlestring required

Environment name. Must contain at least one letter or number, must not collide with a built-in environment name (Production / Staging), and must derive to a key not already in use in the scope.

descriptionstring

Optional description shown on the environment card / editor

colorstring

Solid color (hex) used for the environment’s dot / badge

ordernumber

Display position among environments; defaults to the end of the list. Write-only — it is persisted but is not returned on any environment response.

Example request

{
  "title": "QA",
  "description": "Pre-release verification",
  "color": "#6A7184",
  "order": 1
}

Response

Created environment

idstring required

Environment ID. Custom environments use a generated ID; the built-in environments use their reserved key (production / staging).

keystring 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.

titlestring required

Human-readable environment name

descriptionstring nullable

Optional description shown on the environment card / editor

colorstring nullable

Solid color (hex) used for the environment’s dot / badge

is_defaultboolean required

True only for the built-in production environment — the fallback whose configuration is the integration’s own config.

is_lockedboolean required

True for the built-in environments (production / staging) — they cannot be renamed or deleted.

workspace_idstring

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_idstring

Present on organization-scoped environments, which are shared by all of the organization’s workspaces.

created_atstring date-time

Creation timestamp (absent on the virtual built-in environments)

updated_atstring date-time

Last update timestamp (absent on the virtual built-in environments)

created_bystring

ID of the user who created the environment (absent on the virtual built-in environments)

Example response

{
  "id": "envabc12345",
  "key": "qa",
  "title": "QA",
  "description": "Pre-release verification",
  "color": "#6A7184",
  "workspace_id": "w6dw3fo0",
  "org_id": "org123",
  "created_by": "usr1234567"
}

Changes