Chapter 12


Find out more about DeployHQ's application programming and command line interfaces

DeployHQ API

DeployHQ has an extensive API that allows you to automate a number of processes in your account, ranging from creating a project and adding servers to triggering deployments.

You can find our full knowledge base containing all available methods in our Knowledge base.

Authenticating and Accessing the API

Users are provided with an API key which can be found in their Security page within the Settings menu. It's a 40 character string which must be used with your username in order to authenticate. All API requests should be sent with HTTP Basic authentication with your username (email address) & API key.

Requests should also send an Accept: application/json and Content-type: application/json header. All requests to the API should be in JSON and all responses received will be returned as JSON.

Requests should be made to http(s)://yourdomain.deployhq.com/

Handling Validation Errors

If there are any validation errors when creating an object via the API, the returned HTTP status will be 422 (Unprocessable Entity). The body of the request will contain an object which describes the error.

This object is keyed on the attribute which is the cause of the validation error. The value will refer to an array containing one or more errors on that attribute. In the case that the validation applies to the object as a whole, the error will be in the base key. For example:

    "base" : ["Could not access the server with the potentials provided"],
    "hostname" : ["must be present", "must be a valid domain"],
    "username" : ["must be present"]

DeployHQ CLI

As well as the web interface, DeployHQ also has a Ruby API library and command line tool for interacting with your projects.

You can find more information about the CLI client on Github, and installation and example usage instructions below.


You'll need Ruby installed on your system to be able to use the DeployHQ CLI. To get started, enter the following command in your terminal, in any directory, which will install the library globally.

gem install deployhq

Configuration (deployhq configure)

To configure the DeployHQ CLI in a project, navigate to your project in your terminal, then run deployhq configure to set up the connection to your project in DeployHQ, and follow the steps provided:

$ cd /path/to/project
$ deployhq configure
Account Domain (e.g. https://atech.deployhq.com): https://atech.deployhq.com
Username or e-mail address: adamw
API key (You can find this in Settings -> Security): my-api-key
Default project to use (please use permalink from web URL): my-project-permalink
File written to ./Deployfile

The CLI client will always look for the details of the current project in a file called Deployfile in the current directory. This file will contain your account URL, project permalink, username and API key, in JSON format.

It is recommended each member of your team has their own Deployfile, since the username and API key are user specific.

List servers (deployhq servers)

$ deployhq servers
Ungrouped Servers
              Name : Test
              Type : SSH
              Path : htdocs
            Branch : master
  Current Revision : baa7690059283c6e2e3d21fd0149f12b318175dd
          Hostname : localhost:22

Make a deployment (deployhq deploy)

$ deployhq deploy
1. Test (branch: master) (currently: baa7690059283c6e2e3d21fd0149f12b318175dd)
2. List Server Details
Please choose a server or group to deploy to:
Waiting for an available deployment slot...
Checking access to repository
Checking start and end revisions are valid
Checking connection to server Test
Updating repository from https://github.com/robertlyall/my-react-project.git
Getting information for start commit baa769
Getting information for end commit baa769
Checking out working copy of your repository at baa769
Deployment has finished successfully!