The DeployHQ API

DeployHQ offers a comprehensive REST 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.

Quick Start: Explore our interactive OpenAPI documentation to test endpoints and see examples before integrating.

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

Most API error responses include machine-readable error_code and hint fields to help agents and scripts handle errors programmatically. Validation errors (422) are returned as field-keyed hashes and may not include these fields.

Error fields

• error_code - A machine-readable snakecase identifier (e.g. `recordnotfound,invalidjson,validation_failed`)
• hint - A human-readable suggestion for resolving the error

Common error codes

Example: Not found

{
    "status": "not_found",
    "error_code": "record_not_found",
    "hint": "Check the identifier is correct and you have access to this resource"
}

Example: Invalid JSON

{
    "error": "There was a problem in the JSON you submitted: ...",
    "error_code": "invalid_json",
    "hint": "Ensure request body is valid JSON with correct Content-Type: application/json header"
}

Example: Validation errors (422)

Validation errors are keyed on the attribute which is the cause of the error. The value is an array containing one or more errors on that attribute. If the validation applies to the object as a whole, the error will be in the base key.

{
    "base": ["Could not access the server with the details 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 RESTful APIs. It allows both humans and computers to discover and understand the capabilities of a service without requiring access to the source code or additional 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.