Working with the Machines API

The Fly Machines API provides resources to create, destroy, and manage Fly Apps, Fly Machines, and Fly Volumes. Refer to the following reference docs for the usage of each:

Apps resource - Every Fly Machine belongs to a Fly App.

Machines resource - Fly Machines are our fast-launching VMs.

Tokens resource - Support for OpenID Connect tokens.

Volumes resource - Fly Volumes are persistent storage for Machines.

Connecting to the API

API addresses

There are two base URLs available to connect to the Machines API service.

Internal base URL: http://_api.internal:4280

Public base URL: https://api.machines.dev

From within your Fly.io private WireGuard network, you can connect to the API directly using the internal endpoint. From outside the Fly.io WireGuard mesh, use the public endpoint; this proxies your request to the API.

Authentication

All requests must include an API token in the HTTP headers as follows:

Authorization: Bearer <fly_api_token>

Replace <fly_api_token> with a Fly.io authentication token.

Environment setup

The examples in the Machines API reference docs assume that you have two environment variables set: FLY_API_TOKEN, the authorization token to use with the API call; and FLY_API_HOSTNAME, the API base URL.

For local development, you might set them as follows, assuming you have flyctl installed and have authenticated to Fly.io:

$ export FLY_API_HOSTNAME="https://api.machines.dev" # set to http://_api.internal:4280 when using WireGuard
$ export FLY_API_TOKEN=$(fly tokens deploy)

The fly tokens deploy command creates a token capable of managing the application in your current directory. See fly tokens create --help for information on other types of tokens you can generate.

To set an access token as an environment variable on Fly Machines, use a secret; for example:

fly secrets set FLY_API_TOKEN="$(fly tokens deploy)"

Response Codes

The Machines API uses conventional HTTP status codes to provide more information about the response.

Typically, 2xx HTTP status codes denote successful operations, 4xx codes imply failures related to the user, and 5xx codes suggest problems with the infrastructure.

Rate Limits

Machines API rate limits apply per-action, per-machine. The limit is 1 request, per second, per action (i.e. Create Machine, Start Machine etc.) — with a short-term burst limit up to 3 req/s, per action.

This applies to all actions except Get Machine which is 5 req/s, with a short-term burst limit up to 10 req/s.