Edit an existing server via API

Last updated on 16th October 2025

This method allows you to edit a server.

URL

/projects/<project>/servers/<identifier>
  • Replace <project> with the permalink of the project.
  • Replace <identifier> with the identifier of the server.

HTTP Method

PUT

Supported Parameters

  • name - Friendly name for your server
  • protocol_type - Connection protocol (this field is required on all PUT requests so that DeployHQ can execute its test process correctly)
  • 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, or send nil 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
  • username
  • password
  • port
  • passive
  • force_hidden_files

FTPS

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

  • implicit
  • ignore_certificate_errors

SSH/SFTP

  • hostname
  • username
  • password
  • port
  • use_ssh_keys
  • atomic
  • atomic_strategy
  • unlink_before_upload

Amazon S3

  • bucket_name
  • access_key_id
  • secret_access_key

Rackspace Cloud

  • username
  • api_key
  • region
  • container_name

Cloudflare R2

  • account_id
  • bucket_name
  • access_key_id
  • secret_access_key

Shopify

  • store_url
  • access_token
  • theme_name

DigitalOcean

  • personal_access_token
  • droplet_id
  • droplet_name
  • username

Shell Server

  • command
  • timeout

Netlify (Beta)

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

  • site_id
  • access_token

Heroku (Beta)

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

  • app_name
  • api_key_heroku

AWS ElasticBeanstalk (Beta)

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

  • application_name
  • environment_name
  • region
  • access_key_id
  • secret_access_key

Example Payload

curl -H "Content-type: application/json" \
-H "Accept: application/json" \
--user user@example.com:your-api-key \
-X PUT \
-d '{ \
  "server": { \
    "name": "Development", \
    "protocol_type": "ftp", \
    "hostname": "ftp.example.com", \
    "username": "deployhq", \
    "password": "test" \
  } \
}' \
https://test.deployhq.com/projects/project/servers/19bdc2ea-1c96-e09f-f3bf-4473990841b7

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",
    "notify_email": null,
    "server_group_identifier": null,
    "hostname": "185.22.208.149",
    "username": "root",
    "port": 22,
    "host_key": "...."
}