Hostname API

The balloon mascot is using her mind's eye


The Fly REST API lets you provision and manage hostnames, apps, secrets, and application releases.

We follow the JSON API specification.

API Endpoint


All API calls require authentication with an [API_TOKEN]. Login to, click Your Account, then Personal Access Tokens on the sidebar. Once generated, you can authenticate by passing the Authorization: Bearer header along with your [API_TOKEN].

Here's an example:

curl -H "Authorization: Bearer [API_TOKEN]" -X GET


[GET] : /api/v1/apps/:name/hostnames

Each app can have many hostnames. You can check-out the hostnames that belong to an app by sending a GET request to /api/v1/apps/:name/hostnames, where :name is name of an existing app (like <name>

For example:

curl -X GET

[POST] : /api/v1/apps/:name/hostnames

To create a new HTTPS hostname for your app, send a POST with an attached JSON body:

  "data": {
    "attributes": {
      "hostname": "[NEW_HOSTNAME]"

A properly structured POST will look like this, plus authorization:

curl -H "Content-Type: application/json" -X POST -d '{"data": { "attributes": { "hostname": "[NEW_HOSTNAME]" } } }'

An HTTPS preview_hostname will be created with a fresh Let's Encrypt SSL certificate for each hostname that's been created. The final step is to setup a DNS record to link the preview_hostname with your domain of choice.

[GET] : /api/v1/apps/:name/hostnames/:hostname

To view a specific hostname, send a GET request to its resource URL.

curl -X GET /api/v1/apps/:name/hostnames/:hostname

[DELETE] : /api/v1/apps/:name/hostnames/:hostname

Send a DELETE to a hostname resource URL to remove it and all its associated certificates from our system.

curl -X DELETE /api/v1/apps/:name/hostnames/:hostname
The balloon mascot wearing a bow tie and glasses