NoctHost API

openapi: 3.1.0
info:
  title: NoctHost API
  version: '2026-11-02'
  description: 'GENERATED FROM DOCUMENTATION by API Evangelist on 2026-11-02: 18 operation(s) read from 3 public documentation page(s) (each operation
    names its page in x-source). This is not the provider''s published contract; NoctHost has published no machine-readable contract that the
    pipeline could find. Engine: local.'
  x-evidence-tiers:
    code-example: 1
    documentation: 17
    pages-with-code: 1
    pages-read: 3
  x-generated-from: documentation
  x-provenance: generated
  x-authored-by: API Evangelist
  x-generated: '2026-11-02'
  x-generator: generate-contract-from-docs.py
  x-engine: local
  x-sources:
  - https://nocthost.com/docs/api
  - https://nocthost.com/docs/vps-for-scraping
  - https://nocthost.com/docs/ci-runners
servers:
- url: https://api.nocthost.com
paths:
  /auth/login:
    post:
      operationId: post_auth_login
      tags:
      - Auth
      summary: Get a fresh access token (expires in 15 minutes).
      x-source: https://nocthost.com/docs/api
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostAuthLoginRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostAuthLoginResponse'
      x-evidence:
        kind: documentation
  /auth/me:
    get:
      operationId: get_auth_me
      tags:
      - Auth
      summary: 'Whoami: id, email and current balance.'
      x-source: https://nocthost.com/docs/api
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetAuthMeResponse'
      x-evidence:
        kind: documentation
  /auth/register:
    post:
      operationId: post_auth_register
      tags:
      - Auth
      summary: Create an account. Email + password is all that is needed.
      x-source: https://nocthost.com/docs/api
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostAuthRegisterRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostAuthRegisterResponse'
      x-evidence:
        kind: documentation
  /backups:
    get:
      operationId: get_backups
      tags:
      - Backups
      summary: List your backups (full disk snapshots, kept 7 days).
      x-source: https://nocthost.com/docs/api
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetBackupsResponse'
      x-evidence:
        kind: documentation
    post:
      operationId: post_backups
      tags:
      - Backups
      summary: 'Back up a server. Async: snapshot takes minutes, PENDING -> AVAILABLE.'
      x-source: https://nocthost.com/docs/api
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostBackupsRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostBackupsResponse'
      x-evidence:
        kind: documentation
  /backups/{id}:
    delete:
      operationId: delete_backups_id
      tags:
      - Backups
      summary: Delete a backup before its 7-day expiry.
      x-source: https://nocthost.com/docs/api
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteBackupsIdResponse'
      x-evidence:
        kind: documentation
  /backups/{id}/restore:
    post:
      operationId: post_backups_id_restore
      tags:
      - Backups
      summary: Restore an AVAILABLE backup onto a new server (gets a new IP).
      x-source: https://nocthost.com/docs/api
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostBackupsIdRestoreRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostBackupsIdRestoreResponse'
      x-evidence:
        kind: documentation
  /billing:
    get:
      operationId: get_billing
      tags:
      - Billing
      summary: Balance and total hourly spend across active servers.
      x-source: https://nocthost.com/docs/api
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetBillingResponse'
      x-evidence:
        kind: documentation
  /servers:
    delete:
      operationId: delete_servers
      tags:
      - Servers
      summary: Destroy a server. Billing stops the same hour.
      x-source: https://nocthost.com/docs/api
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteServersResponse'
      x-evidence:
        kind: documentation
    get:
      operationId: get_servers
      tags:
      - Servers
      summary: List all non-destroyed servers.
      x-source: https://nocthost.com/docs/api
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetServersResponse'
      x-evidence:
        kind: documentation
    post:
      operationId: post_servers
      tags:
      - Servers
      summary: POST /servers
      x-source: https://nocthost.com/docs/api
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostServersRequest'
      responses:
        '201':
          description: Success (shape read from the example response on the page)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostServersResponse'
      x-evidence:
        kind: code-example
        language: curl
        snippet: 'curl https://api.nocthost.com/servers  -H "Authorization: Bearer $NOCTHOST_KEY" Access token: for interactive sessions POST
          /auth/login returns a short-lived token (15 minutes). Fine for a one-off script you run by hand; for anything unattended use an API
          key instead. curl -X POST https://api.nocthost.com/auth/login  -H "content-type: application/json"  -d ''{"email":"you@example.com","password":"…'
  /servers/{id}:
    delete:
      operationId: delete_servers_id
      tags:
      - Servers
      summary: Destroy a server. Billing stops the same hour.
      x-source: https://nocthost.com/docs/api
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteServersIdResponse'
      x-evidence:
        kind: documentation
    get:
      operationId: get_servers_id
      tags:
      - Servers
      summary: One server. Poll this every ~5s after a deploy.
      x-source: https://nocthost.com/docs/api
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetServersIdResponse'
      x-evidence:
        kind: documentation
  /servers/{id}/reboot:
    post:
      operationId: post_servers_id_reboot
      tags:
      - Servers
      summary: Reboot a running server.
      x-source: https://nocthost.com/docs/api
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostServersIdRebootResponse'
      x-evidence:
        kind: documentation
  /servers/{id}/root-password:
    post:
      operationId: post_servers_id_root_password
      tags:
      - Servers
      summary: Set a new root password without erasing the disk.
      x-source: https://nocthost.com/docs/api
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostServersIdRootPasswordRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostServersIdRootPasswordResponse'
      x-evidence:
        kind: documentation
  /servers/{id}/start:
    post:
      operationId: post_servers_id_start
      tags:
      - Servers
      summary: Power a STOPPED server back on.
      x-source: https://nocthost.com/docs/api
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostServersIdStartResponse'
      x-evidence:
        kind: documentation
  /servers/{id}/stop:
    post:
      operationId: post_servers_id_stop
      tags:
      - Servers
      summary: Power off a server. STOPPED is still billed while it exists.
      x-source: https://nocthost.com/docs/api
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostServersIdStopResponse'
      x-evidence:
        kind: documentation
  /servers/bulk:
    post:
      operationId: post_servers_bulk
      tags:
      - Servers
      summary: Deploy up to 10 servers in one call. Labels get -1..-N suffixes.
      x-source: https://nocthost.com/docs/api
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostServersBulkRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostServersBulkResponse'
      x-evidence:
        kind: documentation
