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

# RESTCONF API

> Use the restAction task to make RESTCONF calls to NSO from Itential Platform workflows.

RESTCONF provides a programmatic interface for reading and writing network device configurations through NSO. Platform workflows interact with the NSO RESTCONF API using the `restAction` task.

## NSO RESTCONF support

| NSO version       | RESTCONF support                               |
| ----------------- | ---------------------------------------------- |
| NSO 5.x           | Supported alongside legacy REST                |
| NSO 5.3           | Last version to support both RESTCONF and REST |
| NSO 5.4 and later | RESTCONF only (REST removed)                   |

NSO also supports JSON-RPC and NETCONF. See [Cisco NSO developer documentation](https://developer.cisco.com/docs/nso/) for Swagger API documentation and additional protocol references.

## HTTP methods

| Method   | CRUD operation                                                 |
| -------- | -------------------------------------------------------------- |
| `GET`    | Read                                                           |
| `PATCH`  | Update (merge)                                                 |
| `PUT`    | Create or replace                                              |
| `POST`   | Create or trigger operations (such as `reload` or `sync-from`) |
| `DELETE` | Delete targeted resource                                       |

Method values are case-insensitive.

## The restAction task

Use the `restAction` task in a workflow to make RESTCONF calls to NSO. The task handles authentication and connection routing through the configured NSO adapter.

`restAction` calls carry the adapter's trace-id automatically — as a `traceparent` header on NSO 6.7 and later, or a `trace-id` query parameter on earlier versions. See [Trace-ID propagation](./trace-id-propagation) for how trace-ids work across protocols and where to find them for troubleshooting.

### Incoming variables

| Variable    | Type   | Required | Description                                                                                                                |
| ----------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------- |
| `adapterId` | String | Yes      | The name of the NSO adapter instance to use. This resolves the NSO host address and authentication. Example: `"Local NSO"` |
| `params`    | Object | Yes      | Call parameters: `path`, `method`, `contentType`, and `accept`                                                             |
| `body`      | Object | Yes      | The request payload to send to NSO. Use an empty object `{}` for requests with no body.                                    |

### Outgoing variables

| Variable | Type   | Description           |
| -------- | ------ | --------------------- |
| `result` | Object | The response from NSO |

### params object

```json
{
  "path": "/restconf/data/tailf-ncs:devices/device=C-IOS1",
  "contentType": "application/yang-data+json",
  "accept": "application/yang-data+json",
  "method": "GET"
}
```

## Examples

The following examples show complete `restAction` variable inputs for each HTTP method. In each example, `adapterId` is set to `"Local NSO"` — substitute the name of your configured adapter instance.

### GET — read a device

Retrieve device information for `C-IOS1`:

```json
adapterId: "Local NSO"

params: {
  "path": "/restconf/data/tailf-ncs:devices/device=C-IOS1",
  "contentType": "application/yang-data+json",
  "accept": "application/yang-data+json",
  "method": "GET"
}

body: {}
```

### PATCH — update device configuration

Add a loopback interface configuration to `C-IOS1`:

```json
adapterId: "Local NSO"

params: {
  "path": "/restconf/data/tailf-ncs:devices/device=C-IOS1/config",
  "accept": "application/yang-data+json",
  "contentType": "application/yang-data+json",
  "method": "PATCH"
}

body: {
  "config": {
    "tailf-ned-cisco-ios:interface": {
      "Loopback": [
        {
          "name": "1",
          "ip": {
            "address": {
              "primary": {
                "address": "127.0.0.1",
                "mask": "255.0.0.0"
              }
            }
          }
        }
      ]
    }
  }
}
```

### PUT — replace a configuration resource

Replace the IP address configuration on loopback interface `1` of `C-IOS1`:

```json
adapterId: "Local NSO"

params: {
  "path": "/restconf/data/tailf-ncs:devices/device=C-IOS1/config/tailf-ned-cisco-ios:interface/Loopback=1/ip",
  "accept": "application/yang-data+json",
  "contentType": "application/yang-data+json",
  "method": "PUT"
}

body: {
  "ip": {
    "address": {
      "primary": {
        "address": "127.0.0.2",
        "mask": "255.0.0.0"
      }
    }
  }
}
```

### POST — create a device

Add a new device named `C-IOS1` to NSO:

```json
adapterId: "Local NSO"

params: {
  "path": "/restconf/data/tailf-ncs:devices",
  "contentType": "application/yang-data+json",
  "accept": "application/yang-data+json",
  "method": "POST"
}

body: {
  "tailf-ncs:device": {
    "name": "C-IOS1",
    "address": "127.0.0.1",
    "port": 10022,
    "authgroup": "default",
    "device-type": {
      "cli": {
        "ned-id": "cisco-ios-cli-6.23:cisco-ios-cli-6.23"
      }
    }
  }
}
```

### DELETE — remove a device

Delete the `C-IOS1` device from NSO:

```json
adapterId: "Local NSO"

params: {
  "path": "/restconf/data/tailf-ncs:devices/device=C-IOS1",
  "accept": "application/yang-data+json",
  "contentType": "application/yang-data+json",
  "method": "DELETE"
}

body: {}
```

## Device lifecycle automation example

A common pattern is to chain `restAction` calls in a workflow to perform a full device onboarding sequence:

1. **Add device** — POST to create the device record in NSO
2. **Fetch SSH host keys** — POST to `/restconf/data/tailf-ncs:devices/device=C-IOS1/ssh/fetch-host-keys`
3. **Sync from device** — POST to `/restconf/data/tailf-ncs:devices/device=C-IOS1/sync-from`
4. **Delete device** — DELETE to remove the device when decommissioning

Each step uses a separate `restAction` task in the workflow, chained sequentially.

## Service model example

To apply a service model using `restAction` with commit queue options, include the `commit-queue` tag in the POST body. Optional parameters such as `no-out-of-sync-check` and `continue-on-error` can be included for operational resilience during bulk deployments.

Refer to the [Cisco NSO developer documentation](https://developer.cisco.com/docs/nso/) for the YANG model paths specific to your service models.

## Related reading

* [Itential Tools actions](./itential-tools-actions)
* [NETCONF event streams](./netconf-events)
* [Configure the NSO adapter](./configure-adapter)
* [Trace-ID propagation](./trace-id-propagation)
* [Cisco NSO developer documentation](https://developer.cisco.com/docs/nso/)

> Use the restAction task to make RESTCONF calls to NSO from Itential Platform workflows.