# Fly.io

> Manage Fly apps, machine lifecycle, volumes and machine diagnostics.

App · 20 actions. Web page: https://docs.lodol.com/docs/integrations/fly-io

## Actions

### Create app

Create an app with the specified details in the request body.

**Inputs**

- Enable subdomains (`enable_subdomains`, true/false): Request a wildcard TLS certificate for *.svc. .fly.dev. Defaults to false. Certificate provisioning is asynchronous; this does not create services or configure their routing.
- Idempotency key (`idempotency_key`, text): When set, makes a retry of this exact request safe: a second create with the same key and the same name (or no name) returns the app the first request created, instead of erroring on a false name conflict or creating a duplicate. A second create with the same key but a *different* name is rejected outright; it won't silently hand back the first app.
- Name (`name`, text, required): Globally unique name for the app. Required.
- Network (`network`, text): Name of the organization's private network to attach the app to. Creates the network if it does not exist. Omit, use an empty string, or use "default" to select the organization's default network.
- Org slug (`org_slug`, text, required): Slug of the organization that will own the app, or "personal" for your personal organization. Required.

**Outputs**

- `data` (object): Returned value.

**Example output**

```json
{
  "data": {
    "created_at": 1,
    "id": "example"
  }
}
```

### Destroy app

Delete an app by its name.

**Inputs**

- App name (`app_name`, text, required): Fly App Name

**Outputs**

- `data` (object): Returned value.

**Example output**

```json
{
  "data": {}
}
```

### Get app

Retrieve details about a specific app by its name.

**Inputs**

- App name (`app_name`, text, required): Fly App Name

**Outputs**

- `data` (object): Returned value.

**Example output**

```json
{
  "data": {
    "id": "example",
    "internal_numeric_id": 1,
    "machine_count": 1,
    "name": "example",
    "network": "example",
    "network_cidr": "example",
    "organization": {
      "internal_numeric_id": 1,
      "name": "example",
      "slug": "example"
    },
    "status": "example",
    "volume_count": 1
  }
}
```

### Get certificate details

Get certificate details

**Inputs**

- App name (`app_name`, text, required): Fly App Name
- Hostname (`hostname`, text, required): Certificate Hostname

**Outputs**

- `data` (object): Returned value.

**Example output**

```json
{
  "data": {
    "acme_requested": false,
    "certificates": [],
    "configured": false,
    "dns_provider": "example",
    "dns_requirements": {
      "a": [],
      "aaaa": [],
      "acme_challenge": {
        "name": "example",
        "target": "example"
      },
      "cname": "example",
      "ownership": {
        "app_value": "example",
        "name": "example",
        "org_value": "example"
      }
    },
    "hostname": "example",
    "rate_limited_until": "example",
    "status": "example",
    "validation": {
      "alpn_configured": false,
      "dns_configured": false,
      "http_configured": false,
      "ownership_txt_configured": false
    },
    "validation_errors": []
  }
}
```

### Get lease

Retrieve the current lease of a specific Machine within an app. Machine leases can be used to obtain an exclusive lock on modifying a Machine.

**Inputs**

- App name (`app_name`, text, required): Fly App Name
- Machine ID (`machine_id`, text, required): Machine ID

**Outputs**

- `data` (object): Returned value.

**Example output**

```json
{
  "data": {
    "description": "example",
    "expires_at": 1,
    "nonce": "example",
    "owner": "example",
    "version": "example"
  }
}
```

### Get machine

Get details of a specific Machine within an app by the Machine ID.

**Inputs**

- App name (`app_name`, text, required): Fly App Name
- Machine ID (`machine_id`, text, required): Machine ID
- Version (`version`, text): 26-character Machine version ID; returns that version of the Machine instead of the current one
- Include leases (`include_leases`, true/false): Include machine lease

**Outputs**

- `data` (object): Returned value.

**Example output**

