openapi: 3.2.0
info:
  title: ServGhost Agent Servers 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: Servers
paths:
  /api/v1/servers/{id}:
    get:
      summary: Get server credentials (active immediately after a successful POST /orders)
      security:
      - BearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Server
      tags:
      - Servers
      operationId: getApiV1ServersById
      x-operation-id-source: derived
  /api/v1/servers/{id}/action:
    post:
      summary: Lifecycle action (reboot/shutdown/start/reinstall/console_link)
      security:
      - BearerAuth: []
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      requestBody:
        required: true
        content:
          application/json:
            example:
              action: reboot
      responses:
        '200':
          description: Queued
      tags:
      - Servers
      operationId: postApiV1ServersByIdAction
      x-operation-id-source: derived
components:
  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.