Skip to content

Update Machines API OpenAPI spec and models page. #2573

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
docs-syncer wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Update Machines API OpenAPI spec and models page. #2573

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 40 additions & 26 deletions api/machines/models.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -69,7 +69,7 @@ These are the data models used across the Machines API requests and responses, g
| --- | --- | --- | --- |
| `Version` | `integer` | No | DEPRECATED |
| `secrets` | `AppSecret[]` | No | |
| `version` | `integer` | No | |
| `version` | `integer` | No | The app's secrets version after this change. Pass it as `min_secrets_version` when creating or updating Machines so that they are guaranteed to see the change. |

## assignIPRequest

Expand Down Expand Up @@ -257,7 +257,7 @@ These are the data models used across the Machines API requests and responses, g
| --- | --- | --- | --- |
| `config` | `fly.MachineConfig` | No | An object defining the Machine configuration |
| `lease_ttl` | `integer` | No | |
| `min_secrets_version` | `integer` | No | |
| `min_secrets_version` | `integer` | No | The minimum version of the app's secrets the Machine must run with. Set it to the `version` returned by the endpoints that set or delete app secrets, so that the Machine is guaranteed to see those changes. This field belongs at the top level of the request body, not in `config`. If omitted, the app's current secrets version is looked up for you. |
| `name` | `string` | No | Unique name for this Machine. If omitted, one is generated for you |
| `region` | `string` | No | The target region. Omitting this param launches in the same region as your WireGuard peer connection (somewhere near you). |
| `skip_launch` | `boolean` | No | |
Expand Down Expand Up @@ -365,7 +365,7 @@ Optional parameters
| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `Version` | `integer` | No | DEPRECATED |
| `version` | `integer` | No | |
| `version` | `integer` | No | The app's secrets version after this change. Pass it as `min_secrets_version` when creating or updating Machines so that they are guaranteed to see the change. |

## DeleteSecretkeyResponse

Expand Down Expand Up @@ -625,29 +625,29 @@ A file that will be written to the Machine. One of RawValue or SecretName must b
| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `auto_destroy` | `boolean` | No | Optional boolean telling the Machine to destroy itself once it’s complete (default false) |
| `cache_drive` | `fly.MachineCacheDrive` | No | |
| `cache_drive` | `fly.MachineCacheDrive` | No | A cache drive attached to the Machine |
| `checks` | `map<string, fly.MachineCheck>` | No | An optional object that defines one or more named top-level checks. The key for each check is the check name. |
| `containers` | `fly.ContainerConfig[]` | No | Containers are a list of containers that will run in the machine. Currently restricted to only specific organizations. |
| `containers` | `fly.ContainerConfig[]` | No | Containers are a list of containers that will run in the machine, each from its own image. |
| `disable_machine_autostart` | `boolean` | No | Deprecated: use Service.Autostart instead |
| `dns` | `fly.DNSConfig` | No | |
| `dns` | `fly.DNSConfig` | No | DNS settings for the Machine |
| `env` | `map<string, string>` | No | An object filled with key/value pairs to be set as environment variables |
| `files` | `fly.File[]` | No | |
| `guest` | `fly.MachineGuest` | No | |
| `files` | `fly.File[]` | No | Files to write into the Machine, from either a raw value or an app secret |
| `guest` | `fly.MachineGuest` | No | The resources (CPUs, memory, etc.) allocated to the Machine |
| `image` | `string` | No | The docker image to run |
| `init` | `fly.MachineInit` | No | |
| `metadata` | `map<string, string>` | No | |
| `metrics` | `fly.MachineMetrics` | No | |
| `mounts` | `fly.MachineMount[]` | No | |
| `processes` | `fly.MachineProcess[]` | No | |
| `restart` | `fly.MachineRestart` | No | |
| `rootfs` | `fly.MachineRootfs` | No | |
| `schedule` | `string` | No | |
| `services` | `fly.MachineService[]` | No | |
| `init` | `fly.MachineInit` | No | Arguments for init, Fly.io's footprint inside the Machine, which controls how your own code is run |
| `metadata` | `map<string, string>` | No | Key/value pairs of Machine metadata. Fly.io uses metadata internally for routing, process groups, and clusters |
| `metrics` | `fly.MachineMetrics` | No | An optional metrics endpoint for Prometheus on Fly.io to scrape |
| `mounts` | `fly.MachineMount[]` | No | Persistent volumes to mount in the Machine. A Machine can mount at most one volume, which must be on the same host. The mounted volume cannot be changed by updating the Machine |
| `processes` | `fly.MachineProcess[]` | No | Multiple processes to run within this one Machine, all from the Machine's image. Unrelated to the process groups in fly.toml, which run on separate Machines. To run processes from different images, use containers instead |
| `restart` | `fly.MachineRestart` | No | Whether and how the Machine is restarted after its main process exits |
| `rootfs` | `fly.MachineRootfs` | No | The size of the Machine's root filesystem and whether it persists |
| `schedule` | `string` | No | Run the Machine at an interval: one of hourly, daily, weekly or monthly. The interval starts when the Machine is created |
| `services` | `fly.MachineService[]` | No | Network services that Fly Proxy routes traffic to |
| `size` | `string` | No | Deprecated: use Guest instead |
| `spot` | `fly.MachineSpot` | No | |
| `spot` | `fly.MachineSpot` | No | Spot pricing settings for the Machine |
| `standbys` | `string[]` | No | Standbys enable a machine to be a standby for another. In the event of a hardware failure, the standby machine will be started. |
| `statics` | `fly.Static[]` | No | |
| `stop_config` | `fly.StopConfig` | No | |
| `statics` | `fly.Static[]` | No | Static files to serve under a URL prefix. Fly Proxy routes matching requests to a file server inside the Machine, bypassing your application's own process; the Machine must be running. The files are read either from a path inside the Machine or from a Tigris bucket that belongs to the app; no bucket is created for you |
| `stop_config` | `fly.StopConfig` | No | How the Machine is shut down gracefully: the signal sent to it and how long to wait before a hard shutdown |