```json
{
  "data": {
    "checks": [],
    "config": {
      "auto_destroy": false,
      "cache_drive": {
        "size_mb": 1
      },
      "checks": {},
      "containers": [],
      "disable_machine_autostart": false,
      "dns": {
        "dns_forward_rules": [],
        "hostname": "example",
        "hostname_fqdn": "example",
        "nameservers": [],
        "options": [],
        "searches": [],
        "skip_registration": false
      },
      "env": {},
      "files": [],
      "guest": {
        "cpu_kind": "example",
        "cpus": 1,
        "gpu_kind": "example",
        "gpus": 1,
        "host_dedication_id": "example",
        "kernel_args": [],
        "max_memory_mb": 1,
        "memory_mb": 1,
        "persist_rootfs": "never",
        "required_host_features": []
      },
      "image": "example",
      "init": {
        "cmd": [],
        "entrypoint": [],
        "exec": [],
        "kernel_args": [],
        "swap_size_mb": 1,
        "tty": false
      },
      "metadata": {},
      "metrics": {
        "https": false,
        "path": "example",
        "port": 1
      },
      "mounts": [],
      "processes": [],
      "restart": {
        "max_retries": 1,
        "policy": "no"
      },
      "rootfs": {
        "persist": "never",
        "size_gb": 1
      },
      "schedule": "example",
      "services": [],
      "size": "example",
      "spot": {
        "max_price_fraction": 1
      },
      "standbys": [],
      "statics": [],
      "stop_config": {
        "signal": "SIGHUP",
        "timeout": "example"
      }
    },
    "cordoned": false,
    "created_at": "example",
    "events": [],
    "host_features": [],
    "host_status": "ok",
    "id": "example",
    "image_ref": {
      "digest": "example",
      "labels": {},
      "registry": "example",
      "repository": "example",
      "tag": "example"
    },
    "incomplete_config": {
      "auto_destroy": false,
      "cache_drive": {
        "size_mb": 1
      },
      "checks": {},
      "containers": [],
      "disable_machine_autostart": false,
      "dns": {
        "dns_forward_rules": [],
        "hostname": "example",
        "hostname_fqdn": "example",
        "nameservers": [],
        "options": [],
        "searches": [],
        "skip_registration": false
      },
      "env": {},
      "files": [],
      "guest": {
        "cpu_kind": "example",
        "cpus": 1,
        "gpu_kind": "example",
        "gpus": 1,
        "host_dedication_id": "example",
        "kernel_args": [],
        "max_memory_mb": 1,
        "memory_mb": 1,
        "persist_rootfs": "never",
        "required_host_features": []
      },
      "image": "example",
      "init": {
        "cmd": [],
        "entrypoint": [],
        "exec": [],
        "kernel_args": [],
        "swap_size_mb": 1,
        "tty": false
      },
      "metadata": {},
      "metrics": {
        "https": false,
        "path": "example",
        "port": 1
      },
      "mounts": [],
      "processes": [],
      "restart": {
        "max_retries": 1,
        "policy": "no"
      },
      "rootfs": {
        "persist": "never",
        "size_gb": 1
      },
      "schedule": "example",
      "services": [],
      "size": "example",
      "spot": {
        "max_price_fraction": 1
      },
      "standbys": [],
      "statics": [],
      "stop_config": {
        "signal": "SIGHUP",
        "timeout": "example"
      }
    },
    "instance_id": "example",
    "lease": {
      "description": "example",
      "expires_at": 1,
      "owner": "example"
    },
    "name": "example",
    "nonce": "example",
    "private_ip": "example",
    "region": "example",
    "state": "example",
    "updated_at": "example",
    "version": "example"
  }
}
```

### Get metadata

Retrieve metadata for a specific Machine within an app.

**Inputs**

- App name (`app_name`, text, required): Fly App Name
- Machine ID (`machine_id`, text, required): Machine ID

**Outputs**

- `data` (object): Returned value.

**Example output**

```json
{
  "data": {}
}
```

### Get volume

Retrieve details about a specific volume by its ID within an app.

**Inputs**

- App name (`app_name`, text, required): Fly App Name
- Volume ID (`volume_id`, text, required): Volume ID

**Outputs**

- `data` (object): Returned value.

**Example output**

```json
{
  "data": {
    "attached_alloc_id": "example",
    "attached_machine_id": "example",
    "auto_backup_enabled": false,
    "block_size": 1,
    "blocks": 1,
    "blocks_avail": 1,
    "blocks_free": 1,
    "bytes_total": 1,
    "bytes_used": 1,
    "created_at": "example",
    "encrypted": false,
    "fstype": "example",
    "host_features": [],
    "host_status": "ok",
    "id": "example",
    "name": "example",
    "region": "example",
    "required_host_features": [],
    "size_gb": 1,
    "snapshot_retention": 1,
    "state": "example",
    "type": "local",
    "zone": "example"
  }
}
```

### List apps

List all apps with the ability to filter by organization slug.

**Inputs**

- Org slug (`org_slug`, text, required): The org slug, or 'personal', to filter apps
- App role (`app_role`, text): Filter apps by role
- Limit (`limit`, number): The number of apps to fetch (must be between 1 and 5000). Providing a limit enables pagination. Without it, all apps are returned in one response.
- Cursor (`cursor`, text): Value of next_cursor from the previous page. Requires limit. Later pages only include apps that existed when the first page was requested. Apps created in the seconds before the first page was requested may be missing. Cursors expire 30 minutes after the first page was requested.

**Outputs**

- `data` (object): Returned value.

**Example output**

```json
{
  "data": {
    "apps": [],
    "next_cursor": "example",
    "total_apps": 1
  }
}
```

### List certificates for app

List certificates for app

**Inputs**

