# Device groups

A device group matches devices by a regular expression that the platform compares with the `User-Agent` request header. These `azion/applications` functions create, list, read, update, and delete the device groups of an application.

---

## createDeviceGroup

Creates a device group in an application. A device group matches devices by a regular expression that the platform compares with the `User-Agent` request header.

```typescript
function createDeviceGroup(params: {
  applicationId: number;
  data: ApiCreateDeviceGroupPayload;
  options?: AzionClientOptions;
}): Promise<AzionApplicationResponse<AzionDeviceGroup>>;
```

| Parameter       | Type                                                                                               | Required | Description                                                                                               |
| --------------- | -------------------------------------------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------- |
| `applicationId` | `number`                                                                                           | Yes      | The ID of the application.                                                                                |
| `data`          | `{ name: string; user_agent: string }`                                                             | Yes      | `name` names the group, and `user_agent` holds the regular expression, such as `Mobile\|Android\|iPhone`. |
| `options`       | [`AzionClientOptions`](/en/documentation/devtools/azion-lib/application/types/#azionclientoptions) | No       | Request options.                                                                                          |

Returns `data` as the created [AzionDeviceGroup](/en/documentation/devtools/azion-lib/application/types/#aziondevicegroup). The API refuses a `name` that contains a space or a hyphen. The function then returns `error` with the message `HTTP error! Status: 400 - BAD REQUEST`.

```typescript
import { createDeviceGroup } from 'azion/applications';

const applicationId = 1234567890; // Replace with the actual application ID

// Create a new device group
const deviceGroupData = {
  name: 'MobileDevices',
  user_agent: 'Mobile|Android|iPhone',
};

const { data: newDeviceGroup, error } = await createDeviceGroup({ applicationId, data: deviceGroupData });

if (error) {
  console.error('Error creating device group:', error);
} else {
  console.log('Device group created successfully:', newDeviceGroup);
}
```

Output:

```text
Device group created successfully: {
  id: 1234,
  name: 'MobileDevices',
  user_agent: 'Mobile|Android|iPhone'
}
```

---

## getDeviceGroups

Lists the device groups of an application, one page at a time.

```typescript
function getDeviceGroups(params: {
  applicationId: number;
  params?: ApiListDeviceGroupsParams;
  options?: AzionClientOptions;
}): Promise<AzionApplicationCollectionResponse<AzionDeviceGroup>>;
```

| Parameter       | Type                                                                                                   | Required | Description                         |
| --------------- | ------------------------------------------------------------------------------------------------------ | -------- | ----------------------------------- |
| `applicationId` | `number`                                                                                               | Yes      | The ID of the application.          |
| `params`        | [`ApiListDeviceGroupsParams`](/en/documentation/devtools/azion-lib/application/types/#list-parameters) | No       | Pagination: `page` and `page_size`. |
| `options`       | [`AzionClientOptions`](/en/documentation/devtools/azion-lib/application/types/#azionclientoptions)     | No       | Request options.                    |

Returns an [AzionApplicationCollectionResponse](/en/documentation/devtools/azion-lib/application/types/#azionapplicationcollectionresponse) whose `data.results` holds [AzionDeviceGroup](/en/documentation/devtools/azion-lib/application/types/#aziondevicegroup) objects.

```typescript
import { getDeviceGroups } from 'azion/applications';

const applicationId = 1234567890; // Replace with the actual application ID

const { data: deviceGroups, error } = await getDeviceGroups({ applicationId, params: { page: 1, page_size: 20 } });

if (error) {
  console.error('Error listing device groups:', error);
} else {
  console.log(`Found ${deviceGroups?.count} device groups:`, deviceGroups?.results);
}
```

Output:

```text
Found 1 device groups: [
  {
    id: 1234,
    name: 'MobileDevices',
    user_agent: 'Mobile|Android|iPhone'
  }
]
```

---

## getDeviceGroup

Returns one device group of an application by its ID.

```typescript
function getDeviceGroup(params: {
  applicationId: number;
  deviceGroupId: number;
  options?: AzionClientOptions;
}): Promise<AzionApplicationResponse<AzionDeviceGroup>>;
```

| Parameter       | Type                                                                                               | Required | Description                 |
| --------------- | -------------------------------------------------------------------------------------------------- | -------- | --------------------------- |
| `applicationId` | `number`                                                                                           | Yes      | The ID of the application.  |
| `deviceGroupId` | `number`                                                                                           | Yes      | The ID of the device group. |
| `options`       | [`AzionClientOptions`](/en/documentation/devtools/azion-lib/application/types/#azionclientoptions) | No       | Request options.            |

Returns `data` as an [AzionDeviceGroup](/en/documentation/devtools/azion-lib/application/types/#aziondevicegroup).

```typescript
import { getDeviceGroup } from 'azion/applications';

const applicationId = 1234567890; // Replace with the actual application ID
const deviceGroupId = 1234; // Replace with the actual device group ID

const { data: deviceGroup, error } = await getDeviceGroup({ applicationId, deviceGroupId });

if (error) {
  console.error('Error retrieving device group:', error);
} else {
  console.log('Device group details:', deviceGroup);
}
```

Output:

```text
Device group details: {
  id: 1234,
  name: 'MobileDevices',
  user_agent: 'Mobile|Android|iPhone'
}
```

---

## updateDeviceGroup

Sends the device group fields you pass in a `PATCH` request. The new `name` follows the same rule as on create: no spaces and no hyphens.

```typescript
function updateDeviceGroup(params: {
  applicationId: number;
  deviceGroupId: number;
  data: ApiUpdateDeviceGroupPayload;
  options?: AzionClientOptions;
}): Promise<AzionApplicationResponse<AzionDeviceGroup>>;
```

| Parameter       | Type                                                                                               | Required | Description                           |
| --------------- | -------------------------------------------------------------------------------------------------- | -------- | ------------------------------------- |
| `applicationId` | `number`                                                                                           | Yes      | The ID of the application.            |
| `deviceGroupId` | `number`                                                                                           | Yes      | The ID of the device group to update. |
| `data`          | `{ name?: string; user_agent?: string }`                                                           | Yes      | The fields to change.                 |
| `options`       | [`AzionClientOptions`](/en/documentation/devtools/azion-lib/application/types/#azionclientoptions) | No       | Request options.                      |

Returns `data` as the updated [AzionDeviceGroup](/en/documentation/devtools/azion-lib/application/types/#aziondevicegroup).

```typescript
import { updateDeviceGroup } from 'azion/applications';

const applicationId = 1234567890; // Replace with the actual application ID
const deviceGroupId = 1234; // Replace with the actual device group ID

const { data: updatedDeviceGroup, error } = await updateDeviceGroup({
  applicationId,
  deviceGroupId,
  data: { name: 'MobileAndTablets', user_agent: 'Mobile|Android|iPhone|iPad' },
});

if (error) {
  console.error('Error updating device group:', error);
} else {
  console.log('Device group updated:', updatedDeviceGroup);
}
```

Output:

```text
Device group updated: {
  id: 1234,
  name: 'MobileAndTablets',
  user_agent: 'Mobile|Android|iPhone|iPad'
}
```

---

## deleteDeviceGroup

Deletes a device group of an application by its ID.

```typescript
function deleteDeviceGroup(params: {
  applicationId: number;
  deviceGroupId: number;
  options?: AzionClientOptions;
}): Promise<AzionApplicationResponse<void>>;
```

| Parameter       | Type                                                                                               | Required | Description                           |
| --------------- | -------------------------------------------------------------------------------------------------- | -------- | ------------------------------------- |
| `applicationId` | `number`                                                                                           | Yes      | The ID of the application.            |
| `deviceGroupId` | `number`                                                                                           | Yes      | The ID of the device group to delete. |
| `options`       | [`AzionClientOptions`](/en/documentation/devtools/azion-lib/application/types/#azionclientoptions) | No       | Request options.                      |

A successful delete returns `error` with the message `Expected JSON response, but got: `, so the sample reads the device group back with [getDeviceGroup](#getdevicegroup). A `404` error confirms the delete.

```typescript
import { deleteDeviceGroup, getDeviceGroup } from 'azion/applications';

const applicationId = 1234567890; // Replace with the actual application ID
const deviceGroupId = 1234; // Replace with the actual device group ID

const { error: deleteError } = await deleteDeviceGroup({ applicationId, deviceGroupId });

// On success (HTTP 204) the envelope still carries an error, so confirm by reading it back
const { error } = await getDeviceGroup({ applicationId, deviceGroupId });
if (error) {
  console.log(`Device group ${deviceGroupId} deleted (read back: ${error.message})`);
} else {
  console.error('Error deleting device group:', deleteError);
}
```

Output:

```text
Device group 1234 deleted (read back: HTTP error! Status: 404 - NOT FOUND)
```

---

## Related resources

- [Azion Lib](/en/documentation/devtools/azion-lib.md): The Azion Lib modules and the npm package each one ships in.
- [Applications](/en/documentation/devtools/azion-lib/application.md): The module's authentication, its response envelope, and the errors its functions report.
- [Application types](/en/documentation/devtools/azion-lib/application/types.md): The payload and response types these functions take and return.
- [Device groups](/en/documentation/platform/applications/device-groups.md): The device group an application matches by User-Agent.