Iru Devices API

openapi: 3.2.0
info:
  title: Iru Endpoint Management Devices API
  description: "# Welcome to the Iru Endpoint Management API Documentation\n\n**Note:** Kandji is in the process of changing to Iru. Many URLs and notes within this documentation will continue to reference Kandji for some time.\n\nYou can find your API URL in Settings > Access. The API URL will follow the below formats.\n\n- US - `https://SubDomain.api.kandji.io`\n    \n- EU - `https://SubDomain.api.eu.kandji.io`\n    \n\nFor information on how to obtain an API token, please refer to the Iru docs.\n\n[https://docs.iru.com/](https://docs.iru.com/)\n\n#### Rate Limit\n\nThe Iru Endpoint Management API currently has an API rate limit of 10,000 requests per hour per customer.\n\n#### Request Methods\n\nHTTP request methods supported by the API.\n\n| Method | Definition |\n| --- | --- |\n| GET | The `GET` method requests a representation of the specified resource. |\n| POST | The `POST` method submits an entity to the specified resource. |\n| PATCH | The `PATCH` method applies partial modifications to a resource. |\n| DELETE | The `DELETE` method deletes the specified resource. |\n\n#### Response codes\n\nNot all response codes apply to every endpoint.\n\n| Code | Response |\n| --- | --- |\n| 200 | OK |\n| 201 | Created |\n| 204 | No content |\n|  | Typical response when sending the DELETE method. |\n| 400 | Bad Request |\n|  | \"Command already running\" - The command may already be running in a _Pending_ state waiting on the device. |\n|  | \"Command is not allowed for current device\" - The command may not be compatible with the target device. |\n|  | \"JSON parse error - Expecting ',' delimiter: line 3 column 2 (char 65)\" |\n| 401 | Unauthorized |\n|  | This error can occur if the token is incorrect, was revoked, or the token has expired. |\n| 403 | Forbidden |\n|  | The request was understood but cannot be authorized. |\n| 404 | Not found |\n|  | Unable to locate the resource in the Iru tenant. |\n| 415 | Unsupported Media Type |\n|  | The request contains a media type which the server or resource does not support. |\n| 500 | Internal server error |\n| 503 | Service unavailable |\n|  | This error can occur if a file upload is still being processed via the custom apps API. |\n\n#### Data structure\n\nThe API returns all structured responses in JSON schema format.\n\n#### Examples\n\nCode examples using the API can be found in the Iru Endpoint Management support [GitHub](https://github.com/kandji-inc/support/tree/main/api-tools)."
  version: 1.0.0
servers:
- url: https://{subdomain}.api.kandji.io
  description: US Server
  variables:
    subdomain:
      default: your-subdomain
      description: Your Iru Endpoint Management subdomain
- url: https://{subdomain}.api.eu.kandji.io
  description: EU Server
  variables:
    subdomain:
      default: your-subdomain
      description: Your Iru Endpoint Management subdomain
