Create

POST
/workspaces
/:workspace
/environments

Creates a new environment in the workspace.

Request

REQUIRED SCOPES

ENVIRONMENT_ADD

URL PARAMETERS

workspacerequiredstring

The workspace name.

POST PARAMETERS

namerequiredstring

The name of the environment.

identifierrequiredstring

Readable ID for environment. It can consist of lowercase letters, numbers, and underscores. It must start with a letter.

scopestring

The scope of the environment. Available values: PROJECT, WORKSPACE, ANY. Default: WORKSPACE.

projectobject

The project. Required when scope is PROJECT.

iconstring

The environment icon.

public_urlstring

The public URL for the environment.

tagsstring[]

A list of tags.

base_onlyboolean

If true, the environment can only be used as a base for other environments.

base_environmentsstring[]

Array of base environment identifiers that this environment inherits from.

variablesvariable[]

Define to set variables for the environment.

permissionspermission

Define to set permissions for the environment.

all_pipelines_allowedboolean

Defines whether all pipelines are allowed to use the environment.

allowed_pipelinesAllowedPipeline[]

List of pipelines that can use this environment.

all_environments_allowedboolean

Defines whether all environments can inherit this environment.

allowed_environmentsAllowedEnvironment[]

List of environments that can inherit this environment.

Last modified on Jan 20, 2026

Personal Access Token Get

Request example


curl -X POST "https://api.buddy.works/workspaces/:workspace/environments" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "identifier": "stage_env",
  "name": "Staging environment",
  "scope": "PROJECT",
  "project": {
    "name": "company-website"
  },
  "icon": "rocket",
  "tags": [
    "staging",
    "tag1"
  ],
  "public_url": "http://staging.com",
  "base_only": false,
  "variables": [
    {
      "key": "myVar1",
      "value": "myValue1",
      "type": "VAR",
      "settable": true,
      "encrypted": false,
      "description": "some variable1"
    }
  ],
  "permissions": {
    "others": "DENIED",
    "users": [
      {
        "id": 1,
        "access_level": "MANAGE"
      }
    ],
    "groups": [
      {
        "id": 2,
        "access_level": "USE_ONLY"
      }
    ]
  },
  "all_pipelines_allowed": false,
  "allowed_pipelines": [
    {
      "project": "company-website",
      "pipeline": "deploy-prod"
    }
  ],
  "all_environments_allowed": false,
  "allowed_environments": [
    {
      "project": "company-website",
      "environment": "development"
    }
  ]
}'

Response

EXAMPLE RESPONSE
{
  "url": "https://api.buddy.works/workspaces/buddy/environments/9DBbgP4q",
  "html_url": "https://app.buddy.works/buddy/environments/environment/9DBbgP4q",
  "id": "9DBbgP4q",
  "name": "Staging environment",
  "identifier": "stage_env",
  "scope": "PROJECT",
  "icon": "rocket",
  "tags": [
    "staging",
    "tag1"
  ],
  "public_url": "http://staging.com",
  "base_only": false,
  "base_environments": [],
  "all_pipelines_allowed": false,
  "allowed_pipelines": [
    {
      "project": "company-website",
      "pipeline": "deploy-prod"
    }
  ],
  "all_environments_allowed": false,
  "allowed_environments": [
    {
      "project": "company-website",
      "environment": "development"
    }
  ],
  "project": {
    "url": "https://api.buddy.works/workspaces/buddy/projects/company-website",
    "html_url": "https://app.buddy.works/buddy/company-website",
    "name": "company-website",
    "display_name": "Company Website"
  },
  "variables": [
    {
      "id": 1,
      "key": "myVar1",
      "value": "myValue1",
      "type": "VAR",
      "settable": true,
      "run_only_settable": false,
      "description": "some variable1"
    }
  ],
  "permissions": {
    "others": "DENIED",
    "users": [
      {
        "id": 1,
        "access_level": "MANAGE"
      }
    ],
    "groups": [
      {
        "id": 2,
        "access_level": "USE_ONLY"
      }
    ]
  }
}

STATUS
201 Created