The DeployHQ API

DeployHQ offers an API to allow you to view your deployments and create new ones. In addition to the API, there's also a ruby gem available to make integrating with DeployHQ even easier.

Access & Authentication

Users are provided with an API key which can be found from the “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) and API key.

All requests should also send the following headers:

• Accept: application/json
• Content-Type: application/json

These requests should be in JSON and all responses received will be returned as JSON.

Requests should be made to https://<account>.deployhq.com/ replacing <account> with the name of your account.

Handling 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 OpenAPI

DeployHQ offers an API to allow you to view your deployments and create new ones. In addition to the API, there's also a Ruby gem available to make integrating with DeployHQ even easier.

An OpenAPI documentation, similar to Swagger, is also available at api.deployhq.com. This provides more detailed information where all schemas can be viewed and tested against the live API.

About OpenAPI

OpenAPI Specification (formerly known as Swagger Specification) is a standard, language-agnostic interface to RESTful3 APIs. It allows both humans and computers to discover and understand the capabilities of a service without requiring access to the source code or additional4 documentation.

An OpenAPI document, written in YAML or JSON, describes the entire API, including:

• Available endpoints and the operations on each endpoint (e.g., GET /users, POST /users).
• Input and output parameters for each operation.
• Authentication methods.
• Contact information, license, and terms of use.

By providing a detailed, machine-readable definition of the API, OpenAPI offers several benefits:

• Interactive Documentation: Tools can render the OpenAPI definition as interactive API documentation, allowing users to test API calls directly in the browser.
• Code Generation: It enables the automatic generation of client libraries in various programming languages and server stubs, which can significantly speed up development.
• Standardization and Consistency: It ensures that the API is well-defined and consistent, which improves the developer experience and reduces the chances of integration errors.