Create a new server via API

Last updated on 13th November 2024

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, either ftp, ftps, rackspace, s3 or ssh
  • 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)

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

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)

Example cURL Request

curl -H "Content-type: application/json" \
-H "Accept: application/json" \
--user adam@atechmedia.com:my-api-key \
-X POST \
-d { \
  "server" : { \
    "name": "Development", \
    "protocol_type" : "ftp", \
    "hostname": "localhost", \
    "username": "deployhq", \
    "password": "test" \
  } \
} \
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": "...."
}