## fly.MachineGuest

Expand Down Expand Up @@ -824,10 +824,10 @@ A Secret needing to be set in the environment of the Machine. env_var is require

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `guest_path` | `string` | Yes | |
| `index_document` | `string` | No | |
| `tigris_bucket` | `string` | No | |
| `url_prefix` | `string` | Yes | |
| `guest_path` | `string` | Yes | The path inside the Machine, or inside tigris_bucket when set, where the files to serve are located |
| `index_document` | `string` | No | The document served for requests to the URL prefix or any of its subfolders. Only works with tigris_bucket |
| `tigris_bucket` | `string` | No | An existing Tigris bucket belonging to the app to read the files from, instead of the Machine's filesystem. The files are still served through the Machine |
| `url_prefix` | `string` | Yes | The URL prefix under which the files are served |

## fly.StopConfig

Expand Down Expand Up @@ -1219,6 +1219,12 @@ Enum: unknown, insufficient_capacity, volume_placement_capacity, name_taken
| --- | --- | --- | --- |
| `value` | `string` | No | |

## OkResponse

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `ok` | `boolean` | No | |

## OrganizationRef

| Property | Type | Required | Description |
Expand Down Expand Up @@ -1560,7 +1566,7 @@ Enum: 1, 2, 4, 8, 16, 31, 0
| `name` | `string` | No | |
| `updated_at` | `string` | No | |
| `value` | `string` | No | |
| `version` | `integer` | No | |
| `version` | `integer` | No | The app's secrets version after this change. Pass it as `min_secrets_version` when creating or updating Machines so that they are guaranteed to see the change. |

## SetSecretkeyRequest

Expand Down Expand Up @@ -1605,6 +1611,14 @@ Enum: 1, 2, 4, 8, 16, 31, 0
| --- | --- | --- | --- |
| `signature` | `integer[]` | No | |

## StartMachineResponse

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `migrated` | `boolean` | No | Whether the Machine was moved to another host to be started |
| `new_host` | `string` | No | The host the Machine was moved to, if it was migrated |
| `previous_state` | `string` | No | The state the Machine was in before it was started |

## StopRequest

| Property | Type | Required | Description |
Expand All @@ -1627,7 +1641,7 @@ Enum: 1, 2, 4, 8, 16, 31, 0
| `config` | `fly.MachineConfig` | No | An object defining the Machine configuration |
| `current_version` | `string` | No | CurrentVersion is an optional optimistic-concurrency guard: the Machine's `version`, as returned by create, get or a previous update. When set and it is no longer the Machine's current version, the update is rejected with 409 Conflict and nothing changes. Omit it to update unconditionally. |
| `lease_ttl` | `integer` | No | |
| `min_secrets_version` | `integer` | No | |
| `min_secrets_version` | `integer` | No | The minimum version of the app's secrets the Machine must run with. Set it to the `version` returned by the endpoints that set or delete app secrets, so that the Machine is guaranteed to see those changes. This field belongs at the top level of the request body, not in `config`. If omitted, the app's current secrets version is looked up for you. |
| `name` | `string` | No | Unique name for this Machine. If omitted, one is generated for you |
| `region` | `string` | No | The target region. Omitting this param launches in the same region as your WireGuard peer connection (somewhere near you). |
| `skip_launch` | `boolean` | No | |
Expand Down
10,495 changes: 10,494 additions & 1 deletion api/machines/openapi.json
View file
Open in desktop

@NullHypothesis NullHypothesis Oct 16, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

FYI, I removed the compact formatting, which will make it easier to eyeball the diff. I don't think our tooling cares.

Large diffs are not rendered by default.

Loading