Nexthink device-deletions API

openapi: 3.0.1
info:
  title: Campaigns device-deletions API
  version: 1.0.0
servers:
- url: https://{instance}.api.{region}.nexthink.cloud
  description: Nexthink Infinity instance API host
  variables:
    instance:
      default: instance
      description: Your Nexthink instance name
    region:
      default: us
      enum:
      - us
      - eu
      - pac
      - meta
      description: Nexthink cloud region
security:
- bearerAuth: []
tags:
- name: device-deletions
paths:
  /api/v1/data-management/device/deletions:
    post:
      tags:
      - device-deletions
      summary: Schedule device deletions
      description: 'Schedule the deletion of one or more devices from the Nexthink inventory.


        Each device must be identified by both its `uid` and `name`. Devices with malformed

        UIDs are rejected individually with status `INVALID` without failing the rest of the

        batch.


        The operation is asynchronous: the API returns `202 Accepted` once the deletions are

        queued. Actual removal from the inventory happens in the background.

        '
      operationId: deleteDevices
      parameters:
      - name: x-request-id
        in: header
        required: false
        description: Optional client-supplied correlation identifier (UUID). Echoed back in the response `x-request-id` header. If omitted, the server generates one.
        schema:
          type: string
          format: uuid
      requestBody:
        description: The batch of devices to delete.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeviceDeletionRequest'
      responses:
        '202':
          description: Deletion batch accepted and queued. Check each device's `status` field — a `202` response does not guarantee all devices were successfully scheduled.
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeviceDeletionResponse'
        '400':
          description: The request payload is invalid and was not accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized — the bearer token is missing or invalid.
        '403':
          description: Forbidden — the Data Management is not enabled for this tenant.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error. Include the `x-request-id` response header value when contacting Nexthink support.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    DeviceEntry:
      description: Identifies a single device for deletion.
      type: object
      required:
      - uid
      - name
      properties:
        uid:
          description: UID of the device as reported by the Nexthink Collector. Must be a valid UUID. A malformed value results in a per-device `INVALID` status rather than failing the whole batch.
          type: string
          format: uuid
        name:
          description: Name of the device as reported by the Nexthink Collector. Must not be blank.
          type: string
          minLength: 1
    ErrorResponse:
      description: Error details returned with 4xx and 5xx responses.
      type: object
      properties:
        code:
          description: Stable machine-readable error code identifying the failure reason.
          type: string
          enum:
          - EMPTY_REQUEST
          - BATCH_SIZE_EXCEEDED
          - INVALID_REQUEST
          - EMPTY_TENANT
          - FEATURE_NOT_ENABLED
          - INTERNAL_ERROR
        message:
          description: Human-readable description of the error.
          type: string
    DeviceDeletionRequest:
      description: Batch of devices to be deleted from the Nexthink inventory.
      type: object
      required:
      - devices
      properties:
        devices:
          description: Non-empty list of devices to delete. The maximum number of devices per request is 100 (configurable per deployment). Split larger deletions into multiple requests.
          type: array
          minItems: 1
          maxItems: 100
          items:
            $ref: '#/components/schemas/DeviceEntry'
    DeviceStatus:
      description: Scheduling outcome for a single device.
      type: object
      properties:
        uid:
          description: UID of the device as submitted.
          type: string
        name:
          description: Name of the device as submitted.
          type: string
        status:
          description: 'Per-device outcome:

            - `SCHEDULED` — deletion queued successfully.

            - `INVALID` — the UID is malformed; the device was skipped. The rest of the batch proceeds.

            - `FAILED` — a downstream error prevented this device from being scheduled.

            '
          type: string
          enum:
          - SCHEDULED
          - INVALID
          - FAILED
    DeviceDeletionResponse:
      description: Scheduling result for the deletion batch.
      type: object
      properties:
        scheduledCount:
          description: Number of devices successfully queued for deletion.
          type: integer
          format: int32
        status:
          description: Overall batch status. Always `ACCEPTED` for a `202` response.
          type: string
          enum:
          - ACCEPTED
        devices:
          description: Per-device scheduling outcome, in the same order as the request.
          type: array
          items:
            $ref: '#/components/schemas/DeviceStatus'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: jwt
x-apievangelist-source: https://docs.nexthink.com/api/llms.txt
x-apievangelist-method: searched
x-apievangelist-generated: '2026-07-20'