Create

View as Markdown

POST
/workspaces
/:workspace
/environments

Create a new environment

Request

REQUIRED SCOPES

ENVIRONMENT_MANAGE

URL PARAMETERS

workspacerequiredstring

The human-readable ID of the workspace

Example: "my-company"

POST PARAMETERS

namerequiredstring

The name of the environment

identifierrequiredstring

A human-readable ID of the environment. Alphanumeric characters, underscores, and hyphens (hyphens cannot appear at the start or end).

tagsstring[]

The list of tags associated with the environment

Constraints: Unique items required

iconstring

The icon of the environment

public_urlstring

The public URL of the environment

all_pipelines_allowedboolean

Indicates if all pipelines can inherit to this environment

all_environments_allowedboolean

Indicates if all pipelines can use this environment

allowed_pipelinesAllowedPipelineRequest[]

The List of pipelines that can use this environment (specified by project slug and pipeline slug)

allowed_environmentsAllowedEnvironmentRequest[]

The List of environments that can inherit this environment (specified by project slug and environment slug)

projectProjectReference

The project to which the environment is assigned (specified by project slug)

permissionsPermissionsView

Access permissions configuration

base_environmentsstring[]

The list of environments that is used as a base for this environment (specified by project slug and environment slug)

base_onlyboolean

Indicates if this environment can only be used as a base for other environments

scopestring enum

The scope of the environment

Allowed enum:

PROJECT,

WORKSPACE,

ANY

Response

RESPONSE BODY

urlread-onlystring

API endpoint to GET this object

html_urlread-onlystring

Web URL to view this object in Buddy.works

idinteger

The ID of the environment

namerequiredstring

The name of the environment

identifierstring

A human-readable ID of the environment. Alphanumeric characters, underscores, and hyphens (hyphens cannot appear at the start or end).

tagsstring[]

The list of tags associated with the environment

Constraints: Unique items required

iconstring

The icon of the environment

public_urlstring

The public URL of the environment

all_pipelines_allowedboolean

Indicates if all pipelines can inherit to this environment

all_environments_allowedboolean

Indicates if all pipelines can use this environment

allowed_pipelinesAllowedPipelineView[]

The List of pipelines that can use this environment (specified by project slug and pipeline slug)

allowed_environmentsAllowedEnvironmentView[]

The List of environments that can inherit this environment (specified by project slug and environment slug)

create_datestring

The creation date of the environment

projectShortProjectView

Short representation of a project

permissionsPermissionsView

Access permissions configuration

base_environmentsstring[]

The list of environments that is used as a base for this environment (specified by project slug and environment slug)

targetsTargetView[]

The list of targets associated with the environment

base_onlyboolean

Indicates if this environment can only be used as a base for other environments

scopestring enum

The scope of the environment

Allowed enum:

PROJECT,

WORKSPACE,

ANY

Last modified on Jan 26, 2026

List Get

Examples

Create a new environment in a project Create a new environment in a workspace

Example: Create a new environment in a project


curl -X POST "https://api.buddy.works/workspaces/:workspace/environments" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Production Environment",
  "identifier": "prod-env",
  "tags": [
    "production",
    "stable"
  ],
  "icon": "production.svg",
  "public_url": "https://prod.example.com",
  "all_pipelines_allowed": false,
  "all_environments_allowed": false,
  "scope": "PROJECT",
  "base_only": false,
  "project": {
    "name": "my-project"
  },
  "allowed_pipelines": [
    {
      "project": "my-project",
      "pipeline": "Deploy to Production"
    }
  ],
  "allowed_environments": [
    {
      "project": "my-project",
      "environment": "staging"
    }
  ],
  "base_environments": [
    "staging",
    "development"
  ]
}'

Example: Create a new environment in a workspace


curl -X POST "https://api.buddy.works/workspaces/:workspace/environments" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Staging Environment",
  "identifier": "staging-env",
  "tags": [
    "staging",
    "testing"
  ],
  "icon": "staging.svg",
  "public_url": "https://staging.example.com",
  "all_pipelines_allowed": true,
  "all_environments_allowed": true,
  "scope": "WORKSPACE",
  "base_only": false,
  "allowed_pipelines": [
    {
      "project": "my-project",
      "pipeline": "Deploy to Production"
    }
  ],
  "allowed_environments": [
    {
      "project": "my-project",
      "environment": "staging"
    }
  ],
  "base_environments": [
    "staging",
    "development"
  ]
}'

EXAMPLE RESPONSE
{
  "url": "https://api.buddy.works/workspaces/my-workspace/projects/environments/3a4KbBQl",
  "html_url": "https://my-workspace.buddy.works/environments/environment/3a4KbBQl",
  "id": "3a4KbBQl",
  "name": "Development Environment",
  "identifier": "dev",
  "tags": [
    "development",
    "dev"
  ],
  "icon": "development.svg",
  "public_url": "https://env.myproduct.com",
  "all_pipelines_allowed": false,
  "all_environments_allowed": false,
  "allowed_pipelines": [
    {
      "project": "my-project",
      "pipeline": "Deploy to Dev"
    }
  ],
  "allowed_environments": [
    {
      "project": "my-project",
      "environment": "staging"
    }
  ],
  "create_date": "2024-01-15T10:30:00Z",
  "project": {
    "url": "https://api.buddy.works/workspaces/my-workspace/projects/my-project",
    "html_url": "https://my-workspace.buddy.works/projects/my-project",
    "name": "my-project",
    "display_name": "My Project"
  },
  "permissions": {
    "others": "USE_ONLY",
    "users": [
      {
        "id": 123,
        "access_level": "MANAGE"
      }
    ],
    "groups": [
      {
        "id": 456,
        "access_level": "READ_WRITE"
      }
    ]
  },
  "base_environments": [
    "production",
    "staging"
  ],
  "targets": [
    {
      "url": "https://api.buddy.works/workspaces/my-workspace/projects/my-project/targets/123",
      "html_url": "https://my-workspace.buddy.works/my-project/targets/123",
      "id": "abc123",
      "identifier": "dev-server",
      "type": "SSH"
    }
  ],
  "base_only": false,
  "scope": "PROJECT"
}

STATUS
201 Created