openapi: 3.1.0
info:
  title: Spiceworks Cloud Apps Comments Devices API
  description: The Spiceworks Cloud Apps API provides a JavaScript SDK for building integrated applications within the Spiceworks IT management platform. The API exposes Help Desk ticketing data, device inventory, and user information to embedded cloud apps. Applications are embedded within the Spiceworks UI and communicate with the platform through the spiceworks-sdk JavaScript library using a postMessage-based bridge. The API uses OAuth 2.0 authentication and provides access to tickets, comments, devices, and user profiles for IT professionals and app developers.
  version: '1.0'
  contact:
    name: Spiceworks Developer Community
    url: https://community.spiceworks.com/
  termsOfService: https://community.spiceworks.com/legal/terms
servers:
- url: https://community.spiceworks.com
  description: Spiceworks Community Platform
security:
- oauth2:
  - helpdesk
  - inventory
  - users
tags:
- name: Devices
  description: Device inventory operations for accessing information about managed IT devices including computers, servers, and network equipment
paths:
  /api/v1/devices:
    get:
      operationId: listDevices
      summary: List Inventory Devices
      description: Retrieves a paginated list of managed IT devices from the Spiceworks inventory. Devices include workstations, servers, network equipment, and other managed assets. Results can be filtered by device type, operating system, and other attributes.
      tags:
      - Devices
      parameters:
      - name: type
        in: query
        description: Filter by device type
        schema:
          type: string
          enum:
          - workstation
          - server
          - network
          - printer
          - mobile
      - name: page
        in: query
        description: Page number for pagination
        schema:
          type: integer
          default: 1
      - name: per_page
        in: query
        description: Number of devices per page
        schema:
          type: integer
          default: 25
          maximum: 100
      responses:
        '200':
          description: List of devices retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  devices:
                    type: array
                    items:
                      $ref: '#/components/schemas/Device'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
  /api/v1/devices/{id}:
    get:
      operationId: getDevice
      summary: Get Inventory Device
      description: Retrieves the full details of a specific managed device by its ID, including hardware specifications, software inventory, operating system, network configuration, and warranty information.
      tags:
      - Devices
      parameters:
      - name: id
        in: path
        required: true
        description: The unique identifier of the device
        schema:
          type: integer
      responses:
        '200':
          description: Device details retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  device:
                    $ref: '#/components/schemas/DeviceDetail'
        '404':
          description: Device not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    PaginationMeta:
      type: object
      description: Pagination metadata for list responses
      properties:
        current_page:
          type: integer
          description: Current page number
        total_pages:
          type: integer
          description: Total number of pages
        total_count:
          type: integer
          description: Total number of items
        per_page:
          type: integer
          description: Items per page
    Error:
      type: object
      description: API error response
      properties:
        error:
          type: string
          description: Error message
        details:
          type: array
          items:
            type: string
          description: Additional error details
    Device:
      type: object
      description: A managed IT device in the Spiceworks inventory
      properties:
        id:
          type: integer
          description: Unique device identifier
        name:
          type: string
          description: Device hostname or display name
        type:
          type: string
          description: Device type classification
          enum:
          - workstation
          - server
          - network
          - printer
          - mobile
          - unknown
        manufacturer:
          type: string
          description: Device manufacturer name
        model:
          type: string
          description: Device model name
        serial_number:
          type: string
          description: Device serial number
        ip_address:
          type: string
          description: Primary IP address of the device
        mac_address:
          type: string
          description: Primary MAC address of the device
        os_name:
          type: string
          description: Operating system name
        os_version:
          type: string
          description: Operating system version
        last_seen_at:
          type: string
          format: date-time
          description: Timestamp when the device was last detected on the network
    DeviceDetail:
      allOf:
      - $ref: '#/components/schemas/Device'
      - type: object
        properties:
          cpu:
            type: string
            description: CPU model and speed
          ram_mb:
            type: integer
            description: Total RAM in megabytes
          disk_gb:
            type: number
            description: Total disk capacity in gigabytes
          software:
            type: array
            items:
              type: object
              properties:
                name:
                  type: string
                version:
                  type: string
            description: List of installed software applications
          warranty_expiry:
            type: string
            format: date
            description: Device warranty expiration date
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth 2.0 authentication via the Spiceworks Cloud Apps platform. Applications receive an implicit grant token through the JS SDK postMessage bridge when running inside the Spiceworks UI.
      flows:
        implicit:
          authorizationUrl: https://community.spiceworks.com/oauth/authorize
          scopes:
            helpdesk: Access Help Desk tickets and comments
            inventory: Access device inventory data
            users: Access user profile data
externalDocs:
  description: Spiceworks Cloud Apps Developer Documentation
  url: https://spiceworks.github.io/developers.spiceworks.com/documentation/cloud-apps/