Hostname API

Channeling an API magically

Introduction

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

We follow the JSON API specification.

API Endpoint

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

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

Each site is an umbrella that contains 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)

For example:

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

[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]" } } }' http://fly.io/api/v1/sites/:slug/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] : /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

Tips