Create a new server via API

Last updated on 16th October 2025

This method allows you to create a new server.

URL

/projects/<project>/servers

Replace <projects> with the permalink 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
  • r2 - Cloudflare R2
  • 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

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
  • 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

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)

Shell Server

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

Cloudflare R2

  • account_id - (required)
  • 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" \
  } \
}' \
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

Cloudflare R2 Example

curl -H "Content-type: application/json" \
-H "Accept: application/json" \
--user user@example.com:your-api-key \
-X POST \
-d '{ \
  "server": { \
    "name": "R2 Bucket", \
    "protocol_type": "r2", \
    "account_id": "abc123def456", \
    "bucket_name": "my-r2-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": "...."
}