> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.itential.com/itential-gateway/4/create-manage-devices/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server.

# Create and manage devices

> How to create and manage devices and device groups via GUI or API.

Information and examples on how to create and manage devices via GUI or API are provided here.

## Create devices

### Via API

You can create an **Internal** device by making a `POST` call to `/api/2.0/devices`.

An example payload to create a device to use with Ansible is shown below.

```json
{
"name": "csr",
  "variables": {
    "ansible_host": "csr.device",
    "ansible_connection":"network_cli",
    "ansible_network_os":"ios",
    "ansible_user": "username",
    "ansible_password": "password"
  }  
}
```

You can create an **Internal** device group by making a `POST` call to `/api/2.0/groups`.

> **Note**
>
> In Ansible, `all` is a reserved group name that implicitly contains every host and group in the inventory. Using `all` as a custom group name creates a conflict that prevents Gateway from parsing the inventory correctly.
>
> For more information, see [Ansible's default groups](http://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#default-groups).

An example payload to create a group to use with Ansible is shown below.

```json
{
  "name": "group_1",
  "childGroups": [
    "child_group_1"
  ],
  "devices": [
    "csr"
  ], 
  "variables": {}
}
```

### Via GUI

You can click the circled plus (**+**) button in the toolbar on the upper-left to start an interactive window to create a **Device for Ansible**.

![](/_fern-img/627c47dcaea2cadfccabe6c854af1308b608c817f937fee9e312c0c551c36135.webp)

You can click the circled plus (**+**) button to start an interactive window to create a **Device Group for Ansible**.

> **Note**
>
> In Ansible, `all` is a reserved group name that implicitly contains every host and group in the inventory. Using `all` as a custom group name creates a conflict that prevents Gateway from parsing the inventory correctly.
>
> For more information, see [Ansible's default groups](http://docs.ansible.com/projects/ansible/latest/inventory_guide/intro_inventory.html#default-groups).

![](/_fern-img/1f84a23d7fd32d4b8154995eff7364448c4282948e26f26d72d4325302976dd9.webp)

## View devices

### Via API

You can view Ansible devices by making a `GET` call to `/api/2.0/devices` or `/api/2.0/devices/{device_name}`.

An example payload to view Ansible devices is shown below.

```json
{
    "data": [
        {
            "name": "csr",
            "variables": {
                "ansible_connection": "network_cli",
                "ansible_host": "csr.device",
                "ansible_network_os": "ios",
                "ansible_password": "password",
                "ansible_user": "username"
            }
        }
    ],
    "meta": {
        "count": 1,
        "query_object": {
            "filter": null,
            "limit": null,
            "offset": null,
            "order": "ascending"
        }
    }
}
```

You can view Ansible groups by making a `GET` call to `/api/2.0/groups` or `/api/2.0/groups/{group_name}`.

An example payload to view Ansible groups is shown below.

```json
{
    "data": [
        {
            "childGroups": [],
            "devices": [],
            "name": "child_group_1",
            "variables": {}
        },
        {
            "childGroups": [
                "child_group_1"
            ],
            "devices": [
                "csr"
            ],
            "name": "group_1",
            "variables": {}
        }
    ],
    "meta": {
        "count": 2,
        "query_object": {
            "filter": null,
            "limit": null,
            "offset": null,
            "order": "ascending"
        }
    }
}
```

### Via GUI

In the left navbar under **Devices**, you will find all the devices and groups you have created for use with Ansible.

![](/_fern-img/3002cde35e8043e7cb8935ecd98529cfdecad634e042d3c95bb297bf619c063f.webp)

## Update devices

### Via API

You can update an **Internal** device by making a `PUT` call to `/api/2.0/devices/{device_name}`.

An example payload to update the properties of an Ansible device (in this case, `ansible_user` and `ansible_password`) is shown below.

```json
{
	"variables": {
		"ansible_host": "csr.device",
		"ansible_connection": "network_cli",
		"ansible_network_os": "ios",
		"ansible_user": "new_username",
		"ansible_password": "new_password"
	}
}
```

You can update an **Internal** device group by making a `PUT` call to `/api/2.0/groups/{group_name}`.

An example payload to update the properties of an Ansible device group (in this case, `devices`) is shown below.

```json
{
  "name": "group_1",
  "childGroups": [
    "child_group_1"
  ],
  "devices": [
    "csr", "new_device"
  ], 
  "variables": {}
}
```

### Via GUI

When viewing a device, you can click the **Edit** button at the bottom of the page to edit the associated variables of the device.

![](/_fern-img/925c59339d4c7e40cea5b6dd6f0e50fc59a8f4cc0f3d8bdba46665b43cb0ed58.webp)

When viewing a device group, you can click the **+** button near the **Devices** tab at the top to edit the devices associated with that group. You can also select the **Group Variables** tab and click **Edit** at the bottom to edit the associated variables of the group.

![](/_fern-img/e8aee4903a7341eac89c07dafdeff7448302e04cfdec3012c7057d1084d6196b.webp)

## Remove devices

### Via API

You can delete an Ansible device by making a `DELETE` call to `/api/2.0/devices/{device_name}`.

### Via GUI

When viewing a device, select the **Delete** button at the bottom of the page and then confirm the deletion.

![](/_fern-img/db0d24c6f33895d713a9cc63c3c892c459211cdb84bfea4cc3f59a2b01a38fab.webp)

When viewing a device group, hover over the vertical ellipsis (**⋮**) at the top and select **Delete group** from the menu that appears. Confirm the deletion.

![](/_fern-img/4c926e74c037e70c2bf5ca534d4be4a8f596c517a88ace78fdc7977dc326c33f.webp)

> How to create and manage devices and device groups via GUI or API.