How to use the Divio API

We provide a REST API using OpenAPI.

Divio API reference documentation

Create an API-only account

The API allows destructive operations to be carried out.

We strongly recommend that you do not use your own account/access token with the API, and especially not with code that is in development or not fully tested.

We recommend instead that you create a dedicated account for use with the API, and minimise the access it is granted. For example - where possible - rather than granting the account access to multiple organisations, give it access to just one, and do not give it admin access unless this is necessary.

Connecting to the API

The API’s end-point is https://api.divio.com/apps/v3/.

You will need a suitable client to connect to the API. This could be the curl command or another application.

Authentication

Each request made to the API must contain a valid Divio Control Panel access token. You can obtain an account’s access token from https://control.divio.com/account/desktop-app/access-token/.

Warning

The access token grants extensive access to you projects on our platform. Never share your access token with any other user. If you need to use it in an application or script, it is your responsibility to ensure that it is transmitted and stored safely.

The token must be included in a header authorization, in the form:

Token <include your token>

Basic requests

A example using curl:

curl https://api.divio.com/apps/v3/ -H 'authorization: Token yFagta25sbsus8d9JK9DrJCSKinqSWAoxU7NgN7IamtheCscry6jFfk3kingofthedivannTyYa10iqqD7EY5nvPR6yN47'

Here, the -H flag is used to pass the authorization header.

The principle using a dedicated REST API client, which will offer you more convenient ways to browse API, is much the same, whether it provides a graphical or command-line interface. It will behave in much the same way: you need to specify the URL, and provide the expected header.

The result of the command above will be a JSON response, for example:

{
    "applications": "https://api.divio.com/apps/v3/applications/",
    "environments": "https://api.divio.com/apps/v3/environments/",
    "domains": "https://api.divio.com/apps/v3/domains/",
    "patches": "https://api.divio.com/apps/v3/patches/",
    "repositories": "https://api.divio.com/apps/v3/repositories/",
    "serviceinstances": "https://api.divio.com/apps/v3/serviceinstances/",
    "deployments": "https://api.divio.com/apps/v3/deployments/",
    "builds": "https://api.divio.com/apps/v3/builds/",
    "regions": "https://api.divio.com/apps/v3/regions/"
}

Refer to the Divio API reference documentation for structured reference information on the API.