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.