ServGhost Agent API Orders API

openapi: 3.2.0
info:
  title: ServGhost Agent Orders API
  version: 2.0.0
  description: Public REST API for AI agents to discover, price, top up balance and deploy offshore VPS, dedicated, Windows RDP and GPU AI servers on servghost.com, plus anonymous domain name registration (26 TLDs, .com from $4.99/yr — -69% vs Namecheap renewal).
  contact:
    url: https://servghost.com/agents
  license:
    name: Proprietary
servers:
- url: https://servghost.com
tags:
- name: Orders
paths:
  /api/v1/orders:
    post:
      summary: Deploy a server from balance (BALANCE-ONLY)
      description: 'Debits the order total from the account''s USD balance and creates the server. **NO crypto field** — pre-fund via POST /api/v1/topup first. If the balance is short, returns 402 `insufficient_balance` with a `topup_required` block (suggested amount covers deficit + clears $30 minimum). Server is `active` immediately on success. Bearer optional — if absent, a new account is auto-created (it will have $0 balance → 402 → topup → retry).


        `type`: `vps`, `dedicated`, `rdp`, or `gpu`. For `rdp`, `os` must be a Windows slug (`win-2022`, `win-2025`, `win-2019`, `win-11`); RDP locations: `netherlands`, `romania`, `moldova`, `russia`. For `gpu`, `os` must be a Linux + CUDA image (e.g. `ubuntu-22-cuda`); GPU locations: `iceland`, `netherlands`, `romania`, `moldova`.


        **GPU-only fields** (ignored for other types):

        - `ai_stacks` (string[]): pre-install AI software at deploy time. Slugs: `vllm`, `ollama-webui`, `text-generation-webui`, `tgi`, `axolotl`, `unsloth`, `llama-factory`, `comfyui`, `a1111`, `forge`, `kohya-ss`, `comfyui-video`, `whisper-server`, `jupyterlab` (always on), `code-server`.

        - `pretrained_models` (string[]): pre-download HuggingFace models. Slugs: `llama-3.3-8b`, `llama-3.3-70b`, `qwen3-32b`, `deepseek-r1`, `mistral-small-3`, `gemma-3-27b`, `phi-4`, `flux-dev`, `flux-schnell`, `sd-3.5-large`, `sdxl-base`, `wan-2.1-t2v`, `cogvideox-5b`, `whisper-large-v3`, `bark`.

        - `hf_token` (string): HuggingFace token, required to pre-download gated models (Llama, Mistral, Gemma, FLUX-dev, SD 3.5). AES-encrypted at rest, used once at provision.

        - `ssh_public_key` (string): SSH public key (`ssh-ed25519`, `ssh-rsa`, `ecdsa-*`). Optional — for password-less login.

        - `public_endpoint` (boolean): auto-provision Let''s Encrypt + nginx reverse proxy on port 443.

        - `auto_shutdown_hours` (integer): one of 0 (never) / 6 / 12 / 24 / 48 / 168. Server self-destructs after the timer.'
      requestBody:
        required: true
        content:
          application/json:
            example:
              type: gpu
              plan: IS-L
              location: iceland
              os: ubuntu-22-cuda
              billing: 1
              ai_stacks:
              - vllm
              - jupyterlab
              pretrained_models:
              - llama-3.3-70b
              - flux-dev
              hf_token: hf_AbCdEf...
              ssh_public_key: ssh-ed25519 AAAA... user@host
              public_endpoint: true
              auto_shutdown_hours: 24
      responses:
        '201':
          description: Server deployed
          content:
            application/json:
              example:
                ok: true
                server_id: 9876
                status: active
                charged_usd: 74.22
                new_balance: 175.78
                billing_months: 1
                service_months: 1
                free_months: 0
                promo: null
                credentials_url: https://servghost.com/api/v1/servers/9876
                account_token: AAAA-BBBB-CCCC-DDDD
        '402':
          description: Insufficient balance — top up first
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InsufficientBalance'
              example:
                ok: false
                error: insufficient_balance
                message: You have $0.00, this order costs $74.22. Top up at least $74 via POST /api/v1/topup, wait for the payment to confirm, then retry POST /api/v1/orders.
                insufficient_balance: true
                have_usd: 0.0
                need_usd: 74.22
                deficit_usd: 74.22
                topup_required: true
                topup:
                  endpoint: https://servghost.com/api/v1/topup
                  method: POST
                  minimum_usd: 30
                  maximum_usd: 2000
                  suggested_usd: 75
                  suggested_bonus: 0.0
                  bonus_doc: https://servghost.com/api/v1/topup/bonus
                account_token: AAAA-BBBB-CCCC-DDDD
        '400':
          description: Bad input
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited
        '500':
          description: Server INSERT failed (balance refunded)
      tags:
      - Orders
      operationId: postApiV1Orders
      x-operation-id-source: derived
  /api/v1/orders/{id}:
    get:
      summary: 'Legacy: poll a crypto-direct order (pre-v2.0 only)'
      description: Only useful for orders created by the legacy crypto-direct API (pre-balance-only refactor). New balance-only orders do NOT generate payment rows — poll GET /api/v1/servers/{server_id} from the create response instead.
      security:
      - BearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Legacy order
        '404':
          description: Not found (likely a balance-only order — use /servers/{id})
      tags:
      - Orders
      operationId: getApiV1OrdersById
      x-operation-id-source: derived
components:
  schemas:
    InsufficientBalance:
      type: object
      description: Returned by POST /api/v1/orders when the account balance is below the order price. The `topup` block contains a suggested amount that covers the deficit AND clears the $30 platform minimum, ready to pass to POST /api/v1/topup.
      properties:
        ok:
          type: boolean
          const: false
        error:
          type: string
          const: insufficient_balance
        message:
          type: string
        insufficient_balance:
          type: boolean
          const: true
        have_usd:
          type: number
        need_usd:
          type: number
        deficit_usd:
          type: number
        topup_required:
          type: boolean
          const: true
        topup:
          type: object
          properties:
            endpoint:
              type: string
            method:
              type: string
            minimum_usd:
              type: number
              const: 30
            maximum_usd:
              type: number
              const: 2000
            suggested_usd:
              type: number
            suggested_bonus:
              type: number
            bonus_doc:
              type: string
        account_token:
          type: string
          description: Present only when the account was auto-created on this call. STORE IT.
    Error:
      type: object
      required:
      - ok
      - error
      - message
      properties:
        ok:
          type: boolean
          const: false
        error:
          type: string
          description: machine-readable code
        message:
          type: string
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: AAAA-BBBB-CCCC-DDDD
x-mcp-server: https://servghost.com/mcp
x-discovery: https://servghost.com/.well-known/agent.json
x-payment-model: 'balance-only: POST /api/v1/topup (min $30, max $2000, with bonus tiers) → wait for confirmation → POST /api/v1/orders (balance-debit, server active immediately)'
x-dry-run:
  trigger: 'Header X-Dry-Run: 1 OR ?dry_run=1 OR body.dry_run=true'
  behavior: Synthetic response, no balance impact, no provisioning. Returned shape mirrors the real one with `dry_run:true` + a `note` field.