Slide Devices API

openapi: 3.2.0
info:
  contact:
    email: hey@slide.tech
    name: Slide Team
    url: https://docs.slide.tech
  description: '## Introduction

    The Slide API is organized around REST.'
  title: Slide Devices API
  version: 1.34.0
servers:
- url: https://api.slide.tech
security:
- BearerAuth: []
tags:
- description: Everything about devices
  name: Devices
paths:
  /v1/device:
    get:
      operationId: Devices
      parameters:
      - $ref: '#/components/parameters/QueryOffset'
      - $ref: '#/components/parameters/QueryLimit'
      - description: Sort by a specific field
        in: query
        name: sort_by
        schema:
          default: hostname
          enum:
          - hostname
          type: string
      - $ref: '#/components/parameters/QuerySortAsc'
      - $ref: '#/components/parameters/QueryClientID'
      - $ref: '#/components/parameters/QueryCreatedAfter'
      - $ref: '#/components/parameters/QueryCreatedBefore'
      responses:
        '200':
          content:
            application/json:
              schema:
                description: Paginated response
                properties:
                  data:
                    description: List of devices
                    items:
                      $ref: '#/components/schemas/Device'
                    title: Devices
                    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 devices
      tags:
      - Devices
  /v1/device/{device_id}:
    get:
      operationId: DeviceByID
      parameters:
      - $ref: '#/components/parameters/PathDeviceID'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Device'
          description: OK
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
      summary: Get device
      tags:
      - Devices
    patch:
      operationId: DeviceUpdate
      parameters:
      - $ref: '#/components/parameters/PathDeviceID'
      requestBody:
        content:
          application/json:
            example: "{\n  \"display_name\": \"<change me or remove the field to keep unchanged>\",\n  \"hostname\": \"<change me or remove the field to keep unchanged>\",\n  \"client_id\": \"<change me or remove the field to keep unchanged>\"\n}"
            schema:
              properties:
                client_id:
                  $ref: '#/components/schemas/ClientIDOrEmpty'
                display_name:
                  $ref: '#/components/schemas/DisplayName'
                hostname:
                  $ref: '#/components/schemas/Hostname'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Device'
          description: OK
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
      summary: Update device
      tags:
      - Devices
  /v1/device/{device_id}/network:
    get:
      description: Get the current network configuration for a device.
      operationId: DeviceNetworkGet
      parameters:
      - $ref: '#/components/parameters/PathDeviceID'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceNetwork'
          description: OK
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
      summary: Get device network configuration
      tags:
      - Devices
    patch:
      description: Update the network configuration for a device. The configuration is tested after it is applied, and rolled back if invalid.
      operationId: DeviceNetworkUpdate
      parameters:
      - $ref: '#/components/parameters/PathDeviceID'
      requestBody:
        content:
          application/json:
            example: "{\n  \"network_mode\": \"static\",\n  \"network_address\": \"192.168.1.100/24\",\n  \"network_gateway\": \"192.168.1.1\",\n  \"dns_server_primary\": \"1.1.1.1\",\n  \"dns_server_secondary\": \"8.8.8.8\"\n}"
            schema:
              $ref: '#/components/schemas/DeviceNetworkUpdate'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceNetwork'
          description: OK
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
      summary: Update device network configuration
      tags:
      - Devices
  /v1/device/{device_id}/shutdown/poweroff:
    post:
      description: Requests a device to power off.
      operationId: DevicePowerOff
      parameters:
      - description: The ID of the device to power off.
        in: path
        name: device_id
        required: true
        schema:
          type: string
      requestBody:
        content: {}
      responses:
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Device'
          description: Accepted
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
      summary: Power off a device
      tags:
      - Devices
  /v1/device/{device_id}/shutdown/reboot:
    post:
      description: Requests a device to reboot.
      operationId: DeviceReboot
      parameters:
      - description: The ID of the device to reboot.
        in: path
        name: device_id
        required: true
        schema:
          type: string
      requestBody:
        content: {}
      responses:
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Device'
          description: Accepted
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
      summary: Reboot a device
      tags:
      - Devices
  /v1/device/{device_id}/vlan:
    get:
      description: List all virtual interfaces (VLANs) for a device.
      operationId: DeviceVLANList
      parameters:
      - $ref: '#/components/parameters/PathDeviceID'
      responses:
        '200':
          content:
            application/json:
              schema:
                description: List of device VLANs
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/DeviceVLAN'
                    type: array
                required:
                - data
                title: DeviceVLANs
                type: object
          description: OK
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
      summary: List device VLANs
      tags:
      - Devices
    post:
      description: Create a new virtual interface (VLAN) for a device.
      operationId: DeviceVLANCreate
      parameters:
      - $ref: '#/components/parameters/PathDeviceID'
      requestBody:
        content:
          application/json:
            example: "{\n  \"vlan_tag\": 100,\n  \"name\": \"vlan100\",\n  \"network_mode\": \"static\",\n  \"ip_address\": \"192.168.100.1/24\",\n  \"gateway\": \"192.168.100.1\"\n}"
            schema:
              $ref: '#/components/schemas/DeviceVLANCreate'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceVLAN'
          description: Created
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
      summary: Create device VLAN
      tags:
      - Devices
  /v1/device/{device_id}/vlan/{vlan_id}:
    delete:
      description: Delete a virtual interface (VLAN) for a device.
      operationId: DeviceVLANDelete
      parameters:
      - $ref: '#/components/parameters/PathDeviceID'
      - $ref: '#/components/parameters/PathVLANID'
      responses:
        '204':
          description: No Content
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '409':
          $ref: '#/components/responses/409'
        '500':
          $ref: '#/components/responses/500'
      summary: Delete device VLAN
      tags:
      - Devices
    get:
      description: Get a specific virtual interface (VLAN) for a device.
      operationId: DeviceVLANGet
      parameters:
      - $ref: '#/components/parameters/PathDeviceID'
      - $ref: '#/components/parameters/PathVLANID'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceVLAN'
          description: OK
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
      summary: Get device VLAN
      tags:
      - Devices
    patch:
      description: Update a virtual interface (VLAN) for a device.
      operationId: DeviceVLANUpdate
      parameters:
      - $ref: '#/components/parameters/PathDeviceID'
      - $ref: '#/components/parameters/PathVLANID'
      requestBody:
        content:
          application/json:
            example: "{\n  \"vlan_tag\": 100,\n  \"name\": \"vlan100-updated\",\n  \"network_mode\": \"static\",\n  \"ip_address\": \"192.168.100.2/24\",\n  \"gateway\": \"192.168.100.1\"\n}"
            schema:
              $ref: '#/components/schemas/DeviceVLANUpdate'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceVLAN'
          description: OK
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
      summary: Update device VLAN
      tags:
      - Devices
