openapi: 3.1.0
info:
  title: Spiceworks Cloud Apps 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
externalDocs:
  description: Spiceworks Cloud Apps Developer Documentation
  url: https://spiceworks.github.io/developers.spiceworks.com/documentation/cloud-apps/
servers:
  - url: https://community.spiceworks.com
    description: Spiceworks Community Platform
tags:
  - name: Tickets
    description: >-
      Help Desk ticket management operations for creating, reading, updating,
      and listing support tickets within the Spiceworks IT management platform
  - name: Comments
    description: >-
      Ticket comment operations for adding and retrieving comments on Help Desk
      support tickets
  - name: Devices
    description: >-
      Device inventory operations for accessing information about managed IT
      devices including computers, servers, and network equipment
  - name: Users
    description: >-
      User management operations for accessing Spiceworks user and technician
      profiles
paths:
  /api/v1/tickets:
    get:
      operationId: listTickets
      summary: List Help Desk Tickets
      description: >-
        Retrieves a paginated list of Help Desk tickets from the Spiceworks
        platform. Results can be filtered by status, assignee, and other
        ticket attributes. Returns ticket summaries including ID, summary,
        status, priority, assignee, and timestamps.
      tags:
        - Tickets
      parameters:
        - name: status
          in: query
          description: Filter tickets by status
          schema:
            type: string
            enum: [open, closed, in_progress]
        - name: assigned_to
          in: query
          description: Filter by assigned technician ID
          schema:
            type: integer
        - name: page
          in: query
          description: Page number for pagination
          schema:
            type: integer
            default: 1
        - name: per_page
          in: query
          description: Number of tickets per page
          schema:
            type: integer
            default: 25
            maximum: 100
      responses:
        '200':
          description: List of tickets retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  tickets:
                    type: array
                    items:
                      $ref: '#/components/schemas/Ticket'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
    post:
      operationId: createTicket
      summary: Create Help Desk Ticket
      description: >-
        Creates a new Help Desk ticket in the Spiceworks platform. The ticket
        is associated with the authenticated user's Spiceworks account. Required
        fields include summary and optionally a description, priority level,
        and assignee.
      tags:
        - Tickets
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TicketCreate'
      responses:
        '201':
          description: Ticket created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  ticket:
                    $ref: '#/components/schemas/Ticket'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/tickets/{id}:
    get:
      operationId: getTicket
      summary: Get Help Desk Ticket
      description: >-
        Retrieves the full details of a specific Help Desk ticket by its ID,
        including summary, description, status, priority, assignee, creator,
        and all associated comments and attachments.
      tags:
        - Tickets
      parameters:
        - name: id
          in: path
          required: true
          description: The unique identifier of the ticket
          schema:
            type: integer
      responses:
        '200':
          description: Ticket details retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  ticket:
                    $ref: '#/components/schemas/TicketDetail'
        '404':
          description: Ticket not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      operationId: updateTicket
      summary: Update Help Desk Ticket
      description: >-
        Updates an existing Help Desk ticket. Allows changing status, priority,
        assignee, summary, description, and other ticket attributes. Only
        fields included in the request body are updated.
      tags:
        - Tickets
      parameters:
        - name: id
          in: path
          required: true
          description: The unique identifier of the ticket
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TicketUpdate'
      responses:
        '200':
          description: Ticket updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  ticket:
                    $ref: '#/components/schemas/Ticket'
        '404':
          description: Ticket not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/tickets/{ticket_id}/comments:
    get:
      operationId: listTicketComments
      summary: List Ticket Comments
      description: >-
        Retrieves all comments associated with a specific Help Desk ticket.
        Comments include the body text, the author, creation timestamp, and
        whether the comment is public or internal (technician-only).
      tags:
        - Comments
      parameters:
        - name: ticket_id
          in: path
          required: true
          description: The unique identifier of the ticket
          schema:
            type: integer
      responses:
        '200':
          description: Comments retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  comments:
                    type: array
                    items:
                      $ref: '#/components/schemas/Comment'
        '404':
          description: Ticket not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      operationId: createTicketComment
      summary: Add Ticket Comment
      description: >-
        Adds a new comment to an existing Help Desk ticket. Comments can be
        public (visible to the ticket requester) or internal (visible only
        to technicians). Supports plain text and basic HTML formatting.
      tags:
        - Comments
      parameters:
        - name: ticket_id
          in: path
          required: true
          description: The unique identifier of the ticket
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CommentCreate'
      responses:
        '201':
          description: Comment added successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  comment:
                    $ref: '#/components/schemas/Comment'
        '404':
          description: Ticket not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /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'
  /api/v1/users:
    get:
      operationId: listUsers
      summary: List Platform Users
      description: >-
        Retrieves a list of Spiceworks users and technicians associated with
        the account. Includes basic profile information such as name, email,
        role, and department.
      tags:
        - Users
      parameters:
        - name: role
          in: query
          description: Filter by user role
          schema:
            type: string
            enum: [admin, technician, user]
        - name: page
          in: query
          description: Page number for pagination
          schema:
            type: integer
            default: 1
      responses:
        '200':
          description: List of users retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  users:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
                  meta:
                    $ref: '#/components/schemas/PaginationMeta'
  /api/v1/users/{id}:
    get:
      operationId: getUser
      summary: Get Platform User
      description: >-
        Retrieves profile details for a specific Spiceworks user including
        name, email, role, department, phone, and avatar information.
      tags:
        - Users
      parameters:
        - name: id
          in: path
          required: true
          description: The unique identifier of the user
          schema:
            type: integer
      responses:
        '200':
          description: User details retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  user:
                    $ref: '#/components/schemas/User'
        '404':
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  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
  schemas:
    Ticket:
      type: object
      description: A Spiceworks Help Desk support ticket
      properties:
        id:
          type: integer
          description: Unique ticket identifier
        summary:
          type: string
          description: Brief description of the ticket issue
        status:
          type: string
          description: Current ticket status
          enum: [open, in_progress, closed]
        priority:
          type: string
          description: Ticket priority level
          enum: [low, medium, high, urgent]
        assignee:
          $ref: '#/components/schemas/UserRef'
        creator:
          $ref: '#/components/schemas/UserRef'
        created_at:
          type: string
          format: date-time
          description: Timestamp when the ticket was created
        updated_at:
          type: string
          format: date-time
          description: Timestamp when the ticket was last updated
        due_date:
          type: string
          format: date
          description: Optional due date for the ticket
    TicketDetail:
      allOf:
        - $ref: '#/components/schemas/Ticket'
        - type: object
          properties:
            description:
              type: string
              description: Full description of the ticket issue
            comments:
              type: array
              items:
                $ref: '#/components/schemas/Comment'
            tags:
              type: array
              items:
                type: string
              description: Tags associated with the ticket
    TicketCreate:
      type: object
      required:
        - summary
      properties:
        summary:
          type: string
          description: Brief description of the issue
          maxLength: 255
        description:
          type: string
          description: Detailed description of the issue
        priority:
          type: string
          enum: [low, medium, high, urgent]
          default: medium
        assignee_id:
          type: integer
          description: ID of the technician to assign the ticket to
        due_date:
          type: string
          format: date
          description: Optional due date for resolution
    TicketUpdate:
      type: object
      properties:
        summary:
          type: string
          description: Updated brief description
          maxLength: 255
        description:
          type: string
          description: Updated detailed description
        status:
          type: string
          enum: [open, in_progress, closed]
        priority:
          type: string
          enum: [low, medium, high, urgent]
        assignee_id:
          type: integer
          description: ID of the technician to assign the ticket to
    Comment:
      type: object
      description: A comment on a Help Desk ticket
      properties:
        id:
          type: integer
          description: Unique comment identifier
        body:
          type: string
          description: The comment text content
        is_public:
          type: boolean
          description: >-
            Whether the comment is visible to the ticket requester (true)
            or internal to technicians only (false)
        author:
          $ref: '#/components/schemas/UserRef'
        created_at:
          type: string
          format: date-time
          description: Timestamp when the comment was created
    CommentCreate:
      type: object
      required:
        - body
      properties:
        body:
          type: string
          description: The comment text content
        is_public:
          type: boolean
          description: Whether the comment is visible to the requester
          default: true
    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
    User:
      type: object
      description: A Spiceworks platform user or technician
      properties:
        id:
          type: integer
          description: Unique user identifier
        first_name:
          type: string
          description: User first name
        last_name:
          type: string
          description: User last name
        email:
          type: string
          format: email
          description: User email address
        role:
          type: string
          description: User role in the platform
          enum: [admin, technician, user]
        department:
          type: string
          description: User department
        phone:
          type: string
          description: User phone number
        avatar_url:
          type: string
          format: uri
          description: URL to the user avatar image
    UserRef:
      type: object
      description: A brief reference to a Spiceworks user
      properties:
        id:
          type: integer
          description: Unique user identifier
        first_name:
          type: string
          description: User first name
        last_name:
          type: string
          description: User last name
        email:
          type: string
          format: email
          description: User email address
    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
security:
  - oauth2:
      - helpdesk
      - inventory
      - users