Skip to main content
POST /api/v1/projects/{project_id}/environments Requires environments.write permission. The current region is automatically assigned to the new environment.

​
Path parameters

​
project_id
string
required
UUID of the project.

​
Request body

​
key
string
required
Machine-readable identifier for the environment. Example: production.
​
name
string
required
Human-readable display name. Example: Production.
​
description
string | null
Optional description. Pass null to leave it unset.

​
Response

​
environment
object
required
The newly created environment.

​
Errors

StatusWhen
400Request body is invalid or missing required fields
403Caller lacks environments.write permission
409An environment with the same key already exists in this project

​
Example

curl -X POST http://localhost:8080/api/v1/projects/p1b2c3d4-e5f6-7890-abcd-ef1234567890/environments \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"key": "production", "name": "Production", "description": "Production environment"}'

{
  "environment": {
    "id": "e1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "project_id": "p1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "key": "production",
    "name": "Production",
    "description": "Production environment",
    "created_at": "2026-03-21T10:00:00Z",
    "updated_at": "2026-03-21T10:00:00Z"
  }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us