Slide Restores (Virtual Machine) API

openapi: 3.0.0
info:
  contact:
    email: hey@slide.tech
    name: Slide Team
    url: https://docs.slide.tech
  description: "## Introduction\nThe Slide API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.\n\n## Authentication\nWe use API tokens to authenticate requests. You can view and manage your API tokens in the [Slide Console](https://docs.slide.tech).\nWhen making HTTP requests, you'll need to include the API token in the `Authorization` header, using Bearer auth (e.g. `Authorization: Bearer YOUR_SECRET_TOKEN`).\n\nExample:\n```shell\n$ curl -H 'Authorization: Bearer YOUR_SECRET_TOKEN' 'https://api.slide.tech/v1/device'\n```\n\n## Pagination\nAll list endpoints support pagination. You can use the `limit` and `offset` query parameters to control the number of items returned and the starting index.\nList responses will include a `pagination` key that includes the `next_offset` to use for pagination.\nIf `next_offset` is not present, that indicates there are no more items to fetch.\n\nExample:\n```shell\n$ curl -H 'Authorization: Bearer YOUR_SECRET_TOKEN' \\\n    'https://api.slide.tech/v1/device?offset=0&limit=10'\n{\n    \"pagination\": {\n        \"next_offset\": 10\n    },\n    \"data\": [\n        ...\n    ]\n}\n```\n\n## Rate Limiting\nWe limit the number of requests you can make to the API within a certain time frame.\nEach API token has a pool of `50` requests. We refill this pool at a rate of `10` requests per second.\nIf you exceed the rate limit, you'll receive a response with a `429 Too Many Requests` HTTP code and a `err_rate_limit_exceeded` error code.\nPlease wait before retrying the request. We recommend you implement an exponential backoff strategy to handle rate limits.\n\n## Errors\nSlide uses conventional HTTP response codes to indicate the success or failure of an API request.\nIn general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted), and codes in the 5xx range indicate an error with Slide's servers.\n\nWe also include [error codes and details](#model/error) in the response, which may provide more context about the error.\n\nExample:\n```shell\n$ curl 'https://api.slide.tech/v1/device'\n{\n    \"codes\": [\n        \"err_missing_authentication\"\n    ],\n    \"details\": [\n        ...\n    ],\n    \"message\": \"unauthorized\"\n}\n```\n\nSome common error codes are:\n\n| Code                         | Description                                                                                                                                             |\n|------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `err_endpoint_not_found`     | Requested endpoint does not exist.                                                                                                                      |\n| `err_entity_not_found`       | Requested entity does not exist.                                                                                                                        |\n| `err_validation_error`       | Bad request due to validation error. The error `details` will contain any fields that were not valid.                                                   |\n| `err_missing_authentication` | Unauthorized due to missing API token. See [authentication](#description/authentication) for more details.                                              |\n| `err_unauthorized`           | Unauthorized due to invalid API token. You've provided an invalid API token or the API token does not have permission to access the requested resource. |\n| `err_internal_server_error`  | Something went wrong. If you retry the request and it does not succeed, you may contact us at `hey@slide.tech`.                                         |\n| `err_rate_limit_exceeded`    | Rate limit exceeded. Please wait before retrying the request. See [rate limiting](#description/rate-limiting) for more details.                         |\n\n<details>\n  <summary>Show more error codes.</summary>\n\n| Code                                | Description                                                                                                           |\n|-------------------------------------|-----------------------------------------------------------------------------------------------------------------------|\n| `err_agent_not_connected_to_device` | Agent is not connected to the device. Ensure the agent is powered on and has network connectivity.                    |\n| `err_device_not_connected_to_cloud` | Device is not connected to the cloud. Ensure the device is powered on and has network connectivity.                   |\n| `err_backup_already_running`        | A backup is already running for this agent. Please wait for the current backup to complete before starting a new one. |\n| `err_client_not_found`              | Client not found. Ensure the client ID is valid and the client exists.                                                |\n\n</details>\n\n## Eventual Consistency\n\nSlide operates an eventual consistency model, where data may not be immediately available after an operation.\nThis is due to the distributed nature of our system and the need for replication and synchronization across multiple\nsystems. Users should expect that operations may take a short period of time to propagate and become visible to all\ncomponents of the system.\n\n## Deprecations and Breaking Changes\n\n### Active Deprecations\n\n`Device.ip_addresses` and `Agent.ip_addresses` will be removed. They have been replaced by `Device.addresses` and `Agent.addresses` respectively.\n"
  title: Slide Accounts Restores (Virtual Machine) API
  version: 1.34.0
