Create Distributions

View as Markdown

POST
/workspaces
/:workspace
/distributions

Create a new distribution

Request

REQUIRED SCOPES

DISTRIBUTION_ADD

URL PARAMETERS

workspacerequiredstring

The human-readable ID of the workspace

Example: "my-company"

BODY PARAMETERS

namerequiredstring

The name of the distribution

scoperequiredstring enum

The scope of the distribution

Allowed enum:

WORKSPACE,

PROJECT,

ENVIRONMENT

identifierstring

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

project_namestring

The name of the project for the distribution

environment_idstring

The ID of the environment for the distribution

permissionsPermissionsView

Access permissions configuration

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 distribution

identifierstring

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

namestring

The name of the distribution

disabledboolean

Indicates if the distribution is disabled

scopestring enum

The scope of the distribution

Allowed enum:

WORKSPACE,

PROJECT,

ENVIRONMENT

projectShortProjectView

Short representation of a project

environmentShortEnvironmentView

Short representation of an environment object

routesRouteView[]

The list of routes associated with the distribution

permissionsPermissionsView

Access permissions configuration

Last modified on Jun 29, 2026

List Distributions Get Distributions

Examples

Create a new distribution in a workspace Create a new distribution in a project Create a new distribution in an environment

Example: Create a new distribution in a workspace


curl -X POST "https://api.buddy.works/workspaces/:workspace/distributions" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "My Distribution",
  "scope": "WORKSPACE",
  "identifier": "my-distribution"
}'

Example: Create a new distribution in a project


curl -X POST "https://api.buddy.works/workspaces/:workspace/distributions" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "My Distribution",
  "scope": "PROJECT",
  "identifier": "my-distribution",
  "project_name": "my-project"
}'

Example: Create a new distribution in an environment


curl -X POST "https://api.buddy.works/workspaces/:workspace/distributions" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "My Distribution",
  "scope": "ENVIRONMENT",
  "identifier": "my-distribution",
  "environment_id": "3a4KbBQl"
}'

EXAMPLE RESPONSE
{
  "url": "https://api.buddy.works/workspaces/my-workspace/distributions/rm1P93jG",
  "html_url": "https://app.buddy.works/my-workspace/-/routing/rm1P93jG/routes",
  "id": "rm1P93jG",
  "identifier": "test",
  "name": "test",
  "disabled": false,
  "scope": "WORKSPACE",
  "routes": [
    {
      "url": "https://api.buddy.works/workspaces/my-workspace/distributions/rm1P93jG/routes/1ObP9zw8",
      "html_url": "https://app.buddy.works/my-workspace/-/routing/rm1P93jG/route/1ObP9zw8",
      "id": "1ObP9zw8",
      "type": "PROXY",
      "subdomain": "testing3",
      "domain": "buddy.works",
      "path": "",
      "targets": {
        "Default": {
          "type": "EXTERNAL",
          "external_url": "kordos.com"
        }
      }
    },
    {
      "url": "https://api.buddy.works/workspaces/my-workspace/distributions/rm1P93jG/routes/VXb2ZOb3",
      "html_url": "https://app.buddy.works/my-workspace/-/routing/rm1P93jG/route/VXb2ZOb3",
      "id": "VXb2ZOb3",
      "type": "PROXY",
      "subdomain": "tunnel",
      "domain": "buddy.works",
      "path": "",
      "targets": {
        "Default": {
          "type": "TUNNEL",
          "tunnel": {
            "id": "bartshoot",
            "tunnel_id": "test"
          }
        }
      }
    },
    {
      "url": "https://api.buddy.works/workspaces/my-workspace/distributions/rm1P93jG/routes/JqbOmp06",
      "html_url": "https://app.buddy.works/my-workspace/-/routing/rm1P93jG/route/JqbOmp06",
      "id": "JqbOmp06",
      "type": "PROXY",
      "subdomain": "asdf",
      "domain": "buddy.works",
      "path": "asd",
      "targets": {
        "COUNTRY-PL": {
          "type": "EXTERNAL",
          "external_url": "testpl.com"
        },
        "CONTINENT-Europe": {
          "type": "EXTERNAL",
          "external_url": "testeu.com"
        },
        "Default": {
          "type": "EXTERNAL",
          "external_url": "test.com"
        }
      }
    }
  ],
  "permissions": {
    "others": "READ_ONLY",
    "users": [
      {
        "id": 1,
        "access_level": "MANAGE"
      }
    ]
  }
}

STATUS
201 Created