---
name: fly-machines-api
description: Call the Fly.io Machines API to create, start, stop, and destroy VMs programmatically.
license: Apache-2.0
---

# Fly.io Machines API

Machines are fast-booting VMs. The REST API creates and controls them directly,
without flyctl.

## Base URL and authentication

```
https://api.machines.dev/v1
```

Every request needs a Fly.io API token:

```
Authorization: Bearer <FLY_API_TOKEN>
```

Create a token with `fly tokens create org <org-slug>`, and scope it to the
narrowest org or app that will do the work.

## Machine lifecycle

Machines belong to an app, so create the app first, then machines within it.

```sh
curl -X POST "https://api.machines.dev/v1/apps/$APP/machines" \
  -H "Authorization: Bearer $FLY_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"config": {"image": "flyio/fastify-functions", "guest": {"cpu_kind": "shared", "cpus": 1, "memory_mb": 256}}}'
```

The same collection supports the rest of the lifecycle:

- `GET /apps/{app}/machines` — list
- `GET /apps/{app}/machines/{id}` — inspect one
- `POST /apps/{app}/machines/{id}/start` — start
- `POST /apps/{app}/machines/{id}/stop` — stop
- `DELETE /apps/{app}/machines/{id}` — destroy

## Specification

The OpenAPI document is the authoritative reference, and is machine-readable:

```
https://docs.machines.dev/openapi.json
```

Prose documentation: <https://docs.fly.io/machines/api>

## Choosing between Machines and Sprites

Machines are the primitive for running an application in production. Sprites
are a persistent development environment built on top of the same platform —
if an agent needs a place to work rather than a place to serve traffic, see
<https://fly.io/sprites>.