Device Groups API

Endpoints for creating and managing device groups for targeted rollouts and deployments.

List groups

GET /api/v1/device-groups

Returns device groups for an organization with pagination.

Query Parameters

Parameter	Type	Required	Description
org_id	string	Yes	Organization identifier
limit	integer	No	Maximum records (default 100, max 1000)
offset	integer	No	Records to skip (default 0)

Response

{
  "groups": [
    {
      "id": "grp_abc123",
      "org_id": "org_demo",
      "name": "iOS Beta Testers",
      "description": "Internal canary cohort",
      "group_type": "static",
      "tags": ["ios", "canary"],
      "device_count": 25,
      "created_at": "2026-02-23T16:30:00Z"
    }
  ],
  "total": 1, "limit": 50, "offset": 0
}

---

Retrieve a group

GET /api/v1/device-groups/{group_id}

Returns metadata for a single device group.

---

Create a group

POST /api/v1/device-groups

Creates a named group for assigning and rolling out model versions to cohorts.

Body Parameters

Parameter	Type	Required	Description
org_id	string	Yes	Organization identifier
name	string	Yes	Group name
description	string	No	Human-readable group description
group_type	string	No	Group type (e.g. static)
tags	string[]	No	Optional tags for filtering

---

Update a group

PUT /api/v1/device-groups/{group_id}

Updates an existing device group's metadata (name, description, tags).

---

Delete a group

DELETE /api/v1/device-groups/{group_id}

Deletes a device group. Existing devices remain registered and are only removed from this group.

---

List group members

GET /api/v1/device-groups/{group_id}/devices

Returns devices that are currently members of the specified group. Supports limit and offset query parameters.

---

Add a device

POST /api/v1/device-groups/{group_id}/devices/{device_id}

Adds a single device to a device group.

---

Remove a device

DELETE /api/v1/device-groups/{group_id}/devices/{device_id}

Removes a single device from a device group.

---

Add devices (batch)

POST /api/v1/device-groups/{group_id}/devices

Adds multiple devices in one request.

Body

Parameter	Type	Required	Description
device_ids	string[]	Yes	Device IDs to add
added_by	string	No	Actor label for audit trail

Response

{
  "group_id": "grp_abc123",
  "added": ["dev_abc123", "dev_def456"],
  "skipped": []
}

---

Remove devices (batch)

DELETE /api/v1/device-groups/{group_id}/devices

Removes multiple devices in one request.

Body

Parameter	Type	Required	Description
device_ids	string[]	Yes	Device IDs to remove

---

Errors

Status	Error	Description
400	bad_request	Invalid or missing request fields
401	unauthorized	Missing or invalid API key
404	not_found	Resource does not exist
409	conflict	Resource already exists or state conflict
429	rate_limited	Too many requests; check Retry-After
500	internal_error	Unexpected server error