components:
  schemas:
    PostAuthLoginRequest:
      type: object
      properties:
        email:
          type: string
        password:
          type: string
      required:
      - email
      - password
    PostAuthLoginResponse:
      type: object
      properties:
        accessToken:
          type: string
        user:
          type: object
    GetAuthMeResponse:
      type: object
      properties:
        user:
          type: object
    PostAuthRegisterRequest:
      type: object
      properties:
        email:
          type: string
        password:
          type: string
      required:
      - email
      - password
    PostAuthRegisterResponse:
      type: object
      properties:
        accessToken:
          type: string
        user:
          type: object
    GetBackupsResponse:
      type: object
      properties:
        backups:
          type: array
          description: Array of backup objects
        id:
          type: string
          description: Backup identifier
        label:
          type: string
          description: Backup label
        status:
          type: string
          description: Backup status
        region:
          type: string
          description: Region of the backup
        plan:
          type: string
          description: Plan of the backup
        createdAt:
          type: string
          description: Creation timestamp
        expiresAt:
          type: string
          description: Expiry timestamp
    PostBackupsRequest:
      type: object
      properties:
        serverId:
          type: string
          description: ID of the server to back up
      required:
      - serverId
    PostBackupsResponse:
      type: object
      properties:
        backup:
          type: object
          description: Backup object
        status:
          type: string
          description: PENDING
    DeleteBackupsIdResponse:
      type: object
      properties:
        ok:
          type: boolean
          description: 'true'
    PostBackupsIdRestoreRequest:
      type: object
      properties:
        password:
          type: string
          description: Root password of the restored server (12–72 chars, 3 of lower/upper/digits/symbols, no spaces)
        planId:
          type: string
          description: Optional plan ID to restore onto a bigger plan
      required:
      - password
    PostBackupsIdRestoreResponse:
      type: object
      properties:
        server:
          type: object
          description: New server object
        status:
          type: string
          description: PROVISIONING
    GetBillingResponse:
      type: object
      properties:
        balance:
          type: string
        hourlySpend:
          type: string
    DeleteServersResponse:
      type: object
      properties:
        ok:
          type: boolean
    GetServersResponse:
      type: object
      properties:
        servers:
          type: array
    PostServersRequest:
      type: object
      properties:
        email:
          type: string
        password:
          type: string
    PostServersResponse:
      type: object
      properties:
        accessToken:
          type: string
        user:
          type: object
    DeleteServersIdResponse:
      type: object
      properties:
        ok:
          type: boolean
          description: 'true'
    GetServersIdResponse:
      type: object
      properties:
        server:
          type: object
    PostServersIdRebootResponse:
      type: object
      properties:
        server:
          type: object
    PostServersIdRootPasswordRequest:
      type: object
      properties:
        password:
          type: string
          description: 12-72 chars, no spaces
      required:
      - password
    PostServersIdRootPasswordResponse:
      type: object
      properties:
        password:
          type: string
          description: New root password
        matchesRequested:
          type: boolean
          description: Whether the returned password matches the requested one
        note:
          type: string
          description: Additional information
    PostServersIdStartResponse:
      type: object
      properties:
        server:
          type: object
          description: Server object with updated status
        status:
          type: string
          description: ACTIVE
    PostServersIdStopResponse:
      type: object
      properties:
        server:
          type: object
    PostServersBulkRequest:
      type: object
      properties:
        label:
          type: string
        count:
          type: integer
        planId:
          type: string
        regionId:
          type: string
        password:
          type: string
        sshKey:
          type: string
      required:
      - label
      - count
      - planId
      - regionId
      - password
    PostServersBulkResponse:
      type: object
      properties:
        servers:
          type: array
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
security:
- bearer: []
tags:
- name: Auth
- name: Backups
- name: Billing
- name: Servers