- App name (`app_name`, text, required): Fly App Name
- Filter (`filter`, text): Hostname filter (substring match)
- Cursor (`cursor`, text): Pagination cursor from previous response
- Limit (`limit`, number): Number of results per page (default 25, max 500)

**Outputs**

- `data` (object): Returned value.

**Example output**

```json
{
  "data": {
    "certificates": [],
    "next_cursor": "example",
    "total_count": 1
  }
}
```

### List events

List all events associated with a specific Machine within an app.

**Inputs**

- App name (`app_name`, text, required): Fly App Name
- Machine ID (`machine_id`, text, required): Machine ID
- Limit (`limit`, number): The number of events to fetch (max of 50). If omitted, this is set to 20 by default.

**Outputs**

- `data` (list): Returned value.

**Example output**

```json
{
  "data": []
}
```

### List machines

List all Machines associated with a specific app, with optional filters for including deleted Machines and filtering by region.

**Inputs**

- App name (`app_name`, text, required): Fly App Name
- Include deleted (`include_deleted`, true/false): Include deleted machines
- Include leases (`include_leases`, true/false): Include machine leases
- Region (`region`, text): Region filter
- State (`state`, text): comma separated list of states to filter (created, started, stopped, suspended)
- Summary (`summary`, true/false): Only return summary info about machines (omit config, checks, events, host_status, nonce, etc.)

**Outputs**

- `data` (list): Returned value.

**Example output**

```json
{
  "data": []
}
```

### List processes

List all processes running on a specific Machine within an app, with optional sorting parameters.

**Inputs**

- App name (`app_name`, text, required): Fly App Name
- Machine ID (`machine_id`, text, required): Machine ID
- Sort by (`sort_by`, text): Sort by
- Order (`order`, text): Order

**Outputs**

- `data` (list): Returned value.

**Example output**

```json
{
  "data": []
}
```

### List snapshots

List all snapshots for a specific volume within an app.

**Inputs**

- App name (`app_name`, text, required): Fly App Name
- Volume ID (`volume_id`, text, required): Volume ID

**Outputs**

- `data` (list): Returned value.

**Example output**

```json
{
  "data": []
}
```

### List versions

List all versions of the configuration for a specific Machine within an app.

**Inputs**

- App name (`app_name`, text, required): Fly App Name
- Machine ID (`machine_id`, text, required): Machine ID

**Outputs**

- `data` (list): Returned value.

**Example output**

```json
{
  "data": []
}
```

### List volumes

List all volumes associated with a specific app.

**Inputs**

- App name (`app_name`, text, required): Fly App Name
- Summary (`summary`, true/false): Only return summary info about volumes (omit blocks, block size, etc)

**Outputs**

- `data` (list): Returned value.

**Example output**

```json
{
  "data": []
}
```

### Restart machine

Restart a specific Machine within an app, with an optional timeout parameter.

**Inputs**

- App name (`app_name`, text, required): Fly App Name
- Machine ID (`machine_id`, text, required): Machine ID
- Timeout (`timeout`, text): Restart timeout as a Go duration string or number of seconds
- Signal (`signal`, text): Unix signal name. One of: `SIGHUP`, `SIGINT`, `SIGQUIT`, `SIGKILL`, `SIGUSR1`, `SIGUSR2`, `SIGTERM`.

**Outputs**

- `data` (object): Returned value.

**Example output**

```json
{
  "data": {
    "ok": false
  }
}
```

### Start machine

Start a specific Machine within an app.

**Inputs**

- App name (`app_name`, text, required): Fly App Name
- Machine ID (`machine_id`, text, required): Machine ID

**Outputs**

- `data` (object): Returned value.

**Example output**

```json
{
  "data": {
    "migrated": false,
    "new_host": "example",
    "previous_state": "example"
  }
}
```

### Stop machine

Stop a specific Machine within an app, with an optional request body to specify signal and timeout.

**Inputs**

- App name (`app_name`, text, required): Fly App Name
- Machine ID (`machine_id`, text, required): Machine ID
- Signal (`signal`, text): Returned value. One of: `SIGHUP`, `SIGINT`, `SIGQUIT`, `SIGKILL`, `SIGUSR1`, `SIGUSR2`, `SIGTERM`.
- Timeout (`timeout`, text): Returned value.

**Outputs**

- `data` (object): Returned value.

**Example output**

```json
{
  "data": {
    "ok": false
  }
}
```

### Suspend machine

Suspend a specific Machine within an app. The next start operation will attempt (but is not guaranteed) to resume the Machine from a snapshot taken at suspension time, rather than performing a cold boot.

**Inputs**

- App name (`app_name`, text, required): Fly App Name
- Machine ID (`machine_id`, text, required): Machine ID

**Outputs**

- `data` (object): Returned value.

**Example output**

```json
{
  "data": {
    "ok": false
  }
}
```