security:
- BearerAuth: []
tags:
- name: Devices
paths:
  /api/v1/devices/{device_id}/action/enablelostmode:
    post:
      summary: Enable Lost Mode
      description: This endpoint sends an MDM command to remotely turn on lost mode on iOS and iPadOS.
      parameters:
      - name: device_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: false
        description: Optional JSON payload to set lock message, phone number, and footnote on the target device
        content:
          application/json:
            schema:
              type: object
              properties:
                Message:
                  type: string
                  description: Lock screen message to display on the device
                PhoneNumber:
                  type: string
                  description: Phone number to display on the lock screen
                Footnote:
                  type: string
                  description: Footnote text to display on the lock screen
            example:
              Message: Hey i just did this from the enable lost mode API
              PhoneNumber: '1234567890'
              Footnote: This is an example footnote.
      responses:
        '200':
          description: Enable Lost Mode
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Bad Request
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Unauthorized
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Not Found
      tags:
      - Devices
  /api/v1/devices/{device_id}/action/disablelostmode:
    post:
      summary: Disable Lost Mode
      description: This command will send a request to turn off lost mode on iOS and iPadOS.
      parameters:
      - name: device_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Disable Lost Mode
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Bad Request
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Unauthorized
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Not Found
      tags:
      - Devices
  /api/v1/devices/{device_id}/action/playlostmodesound:
    post:
      summary: Play Lost Mode Sound
      description: This command will tell the target iOS or iPadOS device to play the lost mode sound.
      parameters:
      - name: device_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Play Lost Mode Sound
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Bad Request
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Unauthorized
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Not Found
      tags:
      - Devices
  /api/v1/devices/{device_id}/action/updatelocation:
    post:
      summary: Update Location
      description: This endpoint sends an MDM command to update the location data on iOS and iPadOS.
      parameters:
      - name: device_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Update Location
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Bad Request
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Unauthorized
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Not Found
      tags:
      - Devices
  /api/v1/devices/{device_id}/action/clearpasscode:
    post:
      summary: Clear Passcode
      description: This endpoint sends an MDM command to clear a device passcode. Available for iPhone and iPad.
      parameters:
      - name: device_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Bad Request
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Unauthorized
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Not Found
      tags:
      - Devices
  /api/v1/devices/{device_id}:
    get:
      summary: Get Device
      description: This request returns the high-level information for a specified Device ID.
      parameters:
      - name: device_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Bad Request
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Unauthorized
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Not Found
      tags:
      - Devices
    patch:
      summary: Update Device
      description: 'This request allows you to update device information, such as the assigned blueprint, user, Asset Tag, '
      parameters:
      - name: device_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                user:
                  type: string
                  description: The user ID (UUID or deprecated integer value). Can be set to null to clear the assigned user.
                asset_tag:
                  type: string
                  description: The asset tag for the device. Can be set to null to clear the asset tag.
                blueprint_id:
                  type: string
                  description: The blueprint ID to assign to the device.
                tags:
                  type: array
                  items:
                    type: string
                  description: Array of tag names to assign to the device. Can be set to [] to clear all tags.
      responses:
        '200':
          description: Clear all tags
          content:
            application/json:
              schema:
                type: object
                example:
                  device_id: bd4eb679-d679-4071-a395-5855807b6829
                  device_name: avenger-test
                  model: MacBook Air (M1, 2020)
                  serial_number: C02FL5YXQ6LC
                  platform: Mac
                  os_version: 13.2.1
                  last_check_in: '2023-03-24T00:45:18.674561Z'
                  user: ''
                  asset_tag: ''
                  blueprint_id: 97e4e175-1631-43f6-a02b-33fd1c748ab8
                  mdm_enabled: true
                  agent_installed: true
                  is_missing: false
                  is_removed: false
                  agent_version: 4.1.3 (3795)
                  first_enrollment: '2022-07-21 15:00:06.470889+00:00'
                  last_enrollment: '2023-03-13 17:29:41.167646+00:00'
                  blueprint_name: _testing_apple_silicon
                  lost_mode_status: ''
                  tags: []
              example:
                device_id: bd4eb679-d679-4071-a395-5855807b6829
                device_name: avenger-test
                model: MacBook Air (M1, 2020)
                serial_number: C02FL5YXQ6LC
                platform: Mac
                os_version: 13.2.1
                last_check_in: '2023-03-24T00:45:18.674561Z'
                user: ''
                asset_tag: ''
                blueprint_id: 97e4e175-1631-43f6-a02b-33fd1c748ab8
                mdm_enabled: true
                agent_installed: true
                is_missing: false
                is_removed: false
                agent_version: 4.1.3 (3795)
                first_enrollment: '2022-07-21 15:00:06.470889+00:00'
                last_enrollment: '2023-03-13 17:29:41.167646+00:00'
                blueprint_name: _testing_apple_silicon
                lost_mode_status: ''
                tags: []
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Bad Request
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Unauthorized
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Not Found
      tags:
      - Devices
    delete:
      summary: Delete device
      description: This endpoint deletes a specific device.
      parameters:
      - name: device_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Device deleted successfully
      tags:
      - Devices
  /api/v1/devices/{device_id}/action/erase:
    post:
      summary: Erase Device
      description: 'This endpoint sends an MDM command to erase the device.

        iOS 4.0+, iPadOS 4.0+, macOS 10.7+, tvOS 10.2+'
      parameters:
      - name: device_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                PIN:
                  type: string
                  description: 'The six-character PIN for Find My. This value is available in macOS 10.8 and later. Note: This value will be ignored for iOS, iPadOS, and tvOS devices.'
                PreserveDataPlan:
                  type: boolean
                  description: 'If true, preserve the data plan on an iPhone or iPad with eSIM functionality, if one exists. This value is available in iOS 11 and later. Default: true'
                DisallowProximitySetup:
                  type: boolean
                  description: 'If true, disable Proximity Setup on the next reboot and skip the pane in Setup Assistant. This value is available in iOS 11 and later. Prior to iOS 14, don''t use this option with any other option. Default: false'
                ReturnToService:
                  type: object
                  description: (iOS 17 and later and iPadOS 17 and later and with Shared iPad) When sending the erase device command to mobile devices, use this key to enable Return to Service. Include an optional Wi-Fi payload ProfileId to allow the device to connect to a Wi-Fi network automatically after being erased. If a Wi-Fi ProfileId is not provided and the mobile device is not tethered to a Mac to share the network connection, the end-user will be required to select a Wi-Fi network to complete the setup. If sent to any macOS computer or to mobile devices on iOS 16 or iPadOS 16 and below, the RTS keys will be ignored, and only the erase device command will be issued to the device.
                  properties:
                    Enabled:
                      type: boolean
                      description: (Required) If true, the device tries to re-enroll itself automatically after erasure. The user needs to deactivate all activation locks for this feature to work correctly.
                    ProfileId:
                      type: string
                      description: Profile ID value associated with a Wi-Fi profile payload. This is required when the device doesn't have ethernet access.
            example:
              PIN: '123456'
              PreserveDataPlan: true
              DisallowProximitySetup: false
              ReturnToService:
                Enabled: false
                ProfileId: ''
      responses:
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Bad Request
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Unauthorized
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Not Found
      tags:
      - Devices
  /api/v1/devices/{device_id}/commands:
    get:
      summary: Get Device Commands
      description: This endpoint sends a request to get information about the commands sent to a given device ID.
      parameters:
      - name: device_id
        in: path
        required: true
        schema:
          type: string
      - name: limit
        in: query
        required: false
        description: A hard upper `limit` is set at 300 device records returned per request. If more device records are expected, pagination should be used using the `limit` and `offset` parameters. Additionally, parameter queries can be added to a request to limit the results.
        schema:
          type: string
      - name: offset
        in: query
        required: false
        description: The initial index from which to return the results.
        schema:
          type: string
      responses:
        '200':
          description: Get Device Commands
          content:
            application/json:
              schema:
                type: object
                example:
                  device_id: 0bc8f610-5b88-49a6-b9ef-a68bf04e1e59
                  commands:
                    count: 41
                    next: null
                    previous: null
                    results:
                    - uuid: d2b2eafe-2dc2-4b13-bd2b-f93735f0e59f
                      error_chain: []
                      command_type: ActivationLockBypassCode
                      request_type: ActivationLockBypassCode
                      metadata: {}
                      request_requires_network_tether: false
                      status: 3
                      attempts: 1
                      date_requested: '2022-08-18T15:07:22.133248Z'
                      date_completed: '2022-08-18T15:07:23.240937Z'
                      last_pushed: '2022-08-18T15:07:22.507520Z'
                      user: null
                      priority: 0
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Bad Request
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Unauthorized
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Not Found
      tags:
      - Devices
  /api/v1/devices/{device_id}/action/lock:
    post:
      summary: Lock Device
      description: This endpoint sends an MDM command to remotely lock a device.
      parameters:
      - name: device_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                Message:
                  type: string
                  description: The lock message to display on the device.
                PhoneNumber:
                  type: string
                  description: The phone number to display on the device.
            example:
              Message: This device is locked!
              PhoneNumber: '1234567890'
      responses:
        '200':
          description: success
          content:
            application/json:
              schema:
                type: object
                example:
                  PIN: '496406'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Bad Request
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Unauthorized
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Not Found
      tags:
      - Devices
  /api/v1/devices/{device_id}/action/reinstallagent:
    post:
      summary: Reinstall Agent
      description: This endpoint sends an MDM command reinstall the Kandji Agent.
      parameters:
      - name: device_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Bad Request
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Unauthorized
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Not Found
      tags:
      - Devices
  /api/v1/devices/{device_id}/action/remotedesktop:
    post:
      summary: Remote Desktop
      description: This endpoint sends an MDM command to control the Remote Management status on a Mac.
      parameters:
      - name: device_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                EnableRemoteDesktop:
                  type: boolean
                  description: Enable or disable Remote Desktop on the device
              required:
              - EnableRemoteDesktop
            example:
              EnableRemoteDesktop: true
      responses:
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Bad Request
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Unauthorized
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Not Found
      tags:
      - Devices
  /api/v1/devices/{device_id}/action/renewmdmprofile:
    post:
      summary: Renew MDM Profile
      description: This endpoint sends an MDM command to re-install the existing root MDM profile for a given device ID.
      parameters:
      - name: device_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Renew MDM Profile
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Bad Request
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Unauthorized
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Not Found
      tags:
      - Devices
  /api/v1/devices/{device_id}/action/restart:
    post:
      summary: Restart Device
      description: This endpoint sends an MDM command to remotely restart a device.
      parameters:
      - name: device_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                RebuildKernelCache:
                  type: boolean
                  description: 'If `true`, the system rebuilds the kernel cache during a device restart. If `BootstrapTokenAllowedForAuthentication` is `true` in `SecurityInfoResponse.SecurityInfo`, the device requests the bootstrap token from MDM before executing this command. This value is available in macOS 11 and later. Default: false'
                NotifyUser:
                  type: boolean
                  description: 'If `true`, notifies the user to restart the device at their convenience. Forced restart if the device is at `loginwindow` with no logged-in users. The user can dismiss the notification and ignore the request. No further notifications display unless you resend the command. This value is available in macOS 11.3 and later. Default: false'
            example:
              RebuildKernelCache: false
              NotifyUser: false
      responses:
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Bad Request
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Unauthorized
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Not Found
      tags:
      - Devices
  /api/v1/devices/{device_id}/action/blankpush:
    post:
      summary: Send Blankpush
      description: This endpoint sends an MDM command to initiate a blank push.
      parameters:
      - name: device_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Bad Request
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Unauthorized
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: Not Found
      tags:
      - Devices
  /api/v1/devices/{device_id}/action/setname:
    post:
      summary: Set Name
      description: This endpoint sends an MDM command to set the device name.
      parameters:
      - name: device_id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                DeviceName:
                  type: string
                  description: The new device name to set.
              required:
              - DeviceName
            example:
              DeviceName: Test Mac Mini
      responses:
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                proper

# --- truncated at 32 KB (78 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/kandji/refs/heads/main/openapi/kandji-devices-api-openapi.yml