Hostname API

The Fly REST API lets you provision and manage hostnames, apps, secrets, and application releases. We follow the JSON API specification.

The balloon mascot is using her mind's eye


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



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> The structure looks like this:

curl -X GET


To create a new HTTPS hostname for your app, send a POST to /api/v1/apps/:name/hostnames 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.


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

curl -X GET /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