components:
  schemas:
    ClientIDOrEmpty:
      description: ID of a client or an empty string
      example: c_0123456789ab
      pattern: ^(c_[a-z0-9]{12}|)$
      type: string
    DeviceNetworkUpdate:
      description: Device network configuration update
      properties:
        dns_server_primary:
          $ref: '#/components/schemas/DNSServerPrimary'
        dns_server_secondary:
          $ref: '#/components/schemas/DNSServerSecondary'
        network_address:
          $ref: '#/components/schemas/DeviceNetworkAddress'
        network_gateway:
          $ref: '#/components/schemas/DeviceNetworkGateway'
        network_mode:
          $ref: '#/components/schemas/NetworkMode'
      type: object
    DeviceNetworkAddress:
      description: IP address and network mask in CIDR notation (e.g., "192.168.1.100/24"). Required when network_mode is "static".
      example: 192.168.1.100/24
      type: string
    Hostname:
      description: Hostname of the system
      example: my-hostname-1
      maxLength: 63
      minLength: 1
      pattern: ^[a-zA-Z0-9][a-zA-Z0-9-]{0,62}$
      type: string
    DNSServerPrimary:
      description: Primary DNS server IP address. Required when network_mode is "static".
      example: 1.1.1.1
      format: ipv4
      type: string
    DeviceVLANCreate:
      description: Device virtual interface (VLAN) creation request
      properties:
        gateway:
          $ref: '#/components/schemas/VLANGateway'
        ip_address:
          $ref: '#/components/schemas/VLANIPAddress'
        name:
          $ref: '#/components/schemas/VLANName'
        network_mode:
          $ref: '#/components/schemas/NetworkMode'
        network_update_pending:
          description: Returned in response only, to indicate that the network update is in progress.
          example: false
          type: boolean
        vlan_tag:
          $ref: '#/components/schemas/VLANTag'
      required:
      - name
      - vlan_tag
      - network_mode
      type: object
    DeviceVLAN:
      description: Device virtual interface (VLAN) configuration
      properties:
        gateway:
          $ref: '#/components/schemas/VLANGateway'
        ip_address:
          $ref: '#/components/schemas/VLANIPAddress'
        name:
          $ref: '#/components/schemas/VLANName'
        network_mode:
          $ref: '#/components/schemas/NetworkMode'
        network_update_pending:
          description: Returned in response only, to indicate that the network update is in progress.
          example: false
          type: boolean
        vlan_id:
          description: Unique identifier for the VLAN
          example: vlan_012345
          type: string
        vlan_tag:
          $ref: '#/components/schemas/VLANTag'
      required:
      - vlan_id
      - name
      - vlan_tag
      - network_mode
      type: object
    DeviceVLANUpdate:
      description: Device virtual interface (VLAN) update request
      properties:
        gateway:
          $ref: '#/components/schemas/VLANGateway'
        ip_address:
          $ref: '#/components/schemas/VLANIPAddress'
        name:
          $ref: '#/components/schemas/VLANName'
        network_mode:
          $ref: '#/components/schemas/NetworkMode'
        network_update_pending:
          description: Returned in response only, to indicate that the network update is in progress.
          example: false
          type: boolean
        vlan_tag:
          $ref: '#/components/schemas/VLANTag'
      type: object
    VLANIPAddress:
      description: IP address and network mask in CIDR notation (e.g., "192.168.100.1/24"). Required when network_mode is "static".
      example: 192.168.100.1/24
      type: string
    DisplayName:
      description: Customizable display name
      example: My First Device
      maxLength: 128
      type: string
    VLANTag:
      description: 802.1Q VLAN tag (1-4094)
      example: 100
      format: uint32
      maximum: 4094
      minimum: 1
      type: integer
    LastSeenAt:
      description: Last seen timestamp
      example: '2024-08-23T01:25:08Z'
      format: date-time
      type: string
    DeviceNetworkGateway:
      description: Gateway IP address. Required when network_mode is "static".
      example: 192.168.1.1
      format: ipv4
      type: string
    ClientID:
      description: ID of a client
      example: c_0123456789ab
      pattern: ^c_[a-z0-9]{12}$
      type: string
    DeviceNetwork:
      description: Device network configuration
      properties:
        dns_server_primary:
          $ref: '#/components/schemas/DNSServerPrimary'
        dns_server_secondary:
          $ref: '#/components/schemas/DNSServerSecondary'
        network_address:
          $ref: '#/components/schemas/DeviceNetworkAddress'
        network_gateway:
          $ref: '#/components/schemas/DeviceNetworkGateway'
        network_mode:
          $ref: '#/components/schemas/NetworkMode'
        network_update_pending:
          description: Returned in response only, to indicate that the network update is in progress.
          example: false
          type: boolean
      required:
      - network_mode
      type: object
    VLANGateway:
      description: Gateway IP address. Required when network_mode is "static".
      example: 192.168.100.1
      format: ipv4
      type: string
    NetworkAddress:
      properties:
        ips:
          items:
            description: The IP addresses associated with the MAC address.
            example: 192.168.1.104
            title: IP Address
            type: string
          type: array
        mac:
          description: MAC address of the network interface.
          example: 62:bb:d3:0d:db:7d
          type: string
      required:
      - mac
      - ips
      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
    VLANName:
      description: Display name for the virtual interface
      example: vlan100
      maxLength: 32
      minLength: 1
      type: string
    IPAddresses:
      deprecated: true
      description: This field is deprecated and will be removed in the future.
      items:
        example: 192.168.3.53
        format: ipv4
        type: string
      type: array
    BootedAt:
      description: Boot timestamp
      example: '2024-08-23T01:25:08Z'
      format: date-time
      type: string
    DeviceID:
      description: ID of a device
      example: d_0123456789ab
      pattern: ^d_[a-z0-9]{12}$
      type: string
    NetworkAddresses:
      description: List of network addresses
      items:
        $ref: '#/components/schemas/NetworkAddress'
      type: array
    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
    NetworkMode:
      description: Network mode (DHCP or static IP)
      enum:
      - dhcp
      - static
      example: static
      type: string
    DNSServerSecondary:
      description: Secondary DNS server IP address. Optional when network_mode is "static".
      example: 8.8.8.8
      format: ipv4
      type: string
    Device:
      description: Device object that represents a Slide Box.
      properties:
        addresses:
          $ref: '#/components/schemas/NetworkAddresses'
        booted_at:
          $ref: '#/components/schemas/BootedAt'
        client_id:
          $ref: '#/components/schemas/ClientID'
        device_id:
          $ref: '#/components/schemas/DeviceID'
        device_warranty_expiration_date:
          description: Warranty expiration date of the device
          example: '2029-08-23T01:25:08Z'
          format: date-time
          type: string
        display_name:
          $ref: '#/components/schemas/DisplayName'
        hardware_model_name:
          description: Hardware model name of the device
          example: Slide Z1, 1 TB
          type: string
        hostname:
          $ref: '#/components/schemas/Hostname'
        image_version:
          description: Version of the device image
          example: 1.0.0
          type: string
        ip_addresses:
          $ref: '#/components/schemas/IPAddresses'
        last_seen_at:
          $ref: '#/components/schemas/LastSeenAt'
        network_update_pending:
          description: Whether the device has a network update pending
          example: false
          type: boolean
        nfr:
          description: Whether the device is an NFR device
          example: false
          type: boolean
        package_version:
          description: Version of the Slide package
          example: 1.2.3
          type: string
        public_ip_address:
          description: Public IP address of the device
          example: 74.83.124.111
          format: ipv4
          type: string
        serial_number:
          description: Serial number of the device
          example: SN123456
          type: string
        service_model_name:
          description: Service model name of the device
          example: Slide Z1 Subscription, 1 TB, 1 Year Cloud Retention
          type: string
        service_model_name_short:
          description: Short service model name of the device
          example: 1 Year Cloud Retention
          type: string
        service_status:
          description: Status of the service
          enum:
          - pending_activation
          - active
          - canceled
          example: active
          type: string
        storage_total_bytes:
          description: Total storage in bytes
          example: 1099511627776
          format: uint64
          type: integer
        storage_used_bytes:
          description: Used storage in bytes
          example: 274877906944
          format: uint64
          type: integer
        total_agent_included_volume_used_bytes:
          description: Amount of data currently on the device's Protected Systems
          example: 274877906944
          format: uint64
          type: integer
      required:
      - device_id
      - display_name
      - last_seen_at
      - hostname
      - ip_addresses
      - addresses
      - public_ip_address
      - image_version
      - package_version
      - storage_used_bytes
      - storage_total_bytes
      - total_agent_included_volume_used_bytes
      - serial_number
      - hardware_model_name
      - device_warranty_expiration_date
      - service_model_name
      - service_model_name_short
      - service_status
      - nfr
      type: object
  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
    QueryCreatedAfter:
      description: Filter results to after a specific creation timestamp (RFC3339 format)
      in: query
      name: created_after
      schema:
        format: date-time
        type: string
    PathVLANID:
      example: vlan_012345
      in: path
      name: vlan_id
      required: true
      schema:
        description: The ID of the VLAN
        type: string
    QueryLimit:
      description: Number of items to return for pagination
      in: query
      name: limit
      schema:
        default: 10
        format: uint32
        maximum: 50
        minimum: 1
        type: integer
    QueryOffset:
      description: Starting index for pagination
      in: query
      name: offset
      schema:
        default: 0
        format: uint32
        minimum: 0
        type: integer
    QueryClientID:
      in: query
      name: client_id
      schema:
        $ref: '#/components/schemas/ClientID'
    PathDeviceID:
      example: d_0123456789ab
      in: path
      name: device_id
      required: true
      schema:
        $ref: '#/components/schemas/DeviceID'
  responses:
    '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
    '409':
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
      description: Conflict
    '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
  securitySchemes:
    BearerAuth:
      bearerFormat: string
      scheme: bearer
      type: http