Hostname API

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

The Fly.io balloon mascot is using her mind's eye

Authorization

All API calls require authentication with an [API_TOKEN]. Login to fly.io, 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 https://fly.io/api/v1/apps

Hostnames

List

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

curl -X GET https://fly.io/api/v1/apps/:name/hostnames

Create

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]" } } }' http://fly.io/api/v1/apps/:name/hostnames

An HTTPS Fly.io 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

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

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

Delete

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

Tips

The Fly.io balloon mascot wearing a bow tie and glasses