{
 "openapi": "3.1.0",
 "info": {
  "title": "Gyro Public API",
  "version": "2.30.0",
  "summary": "Manage Gyro cloud servers, SSH keys and billing programmatically.",
  "x-summary-tr": "Gyro bulut sunucularınızı, SSH anahtarlarınızı ve faturalarınızı programla yönetin.",
  "contact": {
   "name": "Gyro Hosting",
   "url": "https://www.gyrohosting.com"
  },
  "license": {
   "name": "Proprietary",
   "identifier": "LicenseRef-Gyro-API-Terms"
  }
 },
 "servers": [
  {
   "url": "https://www.gyrohosting.com/api/v1/client",
   "description": "Production"
  }
 ],
 "paths": {
  "/cloud/servers/{id}/actions/{action}": {
   "post": {
    "tags": [
     "Server actions"
    ],
    "operationId": "serverAction",
    "summary": "Run a server action",
    "x-summary-tr": "Sunucu işlemi çalıştır",
    "description": "Heavy actions (rebuild, reset, rescue, snapshot restore, password reset) are limited per server per day.\nA one-time `root_password` is returned only when the request has **no** `Idempotency-Key`\n(idempotent answers are stored for replay, secrets never are; you then get `root_password_withheld: true`).\n\n**Region tr-ist-1**: poweron, shutdown, reboot, poweroff (same as shutdown), rebuild and reset_password are available; reset, enable_rescue and disable_rescue answer 422 `action_not_supported`. rebuild accepts the images of the server's own product (GET /cloud/images?region=tr-ist-1); the SSH keys given at creation are installed again once the rebuilt server is ready (follow `ssh_keys.state`). Prepaid servers: DELETE always cancels at once (no cancellation request).\n\n**2.14.0 (Gyro Compute, tr-ist-1)**: `reset` (hard reset) is available too; `rebuild` accepts `user_data` and installs the server's SSH keys again; `poweroff` is a hard power off (shutdown = graceful). rescue actions answer 422 `action_not_supported`.\n\n**2.19.1 (rebuild + app)**: `rebuild` accepts `app` (+ optional `app_domain`) on cloud servers: the disk is wiped, the new system is installed and the app is set up on it (progress in GET /cloud/servers/{id}/app, `/app/log`; login details once in the app status). A rebuild **without** `app` closes the server's previous app record (its automatic address is removed). What a rebuild keeps: IP addresses (incl. additional IPv4), server name, plan, SSH keys, firewall rules; tr-ist-1 deletes additional disks and snapshots, EU/US/SG keeps volumes, snapshots and backups. Errors: `app_with_user_data`, `invalid_app`, `invalid_app_domain`, `app_not_supported` (legacy VDS), `tool_action_failed` with the reason (app not available for the image, hourly limit).\n\n**rebuild erases data** (needs `\"confirm\": true`): the disk is re-created from the image; on tr-ist-1 additional disks and snapshots are deleted too, IP addresses, SSH keys of the order and the plan stay. A plan change (`/cloud/services/{id}/resize`) never erases data.",
    "x-description-tr": "Ağır işlemler (yeniden kurulum, reset, kurtarma, snapshot'tan dönüş, parola sıfırlama) sunucu başına günlük sınırlıdır.\nTek seferlik `root_password` yalnız istekte `Idempotency-Key` **yoksa** döner (tekrar için saklanan yanıtlara sır yazılmaz;\nbu durumda `root_password_withheld: true` görürsünüz).\n\n**tr-ist-1 bölgesi**: poweron, shutdown, reboot, poweroff (shutdown ile aynı), rebuild ve reset_password var; reset, enable_rescue ve disable_rescue 422 `action_not_supported` döner. rebuild sunucunun kendi ürününün imajlarını kabul eder.\n\n**2.14.0 (Gyro Compute, tr-ist-1)**: `reset` (sert yeniden başlatma) da var; `rebuild` `user_data` kabul eder ve sunucunun SSH anahtarlarını yeniden kurar; `poweroff` sert kapatmadır (shutdown = düzgün kapatma).\n\n**2.19.1 (yeniden kurulum + uygulama)**: bulut sunucularda `rebuild` `app` (+ isteğe bağlı `app_domain`) alır: disk silinir, yeni sistem kurulur ve uygulama üstüne kurulur (ilerleme GET /cloud/servers/{id}/app ve `/app/log`; giriş bilgileri uygulama durumunda bir kez). `app` **olmadan** yeniden kurulum sunucunun önceki uygulama kaydını kapatır (otomatik adresi silinir). Korunanlar: IP adresleri (ek IPv4 dahil), sunucu adı, paket, SSH anahtarları, güvenlik duvarı kuralları; tr-ist-1'de ek diskler ve snapshot'lar silinir, AB/ABD/SG'de volume, snapshot ve yedekler kalır.\n\n**rebuild veriyi siler** (`\"confirm\": true` ister): disk imajdan yeniden oluşur; tr-ist-1'de ek diskler ve snapshot'lar da silinir, IP adresleri, siparişteki SSH anahtarları ve plan kalır. Plan değişikliği (`/cloud/services/{id}/resize`) veriyi asla silmez.",
    "x-scope": "cloud_write",
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "image": {
          "type": "string",
          "description": "rebuild only: image slug from /cloud/images",
          "example": "ubuntu-24.04"
         },
         "confirm": {
          "type": "boolean",
          "description": "required for reset and rebuild"
         },
         "user_data": {
          "type": "string",
          "maxLength": 32768,
          "description": "rebuild only (tr-ist-1 Gyro Compute): cloud-init for the new system; must start with `#cloud-config` or `#!`. Cannot be combined with `app`."
         },
         "app": {
          "type": "string",
          "description": "rebuild only: one-click app id from GET /cloud/apps, installed automatically on top of the new system (cloud servers: Gyro Cloud EU/US/SG and Istanbul). The image must be one the app supports (`os` of the app). Follow the install with GET /cloud/servers/{id}/app and /app/log. Cannot be combined with `user_data`; at most 3 app installs per server per hour.",
          "example": "uptime-kuma"
         },
         "app_domain": {
          "type": "string",
          "maxLength": 190,
          "description": "rebuild with `app` only: your domain for the app (its A record must point to the server); empty = automatic `<ip-with-dashes>.gyroapp.net` address."
         }
        }
       }
      }
     }
    },
    "responses": {
     "202": {
      "description": "Accepted",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "data": {
           "$ref": "#/components/schemas/ActionResult"
          }
         }
        }
       }
      }
     },
     "404": {
      "$ref": "#/components/responses/NotFound"
     },
     "409": {
      "$ref": "#/components/responses/Conflict"
     },
     "422": {
      "$ref": "#/components/responses/Validation"
     }
    }
   },
   "parameters": [
    {
     "$ref": "#/components/parameters/ServerId"
    },
    {
     "name": "action",
     "in": "path",
     "required": true,
     "schema": {
      "type": "string",
      "enum": [
       "poweron",
       "shutdown",
       "reboot",
       "poweroff",
       "reset",
       "rebuild",
       "reset_password",
       "enable_rescue",
       "disable_rescue"
      ]
     },
     "description": "`shutdown` = graceful (ACPI), `poweroff` = hard power cut, `reset` = hard reset (needs confirm),\n`rebuild` = reinstall from `image` (needs confirm, **wipes the disk**), `reset_password` / `enable_rescue`\nreturn a one-time `root_password`.\n"
    }
   ]
  }
 },
 "components": {
  "parameters": {
   "ServerId": {
    "name": "id",
    "in": "path",
    "required": true,
    "schema": {
     "type": "integer"
    },
    "description": "Server id (= service id in the client area)"
   }
  },
  "responses": {
   "Validation": {
    "description": "Validation or business rule failure (`confirm_required`, `invalid_image`, `tool_action_failed` ...)",
    "content": {
     "application/json": {
      "schema": {
       "$ref": "#/components/schemas/Error"
      }
     }
    }
   },
   "Conflict": {
    "description": "State conflict (`server_locked`, `not_actionable`, `ssh_key_exists`, `server_limit`, `idempotency_in_flight`)",
    "content": {
     "application/json": {
      "schema": {
       "$ref": "#/components/schemas/Error"
      }
     }
    }
   },
   "NotFound": {
    "description": "Not found — also returned for objects owned by someone else",
    "content": {
     "application/json": {
      "schema": {
       "$ref": "#/components/schemas/Error"
      }
     }
    }
   }
  },
  "schemas": {
   "Error": {
    "type": "object",
    "required": [
     "error"
    ],
    "properties": {
     "error": {
      "type": "object",
      "required": [
       "code",
       "message"
      ],
      "properties": {
       "code": {
        "type": "string",
        "example": "server_not_found"
       },
       "message": {
        "type": "string"
       },
       "details": {
        "type": "object",
        "additionalProperties": true,
        "description": "Extra data. Limit refusals add the LimitHint fields (`limit_exceeded: true`, `limit_key`, `limit`, `current`, `how_to_increase`, `support_ticket`, `hint`): account limits are raised with a support ticket. Validation errors (length, format) never carry the limit hint.",
        "x-description-tr": "Ek veri. Sınır retlerinde LimitHint alanları gelir: hesap sınırları destek talebiyle artırılır. Doğrulama hataları (uzunluk, biçim) sınır ipucu taşımaz."
       }
      }
     }
    }
   },
   "ActionResult": {
    "type": "object",
    "properties": {
     "action": {
      "type": "string"
     },
     "status": {
      "type": "string",
      "const": "accepted"
     },
     "server_id": {
      "type": "integer"
     },
     "message": {
      "type": "string",
      "description": "Human readable, in the account language"
     },
     "root_password": {
      "type": "string",
      "description": "One-time secret (rebuild without SSH key, reset_password, enable_rescue)"
     },
     "root_password_withheld": {
      "type": "boolean"
     },
     "app_install_id": {
      "type": "integer",
      "description": "rebuild with `app`: id of the started app install (GET /cloud/servers/{id}/app)"
     }
    }
   }
  }
 },
 "security": [
  {
   "bearerAuth": []
  }
 ]
}