---
title: "List Environments"
method: GET
path: "/api/v3/meta/workspaces/{workspaceId}/environments"
tags: ["Environments"]
---

# List Environments

`GET /api/v3/meta/workspaces/{workspaceId}/environments`

## Request

- Base URL: `https://app.nocodb.com`
- URL: `https://app.nocodb.com/api/v3/meta/workspaces/{workspaceId}/environments`
- 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/get.ts> (a function with typed inputs; its response is checked against the schema)

Retrieve the effective environment set for a workspace: the built-in `production` and `staging` environments (virtual, locked — present for every workspace with no stored row), plus the organization’s shared environments and the workspace’s own custom environments. Environments resolve per-environment integration configuration.

Requires **Workspace Viewer** role or above — listing is read-only. Creating, updating and deleting custom environments requires **Workspace Owner** or **Workspace Creator**.

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

## Response `200`

List of environments

- object
  - `list` EnvironmentV3[], required
    - `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.
- `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/get.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)