Last updated on 5th March 2026

Edit an existing server via API

This method allows you to edit a server.

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

URL

/projects/<project>/servers/<identifier>
  • Replace <project> with either the permalink or identifier 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 * 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
  • username
  • password
  • port
  • passive
  • force_hidden_files
  • 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 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
  • 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
  • atomic_strategy
  • unlink_before_upload
  • 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
  • access_key_id
  • secret_access_key

Rackspace Cloud

  • username
  • api_key
  • region
  • container_name

S3-Compatible Storage

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

Shopify

  • store_url
  • access_token
  • theme_name

DigitalOcean

  • personal_access_token
  • droplet_id
  • droplet_name
  • username
  • unlink_before_upload
  • 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
  • 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": "...."
}