Last updated on 5th March 2026

Create a new server via API

This method allows you to create a new server.

Tip: You can explore and test this endpoint interactively using our OpenAPI documentation.

URL

/projects/<project>/servers

Replace <project> with either the permalink or identifier of the project.

HTTP Method

POST

Supported Parameters

  • name - Friendly name for your server
  • protocol_type - Connection protocol (see supported types below)
  • server_path - Where on the server should your files be placed (for example, public_html/ or /absolute/path/here)
  • email_notify_on - When do you want to receive email notifications, either never, failure or always
  • root_path - The subdirectory in your repository that you wish to deploy. Leave blank to use the default specified in the project.
  • auto_deploy - Should auto deployments be enabled, either true or false
  • notification_email - Custom notification e-mail address, leave blank to use the user who started the deployment's address
  • branch - Branch to deploy from, leave blank to use the project default
  • environment - Production, Testing, Development etc. can be substituted into SSH commands.
  • server_group_identifier - The server group that this server belongs to
  • agent_id - The ID of the network agent that you wish to connect through (omit if you're connecting directly)

Protocol Types

Standard protocol types available to all accounts:

  • ssh - SSH/SFTP
  • ftp - FTP
  • ftps - FTPS (SSL/TLS)
  • s3 - Amazon S3
  • rackspace - Rackspace Cloud Files
  • s3_compatible - S3-Compatible Storage (Cloudflare R2, Wasabi, Backblaze B2, MinIO, Katapult)
  • shopify - Shopify
  • digital_ocean - DigitalOcean
  • shell - Shell Server

Beta protocol types (requires account with beta features enabled):

  • netlify - Netlify
  • heroku - Heroku
  • elastic_beanstalk - AWS ElasticBeanstalk

In addition to the above parameters, the following parameters are available depending on the protocol selected:

FTP

  • hostname (required)
  • username (required)
  • password (required)
  • port - default 21
  • passive - true or false
  • force_hidden_files - true or false
  • use_parallel_upload - true or false - upload files using multiple simultaneous connections for faster deployments (Beta - requires account with beta features enabled). Automatically falls back to standard uploads if the server does not support multiple connections.

FTPS

In addition the the FTP parameters the following parameters are available for FTPS servers.

  • implicit - true or false
  • ignore_certificate_errors - true or false

SSH/SFTP

  • hostname (required)
  • username (required)
  • password (required if not using SSH keys)
  • port - default 22
  • use_ssh_keys - true or false
  • global_key_pair_id - The ID of a global SSH key to use instead of the project's own key. Omit or leave blank to use the project key.
  • atomic - true or false (for setting up zero-downtime deployments, your server will need to support POSIX commands to take advantage of this feature)
  • atomic_strategy - copy_release or copy_cache - this must be set if atomic has been set to true
  • unlink_before_upload - true or false - removes files before uploading new versions
  • use_accelerated_transfer - true or false - enable Turbo Deployments (compressed TAR-based deployments). Requires tar, gzip, rsync, jq, and awk to be installed on your server. See the Turbo Deployments guide for more details.
  • use_parallel_upload - true or false - upload files using multiple simultaneous connections for faster deployments (Beta - requires account with beta features enabled). Automatically falls back to standard uploads if the server does not support multiple connections.

Amazon S3

  • bucket_name - (required)
  • access_key_id - (required)
  • secret_access_key - (required)

Rackspace Cloud

  • username - (required)
  • api_key - (required)
  • region - (required)
  • container_name - (required)

DigitalOcean

  • personal_access_token - (required)
  • droplet_id - (required)
  • droplet_name - (required)
  • username - SSH username for droplet access
  • unlink_before_upload - true or false - removes files before uploading new versions
  • use_accelerated_transfer - true or false - enable Turbo Deployments (compressed TAR-based deployments). Requires tar, gzip, rsync, jq, and awk to be installed on your server. See the Turbo Deployments guide for more details.

Shell Server

  • command - (required)
  • timeout - command timeout, in seconds (can be 5, 10, 30, 60, 90, 180 minutes)

S3-Compatible Storage

  • custom_endpoint - (required) - The full S3-compatible endpoint URL
  • bucket_name - (required)
  • access_key_id - (required)
  • secret_access_key - (required)

Shopify

  • store_url - (required) - The Shopify store URL or hostname
  • access_token - (required) - Shopify API access token
  • theme_name - The name of the theme to deploy to

Netlify (Beta)

Note: This protocol type requires an account with beta features enabled.

  • site_id - (required) - The Netlify site ID (36 character UUID)
  • access_token - (required) - Netlify personal access token

Heroku (Beta)

Note: This protocol type requires an account with beta features enabled.

  • app_name - (required) - The Heroku app name (3-30 characters, lowercase alphanumeric with hyphens)
  • api_key_heroku - (required) - Heroku API key

AWS ElasticBeanstalk (Beta)

Note: This protocol type requires an account with beta features enabled.

  • application_name - (required) - The ElasticBeanstalk application name (1-100 characters)
  • environment_name - (required) - The ElasticBeanstalk environment name (4-40 characters, alphanumeric with hyphens)
  • region - (required) - AWS region code (e.g., us-east-1, eu-west-1)
  • access_key_id - (required) - AWS access key ID (20 characters)
  • secret_access_key - (required) - AWS secret access key (40 characters)

Example cURL Requests

FTP Server Example

curl -H "Content-type: application/json" \
-H "Accept: application/json" \
--user user@example.com:your-api-key \
-X POST \
-d '{ \
  "server": { \
    "name": "Development", \
    "protocol_type": "ftp", \
    "hostname": "ftp.example.com", \
    "username": "deployhq", \
    "password": "test", \
    "port": 21, \
    "passive": true \
  } \
}' \
https://test.deployhq.com/projects/project/servers

SSH/SFTP Server Example

curl -H "Content-type: application/json" \
-H "Accept: application/json" \
--user user@example.com:your-api-key \
-X POST \
-d '{ \
  "server": { \
    "name": "Production", \
    "protocol_type": "ssh", \
    "hostname": "ssh.example.com", \
    "username": "deployhq", \
    "password": "secretpass", \
    "port": 22, \
    "server_path": "/var/www/html", \
    "atomic": true, \
    "atomic_strategy": "copy_release", \
    "use_accelerated_transfer": true \
  } \
}' \
https://test.deployhq.com/projects/project/servers

Amazon S3 Example

curl -H "Content-type: application/json" \
-H "Accept: application/json" \
--user user@example.com:your-api-key \
-X POST \
-d '{ \
  "server": { \
    "name": "S3 Bucket", \
    "protocol_type": "s3", \
    "bucket_name": "my-deployment-bucket", \
    "access_key_id": "AKIAIOSFODNN7EXAMPLE", \
    "secret_access_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY" \
  } \
}' \
https://test.deployhq.com/projects/project/servers

S3-Compatible Storage Example

curl -H "Content-type: application/json" \
-H "Accept: application/json" \
--user user@example.com:your-api-key \
-X POST \
-d '{ \
  "server": { \
    "name": "S3-Compatible Storage", \
    "protocol_type": "s3_compatible", \
    "custom_endpoint": "https://abc123def456.r2.cloudflarestorage.com", \
    "bucket_name": "my-bucket", \
    "access_key_id": "AKIAIOSFODNN7EXAMPLE", \
    "secret_access_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY" \
  } \
}' \
https://test.deployhq.com/projects/project/servers

Shopify Example

curl -H "Content-type: application/json" \
-H "Accept: application/json" \
--user user@example.com:your-api-key \
-X POST \
-d '{ \
  "server": { \
    "name": "Shopify Store", \
    "protocol_type": "shopify", \
    "store_url": "mystore.myshopify.com", \
    "access_token": "shpat_abc123def456", \
    "theme_name": "Dawn" \
  } \
}' \
https://test.deployhq.com/projects/project/servers

Netlify Example (Beta)

curl -H "Content-type: application/json" \
-H "Accept: application/json" \
--user user@example.com:your-api-key \
-X POST \
-d '{ \
  "server": { \
    "name": "Netlify Site", \
    "protocol_type": "netlify", \
    "site_id": "12345678-1234-1234-1234-123456789abc", \
    "access_token": "nfp_abc123def456ghi789jkl012" \
  } \
}' \
https://test.deployhq.com/projects/project/servers

Heroku Example (Beta)

curl -H "Content-type: application/json" \
-H "Accept: application/json" \
--user user@example.com:your-api-key \
-X POST \
-d '{ \
  "server": { \
    "name": "Heroku App", \
    "protocol_type": "heroku", \
    "app_name": "my-app-name", \
    "api_key_heroku": "abc123def456-ghi789-jkl012-mno345" \
  } \
}' \
https://test.deployhq.com/projects/project/servers

AWS ElasticBeanstalk Example (Beta)

curl -H "Content-type: application/json" \
-H "Accept: application/json" \
--user user@example.com:your-api-key \
-X POST \
-d '{ \
  "server": { \
    "name": "ElasticBeanstalk Environment", \
    "protocol_type": "elastic_beanstalk", \
    "application_name": "my-application", \
    "environment_name": "production", \
    "region": "us-east-1", \
    "access_key_id": "AKIAIOSFODNN7EXAMPLE", \
    "secret_access_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY" \
  } \
}' \
https://test.deployhq.com/projects/project/servers

Example Response

{
    "identifier": "19bdc2ea-1c96-e09f-f3bf-4473990841b7",
    "name": "Development",
    "protocol_type": "ssh",
    "server_path": "",
    "auto_deploy_url": "https://test.deployhq.com/deploy/project/to/development/fewfwef",
    "last_revision": null,
    "preferred_branch": "master", // preferred_branch will be the branch on this server if set, or the default branch for the repository if unset.
    "branch": null,
    "notify_email": null,
    "server_group_identifier": null,
    "hostname": "185.22.208.149",
    "username": "root",
    "port": 22,
    "host_key": "...."
}