GPU Cloud Backups API

openapi: 3.2.0
info:
  title: GPU Cloud Backups API
  description: 'REST API of GPUcloud.ca: GPU plans, GPU servers (deploy, power actions, metrics, firewall), SSH keys and API keys. All prices are in CAD. Authenticate with a REST API key: `Authorization: Bearer `. AI agents should use the MCP endpoint (https://gpucloud.ca/api/mcp) with an MCP key instead. REST keys (prefix gpu_) are created in the console, expire after 90 days and are either full access or read-only (GET only; a read-only key gets 401 on any other method). Write requests (POST, PUT, DELETE) must also send the header `Origin: https://gpucloud.ca`, otherwise they get 403. Developer guide: https://gpucloud.ca/en/developers'
  version: 1.1.1
  contact:
    name: GPU Cloud Support
    url: https://gpucloud.ca
    email: info@gpucloud.ca
servers:
- url: https://gpucloud.ca/api
  description: Production
security: []
tags:
- name: Backups
paths:
  /servers/{id}/backups:
    parameters:
    - name: id
      in: path
      required: true
      schema:
        type: string
      description: Server ID
    get:
      summary: List backups
      description: 'Backup option: daily backup of the system disk (100 GB: operating system, software and configuration), kept 7 days. The work disk (high-capacity local storage) is not included: back up your important data elsewhere. The server is briefly interrupted during the backup, at the time you choose. 14.99 $/month for a new subscription (the price of an existing subscription stays the one of its activation). Returns the option (enabled, hourLocal 0-23 Eastern time, retention, price, billing) and the backups (id, kind, status, date, size).'
      operationId: listServerBackups
      tags:
      - Backups
      security:
      - BearerAuth: []
      responses:
        '200':
          description: Backup option and backups
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
    put:
      summary: Backup option
      description: 'Turn the option on (hourly server: billed pro rata per billed hour; prepaid server: the rest of the paid period now from credits, then with each renewal) or off (confirmDeleteBackups: true is required when backups exist: they are deleted), or change the hour / retention.'
      operationId: setServerBackupPolicy
      tags:
      - Backups
      security:
      - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                enabled:
                  type: boolean
                hourLocal:
                  type: integer
                  minimum: 0
                  maximum: 23
                retention:
                  type: integer
                  minimum: 1
                  maximum: 7
                confirmDeleteBackups:
                  type: boolean
                expectedChargeCad:
                  type: number
                expectedMonthlyPriceCad:
                  type: number
                  description: 'When turning the option on: the monthly price you were shown (GET .../backups/quote, priceMonthlyCad). If the price changed meanwhile, nothing is changed and the answer is 409 PRICE_CHANGED with the current price.'
            example:
              enabled: true
              hourLocal: 3
              retention: 7
              expectedMonthlyPriceCad: 14.99
      responses:
        '200':
          description: Option updated
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      summary: Back up now
      description: Starts a backup of the system disk now (option enabled, at most 2 manual backups kept). The server is briefly interrupted (a few minutes).
      operationId: createServerBackup
      tags:
      - Backups
      security:
      - BearerAuth: []
      responses:
        '200':
          description: Backup started
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
  /servers/{id}/backups/{backupId}:
    parameters:
    - name: id
      in: path
      required: true
      schema:
        type: string
      description: Server ID
    - name: backupId
      in: path
      required: true
      schema:
        type: string
      description: Backup ID (from GET /servers/{id}/backups)
    delete:
      summary: Delete a backup
      description: Deletes one backup (not while it is being created).
      operationId: deleteServerBackup
      tags:
      - Backups
      security:
      - BearerAuth: []
      responses:
        '200':
          description: Backup deleted
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
  /servers/{id}/backups/{backupId}/restore:
    parameters:
    - name: id
      in: path
      required: true
      schema:
        type: string
      description: Server ID
    - name: backupId
      in: path
      required: true
      schema:
        type: string
      description: Backup ID (from GET /servers/{id}/backups)
    get:
      summary: Restore price
      description: 'Price of restoring this backup to a NEW server (hourly billing: first hour from credits).'
      operationId: quoteBackupRestore
      tags:
      - Backups
      security:
      - BearerAuth: []
      responses:
        '200':
          description: Restore price
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      summary: Restore to a new server
      description: Creates a NEW server (same GPU model and region) from the backup; the original server is not changed. Billed like any new hourly server (first hour from credits, budget limits apply).
      operationId: restoreServerBackup
      tags:
      - Backups
      security:
      - BearerAuth: []
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                expectedHourlyRateCad:
                  type: number
            example:
              name: train-restored
      responses:
        '200':
          description: New server created
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: Backup not ready / out of stock
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
  /servers/{id}/migrate:
    parameters:
    - name: id
      in: path
      required: true
      schema:
        type: string
      description: Server ID
    get:
      summary: 'Move to another GPU: options'
      description: '"Migrate my VM to another GPU": whether this server can move now (the backup option must be on), the GPUs in stock it may move to with their price per hour for your account, the sources (a new backup now, or the latest backup), the move in progress or the last one. Only the system disk (100 GB) is copied; the work disk is not.'
      operationId: getServerMigrationOptions
      tags:
      - Backups
      security:
      - BearerAuth: []
      responses:
        '200':
          description: Options
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
    post:
      summary: Move to another GPU
      description: Creates a NEW server of the chosen GPU (in stock) from the system disk of this server; the original server is not changed and stays billed until you delete it. Billed like any new hourly server (first hour from credits, budget limits apply). About 20 minutes from a new backup, 5 from the latest one; the new server gets a new public IP address; the work disk is not copied. One move at a time per server.
      operationId: migrateServer
      tags:
      - Backups
      security:
      - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - targetProductId
              - source
              properties:
                targetProductId:
                  type: string
                  description: Catalog id of the destination GPU (from GET)
                source:
                  type: string
                  enum:
                  - fresh
                  - latest
                expectedHourlyRateCad:
                  type: number
                name:
                  type: string
                keepBackup:
                  type: boolean
            example:
              targetProductId: gpu-a100-pcie
              source: fresh
              expectedHourlyRateCad: 2.09
      responses:
        '202':
          description: Move started
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Backup option off / GPU not allowed / invalid input
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: Move already in progress / out of stock / price changed / no backup
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  responses:
    PaymentRequired:
      description: 'Payment required (accountAction.code PAYMENT_REQUIRED: not enough credit, no saved card or a declined card) or a budget cap reached (BUDGET_CAP_REACHED: account or server budget limit, nothing charged). accountAction.balanceCad gives the balance and, when a server is concerned, accountAction.hibernationThresholdCad its hibernation threshold (a server is hibernated when the balance reaches it and restarts as soon as the balance is above it; it is deleted only once the account''s credit is exhausted, after three notices). Add your card and credits at accountAction.action.url (or raise the cap), then send the same request again.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AccountActionError'
          examples:
            insufficientCredits:
              summary: Not enough credit to deploy
              value:
                error: INSUFFICIENT_CREDITS
                message: Payment required. You need a paid order or at least enough credits for 1 hour of usage.
                requiredCredits: 1.55
                currentBalance: 0
                accountAction:
                  code: PAYMENT_REQUIRED
                  message: 'Payment required. Add your card and credits here, then run the same request again: you will get your GPU. https://gpucloud.ca/en/console/billing?addCredits=25 At least 1.55 CAD is needed to cover one hour of this GPU (smallest credit purchase: 25 CAD).'
                  action:
                    label: Add a card and credits
                    url: https://gpucloud.ca/en/console/billing?addCredits=25
                  links:
                    signup: https://gpucloud.ca/en/auth/register
                    login: https://gpucloud.ca/en/auth/login
                    apiKeys: https://gpucloud.ca/en/console/settings#api-keys
                    billing: https://gpucloud.ca/en/console/billing
                    addCredits: https://gpucloud.ca/en/console/billing?addCredits=25
                    paymentMethod: https://gpucloud.ca/en/console/billing?addCredits=25#payment-method
                    budget: https://gpucloud.ca/en/console/billing#budget-limit
                    documentation: https://gpucloud.ca/en/developers#errors
                  minimumCad: 1.55
                  minimumTopupCad: 25
            budgetCap:
              summary: Account budget limit reached
              value:
                error: BUDGET_LIMIT_REACHED
                message: The monthly budget limit of this account is reached.
                scope: account
                accountAction:
                  code: BUDGET_CAP_REACHED
                  message: 'The budget limit of this account was reached: nothing was charged. The account owner can raise or remove this limit here, then run the same request again: https://gpucloud.ca/en/console/billing#budget-limit'
                  action:
                    label: Change the limit
                    url: https://gpucloud.ca/en/console/billing#budget-limit
                  links:
                    signup: https://gpucloud.ca/en/auth/register
                    login: https://gpucloud.ca/en/auth/login
                    apiKeys: https://gpucloud.ca/en/console/settings#api-keys
                    billing: https://gpucloud.ca/en/console/billing
                    addCredits: https://gpucloud.ca/en/console/billing?addCredits=25
                    paymentMethod: https://gpucloud.ca/en/console/billing?addCredits=25#payment-method
                    budget: https://gpucloud.ca/en/console/billing#budget-limit
                    documentation: https://gpucloud.ca/en/developers#errors
    BadRequest:
      description: Invalid request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Invalid input
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Server not found
    TooManyRequests:
      description: Rate limit exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Too many requests
    Unauthorized:
      description: 'No API key (accountAction.code NO_API_KEY) or an invalid, expired, revoked or read only key on a write (INVALID_API_KEY). Provide a valid API key as `Authorization: Bearer <key>`; accountAction gives the links to create an account and a key.'
      headers:
        WWW-Authenticate:
          schema:
            type: string
          description: Bearer realm="gpucloud" (error="invalid_token" when a key was sent).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AccountActionError'
          examples:
            noKey:
              summary: No key sent
              value:
                error: Unauthorized. Use Bearer API key.
                message: 'No API key was sent. Create a GPU Cloud account (https://gpucloud.ca/en/auth/register), then an API key in the console (https://gpucloud.ca/en/console/settings#api-keys), and send it in the header Authorization: Bearer gpu_...'
                accountAction:
                  code: NO_API_KEY
                  message: 'No API key was sent. Create a GPU Cloud account (https://gpucloud.ca/en/auth/register), then an API key in the console (https://gpucloud.ca/en/console/settings#api-keys), and send it in the header Authorization: Bearer gpu_...'
                  action:
                    label: Create an account
                    url: https://gpucloud.ca/en/auth/register
                  links:
                    signup: https://gpucloud.ca/en/auth/register
                    login: https://gpucloud.ca/en/auth/login
                    apiKeys: https://gpucloud.ca/en/console/settings#api-keys
                    billing: https://gpucloud.ca/en/console/billing
                    addCredits: https://gpucloud.ca/en/console/billing?addCredits=25
                    paymentMethod: https://gpucloud.ca/en/console/billing?addCredits=25#payment-method
                    budget: https://gpucloud.ca/en/console/billing#budget-limit
                    documentation: https://gpucloud.ca/en/developers#errors
            invalidKey:
              summary: Invalid, expired or revoked key
              value:
                error: Unauthorized
                message: 'This API key is invalid, expired, revoked or lacks the required permission. Create a new API key in the console (https://gpucloud.ca/en/console/settings#api-keys) and send it in the header Authorization: Bearer gpu_... No account yet: https://gpucloud.ca/en/auth/register'
                accountAction:
                  code: INVALID_API_KEY
                  message: 'This API key is invalid, expired, revoked or lacks the required permission. Create a new API key in the console (https://gpucloud.ca/en/console/settings#api-keys) and send it in the header Authorization: Bearer gpu_... No account yet: https://gpucloud.ca/en/auth/register'
                  action:
                    label: Create an API key
                    url: https://gpucloud.ca/en/console/settings#api-keys
                  links:
                    signup: https://gpucloud.ca/en/auth/register
                    login: https://gpucloud.ca/en/auth/login
                    apiKeys: https://gpucloud.ca/en/console/settings#api-keys
                    billing: https://gpucloud.ca/en/console/billing
                    addCredits: https://gpucloud.ca/en/console/billing?addCredits=25
                    paymentMethod: https://gpucloud.ca/en/console/billing?addCredits=25#payment-method
                    budget: https://gpucloud.ca/en/console/billing#budget-limit
                    documentation: https://gpucloud.ca/en/developers#errors
    InternalError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Internal server error
  schemas:
    AccountAction:
      type: object
      description: What to do to fix an account or payment problem, with the direct absolute link. Same object on every route and in the MCP tool errors (structuredContent.error.accountAction). The message is in French when Accept-Language asks for it, otherwise in English.
      properties:
        code:
          type: string
          enum:
          - NO_API_KEY
          - INVALID_API_KEY
          - PAYMENT_REQUIRED
          - BUDGET_CAP_REACHED
          description: Stable machine code. NO_API_KEY and INVALID_API_KEY come with HTTP 401, PAYMENT_REQUIRED and BUDGET_CAP_REACHED with HTTP 402.
        message:
          type: string
          description: Clear sentence telling what to do, including the link.
        action:
          type: object
          properties:
            label:
              type: string
            url:
              type: string
              format: uri
          required:
          - label
          - url
        links:
          type: object
          description: 'Absolute links: account creation, sign in, API keys page, billing, add credits (opens the credit window), payment card, budget or cap setting, documentation.'
          properties:
            signup:
              type: string
              format: uri
            login:
              type: string
              format: uri
            apiKeys:
              type: string
              format: uri
            billing:
              type: string
              format: uri
            addCredits:
              type: string
              format: uri
            paymentMethod:
              type: string
              format: uri
            budget:
              type: string
              format: uri
            documentation:
              type: string
              format: uri
          required:
          - signup
          - login
          - apiKeys
          - billing
          - addCredits
          - paymentMethod
          - budget
          - documentation
        minimumCad:
          type: number
          description: 'PAYMENT_REQUIRED only, when known: credits (CAD) covering one hour of the GPU asked for, computed by the server from the same price as the deployment.'
        minimumTopupCad:
          type: number
          description: Smallest credit purchase accepted (CAD), given with minimumCad.
        balanceCad:
          type: number
          description: 'PAYMENT_REQUIRED and BUDGET_CAP_REACHED, when known: the account''s credit balance (CAD) when the request was refused.'
        hibernationThresholdCad:
          type: number
          description: 'PAYMENT_REQUIRED, when a server is concerned: its hibernation threshold (CAD), the larger of 3 CAD and 2 hours of its hourly rate. A running hourly server is hibernated when the balance reaches its threshold (after the automatic reload was tried); it restarts automatically as soon as the balance is above the threshold. A server is never deleted while the account has credit left. When the balance covers only about 24 hours of what the account spends per hour, a first notice is sent while the servers still run, then two more about 24 hours and 1 hour before the deletion; a server is deleted with its data only once it is out of service (stopped or hibernated for lack of credit, or hibernated by the user for at least 72 hours), once the credit is exhausted (the balance no longer pays the next hour of the account''s servers), after the three notices and at least 24 hours after the first. Adding credits cancels the deletion. For the restart of such a server, minimumCad is the balance that restarts it (threshold + 0.01).'
        capCad:
          type: number
          description: 'BUDGET_CAP_REACHED of an MCP key, for a money cap: the cap reached (CAD). The cap set by the customer is always respected: nothing is charged or reloaded beyond it.'
        capRemainingCad:
          type: number
          description: 'BUDGET_CAP_REACHED of an MCP key, with capCad: what is left of that cap (CAD).'
      required:
      - code
      - message
      - action
      - links
    AccountActionError:
      type: object
      description: 'Error of an account or payment problem. Backward compatible: `error` keeps its previous string value (for example "Unauthorized" or "INSUFFICIENT_CREDITS"), `message` and the existing details stay; `accountAction` is added.'
      properties:
        error:
          type: string
          description: Previous error string or code, unchanged (backward compatibility).
        message:
          type: string
        requiredCredits:
          type: number
          description: 'INSUFFICIENT_CREDITS: credits (CAD) the action needs.'
        currentBalance:
          type: number
        accountAction:
          $ref: '#/components/schemas/AccountAction'
      required:
      - error
      - accountAction
    Error:
      type: object
      properties:
        error:
          type: string
      required:
      - error
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: 'REST API key (prefix gpu_) created in the GPU Cloud console (Settings). Pass it as `Authorization: Bearer <your-api-key>`. Keys expire after 90 days; a read-only key may only call GET. Write requests (POST, PUT, DELETE) must also send `Origin: https://gpucloud.ca`.'