# Create

`POST /workspaces/:workspace/distributions`

Create a new distribution

**Required Scopes:** `DISTRIBUTION_ADD`

## URL Parameters

```typescript
interface URLParameters {
  /** The human-readable ID of the workspace */
  workspace: string; // Example: "my-company"
}
```

## Body Parameters

```typescript
interface BodyParameters {
  /** The name of the distribution */
  name: string;
  /** The scope of the distribution */
  scope: "WORKSPACE" | "PROJECT" | "ENVIRONMENT";
  /** A human-readable ID of the distribution. Alphanumeric characters, underscores, and hyphens (hyphens cannot appear at the start or end). */
  identifier?: string;
  /** The name of the project for the distribution */
  project_name?: string;
  /** The ID of the environment for the distribution */
  environment_id?: string;
  /** Access permissions configuration */
  permissions?: PermissionsView;
}
```

## Response Body

```typescript
interface ResponseBody {
  /** API endpoint to GET this object */
  url?: string;
  /** Web URL to view this object in Buddy.works */
  html_url?: string;
  /** The ID of the distribution */
  id?: number;
  /** A human-readable ID of the distribution. Alphanumeric characters, underscores, and hyphens (hyphens cannot appear at the start or end). */
  identifier?: string;
  /** The name of the distribution */
  name?: string;
  /** Indicates if the distribution is disabled */
  disabled?: boolean;
  /** The scope of the distribution */
  scope?: "WORKSPACE" | "PROJECT" | "ENVIRONMENT";
  /** Short representation of a project */
  project?: ShortProjectView;
  /** Short representation of an environment object */
  environment?: ShortEnvironmentView;
  /** The list of routes associated with the distribution */
  routes?: RouteView[];
  /** Access permissions configuration */
  permissions?: PermissionsView;
}
```

## Type Definitions

```typescript
interface PermissionsView {
  /** Access level for other workspace members */
  others?: "DENIED" | "READ_ONLY" | "USE_ONLY" | "BLIND" | "RUN_ONLY" | "READ_WRITE" | "MANAGE" | "DEFAULT" | "ALLOWED" | "STAGE" | "COMMIT";
  /** List of specific users with their access levels */
  users?: UserPermissionView[];
  /** List of user groups with their access levels */
  groups?: GroupPermissionView[];
}

interface UserPermissionView {
  /** The ID of the user */
  id?: number;
  /** The access level for the user */
  access_level?: "DENIED" | "READ_ONLY" | "USE_ONLY" | "BLIND" | "RUN_ONLY" | "READ_WRITE" | "MANAGE" | "DEFAULT" | "ALLOWED" | "STAGE" | "COMMIT";
}

interface GroupPermissionView {
  /** The ID of the group */
  id?: number;
  /** The access level for the group */
  access_level?: "DENIED" | "READ_ONLY" | "USE_ONLY" | "BLIND" | "RUN_ONLY" | "READ_WRITE" | "MANAGE" | "DEFAULT" | "ALLOWED" | "STAGE" | "COMMIT";
}

interface ShortProjectView {
  /** API endpoint to GET this object */
  url?: string;
  /** Web URL to view this object in Buddy.works */
  html_url?: string;
  /** The human-readable ID of the project */
  name?: string;
  /** The Name of the project */
  display_name: string;
  /** The status of the project */
  status?: string;
  /** Indicates if this is a public project */
  access?: "PRIVATE" | "PUBLIC";
  /** The creation date of the project */
  create_date?: string;
}

interface ShortEnvironmentView {
  /** API endpoint to GET this object */
  url?: string;
  /** Web URL to view this object in Buddy.works */
  html_url?: string;
  /** The name of the environment */
  name?: string;
  /** The human-readable identifier of the environment */
  identifier?: string;
  /** The ID of the environment */
  id?: number;
  /** The scope level of the environment */
  scope?: "PROJECT" | "WORKSPACE" | "ANY";
}

interface RouteView {
  /** API endpoint to GET this object */
  url?: string;
  /** Web URL to view this object in Buddy.works */
  html_url?: string;
  /** The ID of the route */
  id?: number;
  /** The type of the route */
  type?: "PROXY" | "REDIRECT" | "CLOAKING" | "PROXY_NO_CACHE";
  /** The subdomain of the route */
  subdomain?: string;
  /** The domain of the route */
  domain?: string;
  /** The path of the route */
  path?: string;
  /** The type of DNS zone for custom domain routing */
  zone_type?: "ROUTING" | "CLAIMABLE" | "USER" | "CLAIMED" | "NS_POINTED" | "CNAME_POINTED";
  /** The targets of the route */
  targets?: object;
}

```

## Request Example

```bash
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"
}'
```

## Response Example

**Status:** `201 Created`

```json
{
  "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"
      }
    ]
  }
}
```

---
Original source: https://buddy.works/docs/api/distributions/create