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](https://api.deployhq.com/docs) 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 snake_case identifier (e.g. `record_not_found`, `invalid_json`, `validation_failed`)
- `hint` - A human-readable suggestion for resolving the error

### Common error codes

| HTTP Status | `error_code` | Description |
|-------------|-------------|-------------|
| 400 | `invalid_json` | Request body is not valid JSON |
| 403 | `api_access_restricted` | Account plan does not include API access |
| 404 | `record_not_found` | Resource not found or not accessible |
| 404 | `invalid_api_method` | Endpoint does not exist |
| 422 | (validation errors) | Per-field validation errors |
| 500 | `internal_error` | Unexpected server error |
| 503 | `service_unavailable` | Temporary unavailability, check `Retry-After` header |

### Example: Not found

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

### Example: Invalid JSON

```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.

```json
{
    "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](https://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.

## Account-level resources

The DeployHQ API can also manage account-level resources shared across all your projects:

- [Global config files](/support/global-config-files) — file templates shared across projects
- [Global environment variables](/support/global-environment-variables) — secrets and configuration shared across projects