Overview

Introduction

The DeployBot HTTP API allows users to access their account data and trigger deployments. It is the best way to integrate your deployments with all of the other tools you use.

Our API is built on REST principles. Authenticated users can interact with any of our URIs by using the specified HTTP request method.

Endpoint

The API is hosted on your account subdomain. Please use the following base endpoint for all of your API requests:

https://yoursubdomain.deploybot.com/api/v1

Please note the https protocol used in the URL. All API users are required to use secure HTTP connections. All plain HTTP requests will be forwarded to the corresponding secure endpoints.

Authentication

The API authenticates users via secret API tokens. Account owners and admins can generate new API tokens in their account settings. The generated tokens should be securely stored and never shared publicly.

An API token can be passed as an HTTP header or as a request parameter.

As a header. Add X-Api-Token header to your request:

curl -H 'Accept: application/json' -H 'X-Api-Token: your-api-token' https://yoursubdomain.deploybot.com/api/v1/users

As a request parameter. Add token parameter to the URL:

curl -H 'Accept: application/json' https://yoursubdomain.deploybot.com/api/v1/users?token=your-api-token

Making requests

The API accepts standard HTTP requests. You can pass values to the API via the URL query string or the request body, when required by an endpoint. The request body, if present, is always assumed to be a JSON document. The Content-Type and Acceptheaders are ignored.

Only GET requests are allowed when using a read-only API key. The API will respond with status 403 Forbidden when trying to use a read-only key for a POST or PUT request.

Handling responses

The API relies on HTTP status codes to communicate the status of your request.

• 200 — Success
  Everything went smooth.
• 400 — Bad Request
  Malformed JSON payload.
• 401 — Authentication Required
  Missing or invalid API token.
• 403 — Forbidden
  Attempting to perform a restricted action.
• 422 — Unprocessable Entity
  Something is not right with the request data.
• 500 — Internal Server Error
  An error on our side. Please contact support if the error persists.

The server always encloses a JSON document in the response body. The document format for all successful requests is specific to an endpoint. The error format is described in the Dealing with errors section.

Dealing with errors

Whenever an error occurs, the server responds with a non-successful HTTP status code and a JSON document is enclosed in the response body. The document has the following format:

{"message" : "Error description."}

The message field of the returned object contains a human-readable description of the error.

Paging results

All "list" endpoints support pagination of returned results. Pagination is controlled via limit and after parameters in the URL query string. The after parameter is the ID of the last entry returned by the current request. You don’t need to provide afterparameter to get the first page. The optional limit parameter specifies how many entries are returned per request ranging from zero to an endpoint-specific maximum value.

A typical response object of a paginated resource contains two top-level fields: meta and entries. The meta object encloses information about the entries matching your query. The entries array contains a number of requested objects (up to the default or provided value of limit).

Response format