{
  "openapi": "3.1.0",
  "info": {
    "title": "NoctHost API",
    "version": "1.0.0",
    "description": "Deploy and manage hourly-billed servers on Hetzner, Vultr, DigitalOcean, Linode and OVHcloud, plus bare metal on Cherry Servers, from one account and one prepaid balance. Full guide for AI agents: https://nocthost.com/llms.txt",
    "contact": {
      "name": "NoctHost",
      "url": "https://nocthost.com/docs/support"
    },
    "termsOfService": "https://nocthost.com/terms",
    "x-logo": {
      "url": "https://nocthost.com/icon.svg"
    }
  },
  "externalDocs": {
    "description": "API reference",
    "url": "https://nocthost.com/docs/api"
  },
  "servers": [
    {
      "url": "https://api.nocthost.com"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "Auth"
    },
    {
      "name": "Billing"
    },
    {
      "name": "Servers"
    },
    {
      "name": "Backups"
    }
  ],
  "paths": {
    "/auth/register": {
      "post": {
        "operationId": "postAuthRegister",
        "summary": "Create an account.",
        "description": "Create an account. Email + password is all that is needed.",
        "tags": [
          "Auth"
        ],
        "responses": {
          "201": {
            "description": "Example: {\"accessToken\":\"<jwt>\",\"user\":{\"id\",\"email\",\"balance\"}}",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [],
        "requestBody": {
          "required": true,
          "description": "Example: {\"email\":\"agent@example.com\",\"password\":\"min-8-chars\"}",
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "example": {
                "email": "agent@example.com",
                "password": "min-8-chars"
              }
            }
          }
        }
      }
    },
    "/auth/login": {
      "post": {
        "operationId": "postAuthLogin",
        "summary": "Get a fresh access token (expires in 15 minutes).",
        "description": "Get a fresh access token (expires in 15 minutes).",
        "tags": [
          "Auth"
        ],
        "responses": {
          "200": {
            "description": "Example: {\"accessToken\":\"<jwt>\",\"user\":{...}}",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "security": [],
        "requestBody": {
          "required": true,
          "description": "Example: {\"email\":\"...\",\"password\":\"...\"}",
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "example": {
                "email": "...",
                "password": "..."
              }
            }
          }
        }
      }
    },
    "/auth/me": {
      "get": {
        "operationId": "getAuthMe",
        "summary": "Whoami: id, email and current balance.",
        "description": "Whoami: id, email and current balance.",
        "tags": [
          "Auth"
        ],
        "responses": {
          "200": {
            "description": "Example: {\"user\":{\"id\",\"email\",\"balance\":\"9.96\"}}",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/billing": {
      "get": {
        "operationId": "getBilling",
        "summary": "Balance and total hourly spend across active servers.",
        "description": "Balance and total hourly spend across active servers.",
        "tags": [
          "Billing"
        ],
        "responses": {
          "200": {
            "description": "Example: {\"balance\":\"9.96\",\"hourlySpend\":\"0.012\"}",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "balance": "9.96",
                  "hourlySpend": "0.012"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/servers": {
      "get": {
        "operationId": "getServers",
        "summary": "List all non-destroyed servers.",
        "description": "List all non-destroyed servers.",
        "tags": [
          "Servers"
        ],
        "responses": {
          "200": {
            "description": "Example: {\"servers\":[{\"id\",\"label\",\"status\",\"region\",\"plan\",\"ipv4\",\"hourlyPrice\",\"createdAt\"}]}",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "operationId": "postServers",
        "summary": "Deploy one server.",
        "description": "Deploy one server. Async: 202 = accepted, not yet running. Optional osId (see the OS list in the catalog below, default Ubuntu 22.04) or appSlug (one-click app, Vultr only) - pick at most one. osId works on every provider; each supports a subset of the list, and an OS the chosen provider does not carry returns 400. Optional sshKey installs a public key for root at first boot. OVHcloud GPU sizes with a monthly price (L4, L40S, A100, H100) accept billingCycle set to monthly. Such a server is paid per calendar month upfront, the rest of the current month now and the full monthly price on the 1st, with no refund if deleted early. Regular (non-GPU) sizes also accept billingCycle set to monthly together with expectedMonthlyUsd, the monthly price you were shown: one month from today is paid upfront at a discount (10%, 5% on DigitalOcean) and renews from your balance; if the price is now higher the request returns 409. Turn renewal off with POST /servers/{id}/auto-renew and the server moves to hourly billing at the end of the paid month. Default is hourly.",
        "tags": [
          "Servers"
        ],
        "responses": {
          "202": {
            "description": "Example: {\"server\":{...,\"status\":\"PROVISIONING\"}}",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "requestBody": {
          "required": true,
          "description": "Example: {\"label\":\"my-bot\",\"planId\":\"vc2-1c-1gb\",\"regionId\":\"ams\",\"osId\":1743,\"providerId\":\"vultr\",\"password\":\"12-72 chars, no spaces\",\"sshKey\":\"ssh-ed25519 AAAA... you@host\"}",
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "example": {
                "label": "my-bot",
                "planId": "vc2-1c-1gb",
                "regionId": "ams",
                "osId": 1743,
                "providerId": "vultr",
                "password": "12-72 chars, no spaces",
                "sshKey": "ssh-ed25519 AAAA... you@host"
              }
            }
          }
        }
      }
    },
    "/servers/{id}": {
      "get": {
        "operationId": "getServersById",
        "summary": "One server.",
        "description": "One server. Poll this every ~5s after a deploy.",
        "tags": [
          "Servers"
        ],
        "responses": {
          "200": {
            "description": "Example: {\"server\":{...,\"status\":\"ACTIVE\",\"ipv4\":\"203.0.113.10\"}}",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      },
      "delete": {
        "operationId": "deleteServersById",
        "summary": "Destroy a server.",
        "description": "Destroy a server. Billing stops the same hour.",
        "tags": [
          "Servers"
        ],
        "responses": {
          "202": {
            "description": "Example: {\"ok\":true}",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "ok": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/servers/providers": {
      "get": {
        "operationId": "getServersProviders",
        "summary": "Which backends can take a deploy right now, and which of their regions are temporarily out of capacity.",
        "description": "Which backends can take a deploy right now, and which of their regions are temporarily out of capacity. Check this before picking providerId/regionId.",
        "tags": [
          "Servers"
        ],
        "responses": {
          "200": {
            "description": "Example: {\"providers\":[{\"id\":\"vultr\",\"label\",\"available\":true}],\"outages\":{\"hetzner\":{\"fra\":\"...\"}}}",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/servers/bulk": {
      "post": {
        "operationId": "postServersBulk",
        "summary": "Deploy up to 10 servers in one call.",
        "description": "Deploy up to 10 servers in one call. Labels get -1..-N suffixes.",
        "tags": [
          "Servers"
        ],
        "responses": {
          "202": {
            "description": "Example: {\"servers\":[...10 items, all \"PROVISIONING\"]}",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "requestBody": {
          "required": true,
          "description": "Example: {\"label\":\"fleet\",\"count\":10,\"planId\":\"vc2-1c-1gb\",\"regionId\":\"ams\",\"password\":\"applied to all\",\"sshKey\":\"optional, applied to all\"}",
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "example": {
                "label": "fleet",
                "count": 10,
                "planId": "vc2-1c-1gb",
                "regionId": "ams",
                "password": "applied to all",
                "sshKey": "optional, applied to all"
              }
            }
          }
        }
      }
    },
    "/servers/{id}/reboot": {
      "post": {
        "operationId": "postServersByIdReboot",
        "summary": "Reboot a running server.",
        "description": "Reboot a running server.",
        "tags": [
          "Servers"
        ],
        "responses": {
          "200": {
            "description": "Example: {\"server\":{...}}",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/servers/{id}/stop": {
      "post": {
        "operationId": "postServersByIdStop",
        "summary": "Power off a server.",
        "description": "Power off a server. STOPPED is still billed while it exists.",
        "tags": [
          "Servers"
        ],
        "responses": {
          "200": {
            "description": "Example: {\"server\":{...,\"status\":\"STOPPED\"}}",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/servers/{id}/start": {
      "post": {
        "operationId": "postServersByIdStart",
        "summary": "Power a STOPPED server back on.",
        "description": "Power a STOPPED server back on.",
        "tags": [
          "Servers"
        ],
        "responses": {
          "200": {
            "description": "Example: {\"server\":{...,\"status\":\"ACTIVE\"}}",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/servers/{id}/root-password": {
      "post": {
        "operationId": "postServersByIdRootPassword",
        "summary": "Set a new root password without erasing the disk, where the server page shows \"Change root password\".",
        "description": "Set a new root password without erasing the disk, where the server page shows \"Change root password\". The server must be running; Linode servers without our recovery key must be stopped first. On Hetzner without the recovery key the password you send is ignored: Hetzner generates one and returns it (matchesRequested: false). The password is shown only in this response.",
        "tags": [
          "Servers"
        ],
        "responses": {
          "200": {
            "description": "Example: {\"password\":\"...\",\"matchesRequested\":true,\"note\":\"...\"}",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "password": "...",
                  "matchesRequested": true,
                  "note": "..."
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "description": "Example: {\"password\":\"12-72 chars, no spaces\"}",
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "example": {
                "password": "12-72 chars, no spaces"
              }
            }
          }
        }
      }
    },
    "/backups": {
      "get": {
        "operationId": "getBackups",
        "summary": "List your backups (full disk snapshots, kept 7 days).",
        "description": "List your backups (full disk snapshots, kept 7 days).",
        "tags": [
          "Backups"
        ],
        "responses": {
          "200": {
            "description": "Example: {\"backups\":[{\"id\",\"label\",\"status\",\"region\",\"plan\",\"createdAt\",\"expiresAt\"}]}",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "operationId": "postBackups",
        "summary": "Back up a server.",
        "description": "Back up a server. Async: snapshot takes minutes, PENDING -> AVAILABLE.",
        "tags": [
          "Backups"
        ],
        "responses": {
          "202": {
            "description": "Example: {\"backup\":{...,\"status\":\"PENDING\"}}",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "requestBody": {
          "required": true,
          "description": "Example: {\"serverId\":\"<id>\"}",
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "example": {
                "serverId": "<id>"
              }
            }
          }
        }
      }
    },
    "/backups/{id}/restore": {
      "post": {
        "operationId": "postBackupsByIdRestore",
        "summary": "Restore an AVAILABLE backup onto a new server (gets a new IP).",
        "description": "Restore an AVAILABLE backup onto a new server (gets a new IP). password is required: the root password of the restored server (12–72 Latin chars, 3 of lower/upper/digits/symbols, no spaces). Optional planId restores onto a bigger plan.",
        "tags": [
          "Backups"
        ],
        "responses": {
          "202": {
            "description": "Example: {\"server\":{...,\"status\":\"PROVISIONING\"}}",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "description": "Example: {\"password\":\"<root password>\",\"planId\":\"<optional>\"}",
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              },
              "example": {
                "password": "<root password>",
                "planId": "<optional>"
              }
            }
          }
        }
      }
    },
    "/backups/{id}": {
      "delete": {
        "operationId": "deleteBackupsById",
        "summary": "Delete a backup before its 7-day expiry.",
        "description": "Delete a backup before its 7-day expiry.",
        "tags": [
          "Backups"
        ],
        "responses": {
          "202": {
            "description": "Example: {\"ok\":true}",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "ok": true
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "A personal API key (nh_..., created in the dashboard under Profile, API keys) or an access token from POST /auth/login (expires after 15 minutes)."
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "Missing, expired or revoked token."
      },
      "RateLimited": {
        "description": "Rate limited: 300 requests/minute authenticated, 10/minute on /auth routes. Back off exponentially."
      }
    }
  }
}