servers:
- url: https://api.slide.tech
security:
- BearerAuth: []
tags:
- description: Everything about [virtual machines](#model/virtualmachine)
  name: Restores (Virtual Machine)
paths:
  /v1/restore/virt:
    get:
      operationId: Virts
      parameters:
      - $ref: '#/components/parameters/QueryOffset'
      - $ref: '#/components/parameters/QueryLimit'
      - description: Sort by a specific field
        in: query
        name: sort_by
        schema:
          default: created
          enum:
          - created
          type: string
      - $ref: '#/components/parameters/QuerySortAsc'
      - $ref: '#/components/parameters/QueryCreatedAfter'
      - $ref: '#/components/parameters/QueryCreatedBefore'
      responses:
        '200':
          content:
            application/json:
              schema:
                description: Paginated response
                properties:
                  data:
                    description: List of virtual machines
                    items:
                      $ref: '#/components/schemas/VirtualMachine'
                    title: VirtualMachines
                    type: array
                  pagination:
                    $ref: '#/components/schemas/Pagination'
                required:
                - pagination
                - data
                title: Paginated response
                type: object
          description: OK
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '500':
          $ref: '#/components/responses/500'
      summary: List virtual machines
      tags:
      - Restores (Virtual Machine)
    post:
      operationId: VirtCreate
      requestBody:
        content:
          application/json:
            examples:
              basic:
                summary: Basic virtual machine
                value:
                  device_id: d_0123456789ab
                  network_type: network-nat-isolated
                  snapshot_id: s_0123456789ab
              basic_disaster:
                summary: Basic disaster virtual machine
                value:
                  device_id: d_0123456789ab
                  network_type: network-nat-isolated
                  purpose: disaster
                  snapshot_id: s_0123456789ab
              basic_with_passphrase:
                summary: Basic virtual machine with passphrase
                value:
                  device_id: d_0123456789ab
                  network_type: network-nat-isolated
                  passphrase: Super Secret Passphrase
                  snapshot_id: s_0123456789ab
              bind_to_network:
                summary: Virtual machine with network binding
                value:
                  device_id: d_0123456789ab
                  network_source: net_012345
                  network_type: network-id
                  snapshot_id: s_0123456789ab
            schema:
              properties:
                boot_mods:
                  $ref: '#/components/schemas/BootMods'
                cpu_count:
                  $ref: '#/components/schemas/CPUCount'
                device_id:
                  $ref: '#/components/schemas/DeviceID'
                disk_bus:
                  $ref: '#/components/schemas/DiskBus'
                force_boot_menu:
                  $ref: '#/components/schemas/ForceBootMenu'
                memory_in_mb:
                  $ref: '#/components/schemas/MemoryInMB'
                network_model:
                  $ref: '#/components/schemas/NetworkModel'
                network_source:
                  allOf:
                  - $ref: '#/components/schemas/NetworkID'
                  description: If network_type is `network-id`, this is the network to bind the VM to.
                network_type:
                  $ref: '#/components/schemas/NetworkType'
                passphrase:
                  $ref: '#/components/schemas/Passphrase'
                purpose:
                  $ref: '#/components/schemas/Purpose'
                snapshot_id:
                  $ref: '#/components/schemas/SnapshotID'
                vnc_enabled:
                  $ref: '#/components/schemas/VNCEnabled'
              required:
              - snapshot_id
              - device_id
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VirtualMachine'
          description: Created
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
      summary: Create virtual machine
      tags:
      - Restores (Virtual Machine)
  /v1/restore/virt/{virt_id}:
    delete:
      operationId: VirtDelete
      parameters:
      - $ref: '#/components/parameters/PathVirtID'
      responses:
        '204':
          description: No Content
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
      summary: Delete virtual machine
      tags:
      - Restores (Virtual Machine)
    get:
      operationId: VirtByID
      parameters:
      - $ref: '#/components/parameters/PathVirtID'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VirtualMachine'
          description: OK
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
      summary: Get virtual machine
      tags:
      - Restores (Virtual Machine)
    patch:
      operationId: VirtUpdate
      parameters:
      - $ref: '#/components/parameters/PathVirtID'
      requestBody:
        content:
          application/json:
            example: "{\n  \"state\": \"running\",\n  \"expires_at\": \"2024-08-23T01:25:08Z\",\n  \"memory_in_mb\": 4096,\n  \"cpu_count\": 2\n}"
            schema:
              properties:
                cpu_count:
                  $ref: '#/components/schemas/CPUCount'
                expires_at:
                  $ref: '#/components/schemas/ExpiresAt'
                force_boot_menu:
                  $ref: '#/components/schemas/ForceBootMenu'
                memory_in_mb:
                  $ref: '#/components/schemas/MemoryInMB'
                network_model:
                  $ref: '#/components/schemas/NetworkModel'
                network_source:
                  allOf:
                  - $ref: '#/components/schemas/NetworkID'
                  description: If network_type is `network-id`, this is the network to bind the VM to.
                network_type:
                  $ref: '#/components/schemas/NetworkType'
                purpose:
                  $ref: '#/components/schemas/Purpose'
                state:
                  $ref: '#/components/schemas/VirtualMachineState'
                vnc_enabled:
                  $ref: '#/components/schemas/VNCEnabled'
        required: true
      responses:
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VirtualMachine'
          description: Accepted
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
      summary: Update virtual machine
      tags:
      - Restores (Virtual Machine)
components:
  schemas:
    BootMods:
      description: Optional boot mods to enable on the restore
      items:
        enum:
        - passwordless_admin_user
        type: string
      type: array
    VNCEnabled:
      description: Whether VNC access is enabled
      example: false
      nullable: true
      type: boolean
    DeviceID:
      description: ID of a device
      example: d_0123456789ab
      pattern: ^d_[a-z0-9]{12}$
      type: string
    Passphrase:
      description: User passphrase. If the agent has a user passphrase, you must provide it here.
      example: Super Secret Passphrase
      minLength: 10
      type: string
    SnapshotID:
      description: ID of a snapshot
      example: s_0123456789ab
      pattern: ^s_[a-z0-9]{12}$
      type: string
    NetworkID:
      description: ID of an network
      example: net_012345
      pattern: ^net_[a-z0-9]{6}$
      type: string
    DiskBus:
      description: Disk bus of the virtual machine
      enum:
      - sata
      - virtio
      example: virtio
      type: string
    VirtualMachineState:
      description: State of the virtual machine
      enum:
      - running
      - stopped
      - paused
      example: running
      type: string
    ForceBootMenu:
      description: Whether to force the VM to boot to the menu
      example: false
      type: boolean
    Error:
      description: Error response object that represents an error that occurred during a request.
      properties:
        codes:
          description: List of error codes that occurred during a request.
          items:
            description: A unique error code that identifies the error.
            title: Code
            type: string
          title: Codes
          type: array
        details:
          description: List of error details that occurred during a request. This may contain action(s) that need to be taken before retrying the request.
          items:
            description: Short detail message describing the error.
            title: Detail
            type: string
          title: Details
          type: array
        message:
          description: Short message describing the error.
          title: Message
          type: string
      required:
      - codes
      - message
      - details
    CreatedAt:
      description: Creation timestamp
      example: '2024-08-23T01:25:08Z'
      format: date-time
      type: string
    NetworkType:
      description: Network type of the virtual machine. If this field is not present, the virtual machine does not have networking.
      enum:
      - network-none
      - network-nat-shared
      - network-nat-isolated
      - network-hostonly
      - bridge
      - network-id
      example: bridge
      type: string
    Purpose:
      description: Purpose for creating the virtual machine or file restore. If this is set to disaster, Slide Support will recieve a notification that you are in a disaster. File restores not created by the slide box for file system verification will have this field set to disaster.
      enum:
      - test
      - disaster
      example: disaster
      type: string
    ExpiresAt:
      description: Expiration timestamp
      example: '2024-08-23T01:25:08Z'
      format: date-time
      type: string
    VirtID:
      description: ID of a virtual machine
      example: virt_0123456789ab
      externalDocs:
        description: See our console documentation for more information on virtual machines
        url: https://docs.slide.tech/restores/#virtualization
      pattern: ^virt_[a-z0-9]{12}$
      type: string
    NetworkModel:
      description: Network model of the virtual machine
      enum:
      - hypervisor_default
      - e1000
      - rtl8139
      - virtio
      example: virtio
      type: string
    AgentID:
      description: ID of an agent
      example: a_0123456789ab
      pattern: ^a_[a-z0-9]{12}$
      type: string
    MemoryInMB:
      description: Memory in MB
      example: 4096
      format: uint32
      maximum: 131072
      minimum: 1024
      nullable: true
      type: integer
    CPUCount:
      description: Number of CPUs
      example: 2
      format: uint32
      maximum: 16
      minimum: 1
      nullable: true
      type: integer
    VirtualMachine:
      description: Virtual machine object that represents a virtual machine that has been created from a snapshot.
      properties:
        agent_id:
          $ref: '#/components/schemas/AgentID'
        cpu_count:
          $ref: '#/components/schemas/CPUCount'
        created_at:
          $ref: '#/components/schemas/CreatedAt'
        device_id:
          $ref: '#/components/schemas/DeviceID'
        disk_bus:
          $ref: '#/components/schemas/DiskBus'
        expires_at:
          $ref: '#/components/schemas/ExpiresAt'
        force_boot_menu:
          $ref: '#/components/schemas/ForceBootMenu'
        ip_address:
          description: IP address
          type: string
        mac_address:
          description: MAC address
          type: string
        memory_in_mb:
          $ref: '#/components/schemas/MemoryInMB'
        network_model:
          $ref: '#/components/schemas/NetworkModel'
        network_source:
          $ref: '#/components/schemas/NetworkID'
        network_type:
          $ref: '#/components/schemas/NetworkType'
        purpose:
          $ref: '#/components/schemas/Purpose'
        rdp_endpoint:
          description: RDP endpoint
          type: string
        snapshot_id:
          $ref: '#/components/schemas/SnapshotID'
        state:
          $ref: '#/components/schemas/VirtualMachineState'
        virt_id:
          $ref: '#/components/schemas/VirtID'
        vnc:
          description: List of VNC connection info
          items:
            $ref: '#/components/schemas/VNC'
          type: array
        vnc_enabled:
          $ref: '#/components/schemas/VNCEnabled'
        vnc_password:
          description: VNC password
          format: password
          type: string
      required:
      - virt_id
      - device_id
      - agent_id
      - snapshot_id
      - state
      - created_at
      - cpu_count
      - memory_in_mb
      - disk_bus
      - network_model
      - mac_address
      - vnc_enabled
      - vnc
      - vnc_password
      - purpose
      type: object
    VNC:
      description: VNC server object. Use this to connect to the virtual machine using a VNC client.
      properties:
        host:
          description: Host of the VNC server
          example: 192.168.1.53
          type: string
        port:
          description: Port of the VNC server
          example: 12345
          format: uint32
          type: integer
        type:
          $ref: '#/components/schemas/LocationType'
        websocket_uri:
          description: Websocket URI of the VNC server
          example: wss://example.com
          type: string
      required:
      - type
      type: object
    Pagination:
      properties:
        next_offset:
          description: Next offset to use for pagination. If this field is not present, that indicates there are no more items to fetch.
          example: 10
          format: uint32
          type: integer
      type: object
    LocationType:
      description: Type of the location
      enum:
      - local
      - cloud
      type: string
  parameters:
    QueryCreatedBefore:
      description: Filter results to before a specific creation timestamp (RFC3339 format)
      in: query
      name: created_before
      schema:
        format: date-time
        type: string
    QuerySortAsc:
      description: Sort in ascending order
      in: query
      name: sort_asc
      schema:
        default: false
        type: boolean
    PathVirtID:
      example: v_0123456789ab
      in: path
      name: virt_id
      required: true
      schema:
        $ref: '#/components/schemas/VirtID'
    QueryCreatedAfter:
      description: Filter results to after a specific creation timestamp (RFC3339 format)
      in: query
      name: created_after
      schema:
        format: date-time
        type: string
    QueryOffset:
      description: Starting index for pagination
      in: query
      name: offset
      schema:
        default: 0
        format: uint32
        minimum: 0
        type: integer
    QueryLimit:
      description: Number of items to return for pagination
      in: query
      name: limit
      schema:
        default: 10
        format: uint32
        maximum: 50
        minimum: 1
        type: integer
  responses:
    '400':
      content:
        application/json:
          examples:
            err_validation_error:
              summary: Validation error
              value:
                codes:
                - err_validation_error
                details:
                - 'parameter "device_id" in path has an error: string doesn''t match the regular expression "^d_[a-z0-9]{12}$"'
                message: bad request
          schema:
            $ref: '#/components/schemas/Error'
      description: Bad request
    '401':
      content:
        application/json:
          examples:
            err_missing_authentication:
              summary: Missing API token
              value:
                codes:
                - err_missing_authentication
                details:
                - 'You did not provide an API token. You need to provide your API token in the Authorization header, using Bearer auth (e.g. ''Authorization: Bearer YOUR_SECRET_TOKEN'').'
                message: unauthorized
            err_unauthorized:
              summary: Invalid API token
              value:
                codes:
                - err_unauthorized
                details:
                - Invalid API token provided or you do not have permission to access this resource.
                message: unauthorized
          schema:
            $ref: '#/components/schemas/Error'
      description: Unauthorized
    '500':
      content:
        application/json:
          examples:
            err_internal_server_error:
              summary: Internal server error
              value:
                codes:
                - err_internal_server_error
                details:
                - Something went wrong processing your request. See https://docs.slide.tech/api/#description/errors for more information.
                message: internal server error
          schema:
            $ref: '#/components/schemas/Error'
      description: Internal server error
    '404':
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: Not found
  securitySchemes:
    BearerAuth:
      bearerFormat: string
      scheme: bearer
      type: http