Create Routes

View as Markdown

POST
/workspaces
/:workspace
/distributions
/:distribution_id
/routes

Create a new route

Request

REQUIRED SCOPES

DISTRIBUTION_ADD

URL PARAMETERS

workspacerequiredstring

The human-readable ID of the workspace

Example: "my-company"

distribution_idrequiredstring

The ID of the distribution

Example: "nZrnl40Y"

GET PARAMETERS

project_namestring

Project name to filter distributions

Example: "my-project"

environment_idstring

Environment ID to filter distributions

Example: "3a4KbBQl"

BODY PARAMETERS

typerequiredstring enum

The type of the route

Allowed enum:

PROXY,

REDIRECT,

CLOAKING,

PROXY_NO_CACHE

targetsrequiredobject

The targets of the route

subdomainstring

Subdomain for the route. For a claimable domain, the rightmost label is extracted as the claim.

domainstring

Optional. Domain on which the route is created.

pathstring

The path of the route

Response

RESPONSE BODY

typestring enum

The type of the route

Allowed enum:

PROXY,

REDIRECT,

CLOAKING,

PROXY_NO_CACHE

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 route

subdomainstring

The subdomain of the route

domainstring

The domain of the route

pathstring

The path of the route

zone_typestring enum

The type of DNS zone for custom domain routing

Allowed enum:

ROUTING,

CLAIMABLE,

USER,

CLAIMED,

NS_POINTED,

CNAME_POINTED

targetsobject

The targets of the route

Last modified on Jun 29, 2026

List Routes Get Routes

Examples

Create a route with external target Create a route with artifact target Create a route with sandbox target Create a route with tunnel target

Example: Create a route with external target


curl -X POST "https://api.buddy.works/workspaces/:workspace/distributions/:distribution_id/routes" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "PROXY",
  "subdomain": "api",
  "targets": {
    "default": {
      "type": "EXTERNAL",
      "external_url": "https://example.com"
    }
  }
}'

Example: Create a route with artifact target


curl -X POST "https://api.buddy.works/workspaces/:workspace/distributions/:distribution_id/routes" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "PROXY",
  "subdomain": "app",
  "targets": {
    "default": {
      "type": "ARTIFACT",
      "artifact": {
        "id": "P41GZ4jq",
        "version_id": "pzR3j3gN"
      }
    }
  }
}'

Example: Create a route with sandbox target


curl -X POST "https://api.buddy.works/workspaces/:workspace/distributions/:distribution_id/routes" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "PROXY",
  "subdomain": "preview",
  "targets": {
    "default": {
      "type": "SANDBOX",
      "sandbox": {
        "id": "ynjuqe2kov258",
        "endpoint": "www"
      }
    }
  }
}'

Example: Create a route with tunnel target


curl -X POST "https://api.buddy.works/workspaces/:workspace/distributions/:distribution_id/routes" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "PROXY",
  "subdomain": "dev",
  "targets": {
    "default": {
      "type": "TUNNEL",
      "tunnel": {
        "id": "yZ8xW7vU",
        "tunnel_id": "rS5tP4oN"
      }
    }
  }
}'

EXAMPLE RESPONSE
{
  "url": "https://api.buddy.works/workspaces/my-workspace/distributions/gNYmaWYw/routes/dybEM2bg?project_name=my-project",
  "html_url": "https://app.buddy.works/my-workspace/my-project/routing/gNYmaWYw/route/dybEM2bg",
  "id": "dybEM2bg",
  "type": "PROXY",
  "subdomain": "sandbox",
  "domain": "buddy.works",
  "path": "",
  "targets": {
    "Default": {
      "type": "SANDBOX",
      "sandbox": {
        "id": "ynjuqe2kov258",
        "endpoint": "www"
      }
    }
  }
}

STATUS
201 Created