Device Deployments

Deployment endpoints provide access to enrollment deployment history for a device. Each record in device_deployments represents a single enrollment event -- when an enrollment token was used to deploy the agent to a device.

Load this data alongside Get Device to show deployment status on the device detail page.

Endpoints

Endpoint	Method	Description
List Deployments	GET	Paginated deployment history for a device
Get Deployment	GET	Full deployment record with error logs

---

List Deployments

GET /clients/{client_id}/devices/{device_id}/deployments

Returns a paginated list of enrollment deployments for a device, ordered by enrollment_date descending (newest first). The first item represents the most recent deployment attempt.

Path Parameters

Parameter	Type	Description
client_id	string (uuid)	Unique identifier for the client organization
device_id	string (uuid)	Unique identifier for the device

Query Parameters

Parameter	Type	Default	Description
status	string	-	Filter by deployment status: success, error, pending
sort_by	string	enrollment_date	Sort field: enrollment_date, status, created_at
sort_order	string	desc	Sort direction: asc, desc
page_size	integer	50	Items per page. Max: 500
cursor	string	-	Pagination cursor from a previous response

Response

Field	Type	Description
data	DeviceDeploymentRef[]	Array of deployment objects
total_count	integer	Total number of deployments matching filters
next_cursor	string | null	Cursor for the next page. null when on the last page.

Example Request

curl -X GET "https://api.example.com/v2/clients/aa7cf840-9ca9-46a3-9778-9015d6580d50/devices/f1e2d3c4-b5a6-7890-abcd-ef1234567890/deployments" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Example Response

{
  "data": [
    {
      "id": "d1e2f3a4-b5c6-7890-abcd-ef1234567890",
      "status": "success",
      "enrollment_date": "2026-01-30T14:30:00.000Z"
    },
    {
      "id": "c2d3e4f5-a6b7-8901-bcde-f12345678901",
      "status": "error",
      "enrollment_date": "2026-01-29T09:00:00.000Z"
    }
  ],
  "total_count": 2,
  "next_cursor": null
}

Filter by Status

curl -X GET "https://api.example.com/v2/clients/aa7cf840-9ca9-46a3-9778-9015d6580d50/devices/f1e2d3c4-b5a6-7890-abcd-ef1234567890/deployments?status=error" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

---

Get Deployment

GET /clients/{client_id}/devices/{device_id}/deployments/{deployment_id}

Returns the full DeviceDeployment record for a single deployment event, including error logs.

Path Parameters

Parameter	Type	Description
client_id	string (uuid)	Unique identifier for the client organization
device_id	string (uuid)	Unique identifier for the device
deployment_id	string (uuid)	Unique identifier for the deployment event

Response

Returns a single DeviceDeployment object.

Example Request

curl -X GET "https://api.example.com/v2/clients/aa7cf840-9ca9-46a3-9778-9015d6580d50/devices/f1e2d3c4-b5a6-7890-abcd-ef1234567890/deployments/c2d3e4f5-a6b7-8901-bcde-f12345678901" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Example Response (Error Deployment)

{
  "id": "c2d3e4f5-a6b7-8901-bcde-f12345678901",
  "status": "error",
  "enrollment_date": "2026-01-29T09:00:00.000Z",
  "enrollment_token_id": "e1f2a3b4-c5d6-7890-abcd-ef1234567890",
  "user_id": "a1d97031-04e2-4907-a249-093f7436207b",
  "error_logs": [
    "2026-01-29T09:00:01Z: Starting deployment...",
    "2026-01-29T09:00:05Z: Downloading agent package...",
    "2026-01-29T09:00:15Z: Installation failed - insufficient permissions",
    "2026-01-29T09:00:15Z: Deployment aborted"
  ],
  "created_at": "2026-01-29T09:00:00.000Z",
  "updated_at": "2026-01-29T09:00:15.000Z"
}

Example Response (Successful Deployment)

{
  "id": "d1e2f3a4-b5c6-7890-abcd-ef1234567890",
  "status": "success",
  "enrollment_date": "2026-01-30T14:30:00.000Z",
  "enrollment_token_id": "e1f2a3b4-c5d6-7890-abcd-ef1234567890",
  "user_id": null,
  "error_logs": null,
  "created_at": "2026-01-30T14:30:00.000Z",
  "updated_at": "2026-01-30T14:30:45.000Z"
}

---

Error Responses

Status	Description
400	Invalid query parameters (e.g. unknown sort_by value)
401	Authentication required
403	Insufficient permissions for this client
404	Device, client, or deployment not found
500	Server error

Example Error Response

{
  "error": {
    "code": "not_found",
    "message": "Deployment not found",
    "details": {
      "deployment_id": "c2d3e4f5-a6b7-8901-bcde-f12345678901"
    }
  }
}

Notes

• Deployments are sorted by enrollment_date descending by default (newest first)
• The first deployment in the list represents the most recent enrollment attempt
• error_logs is only populated for failed deployments; successful deployments return null
• status values:
  • success -- Enrollment completed successfully
  • error -- Enrollment failed (check error_logs in the detail endpoint)
  • pending -- Enrollment in progress

Related Endpoints

• Get Device - Device hardware and OS information
• Device Users - Users observed on this device
• List Devices - Paginated list of all devices