---
title: "Create Organization Environment"
method: POST
path: "/api/v3/meta/orgs/{orgId}/environments"
tags: ["Environments"]
---

# Create Organization Environment

`POST /api/v3/meta/orgs/{orgId}/environments`

## Request

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

Create a custom environment at the organization level, shared by all of the organization’s workspaces. The stable `key` slug is auto-derived from the title server-side 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 **Org Owner** role. Available on cloud-hosted plans with organizations.

**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

- `orgId` string, required

## Request body

- EnvironmentCreateV3Req: Environment creation request for v3 API. Creates a CUSTOM environment — the built-in `production` and `staging` environments always exist and cannot be created. The stable `key` slug is auto-derived from the title server-side; clients never send a key.
  - `title` string, 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.
  - `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; defaults to the end of the list. Write-only — it is persisted but is not returned on any environment response.

## Response `200`

Created 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/orgs/:orgId/environments/post.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)