From fc299c96e9d3e888fef6b9c29005cf912d568b54 Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
 <41898282+github-actions[bot]@users.noreply.github.com>
Date: Fri, 23 Oct 2026 21:34:17 +0000
Subject: [PATCH] Update Machines API OpenAPI spec and models page

---
 api/machines/models.mdx   |  8 ++++----
 api/machines/openapi.json | 12 ++++++++----
 2 files changed, 12 insertions(+), 8 deletions(-)

diff --git a/api/machines/models.mdx b/api/machines/models.mdx
index bc7aed5dc9..202717b2ae 100644
--- a/api/machines/models.mdx
+++ b/api/machines/models.mdx
@@ -223,11 +223,11 @@ These are the data models used across the Machines API requests and responses, g
 
 | Property | Type | Required | Description |
 | --- | --- | --- | --- |
-| `enable_subdomains` | `boolean` | No |  |
+| `enable_subdomains` | `boolean` | No | Request a wildcard TLS certificate for *.svc.<app-name>.fly.dev. Defaults to false. Certificate provisioning is asynchronous; this does not create services or configure their routing. |
 | `idempotency_key` | `string` | No | 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` | `string` | No |  |
-| `network` | `string` | No |  |
-| `org_slug` | `string` | No |  |
+| `name` | `string` | No | Globally unique name for the app. Required. |
+| `network` | `string` | No | 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` | `string` | No | Slug of the organization that will own the app, or "personal" for your personal organization. Required. |
 
 ## CreateAppResponse
 
diff --git a/api/machines/openapi.json b/api/machines/openapi.json
index c1e566f36a..610278190d 100644
--- a/api/machines/openapi.json
+++ b/api/machines/openapi.json
@@ -6509,20 +6509,24 @@
         "type": "object",
         "properties": {
           "enable_subdomains": {
-            "type": "boolean"
+            "type": "boolean",
+            "description": "Request a wildcard TLS certificate for *.svc.<app-name>.fly.dev. Defaults to false. Certificate provisioning is asynchronous; this does not create services or configure their routing."
           },
           "idempotency_key": {
             "type": "string",
             "description": "When set, makes a retry of this exact request safe: a\nsecond create with the same key and the same name (or no name) returns\nthe app the first request created, instead of erroring on a false name\nconflict or creating a duplicate. A second create with the same key\nbut a *different* name is rejected outright; it won't silently\nhand back the first app."
           },
           "name": {
-            "type": "string"
+            "type": "string",
+            "description": "Globally unique name for the app. Required."
           },
           "network": {
-            "type": "string"
+            "type": "string",
+            "description": "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": {
-            "type": "string"
+            "type": "string",
+            "description": "Slug of the organization that will own the app, or \"personal\" for your personal organization. Required."
           }
         }
       },