JSON interface

SR Linux provides a JSON-based Remote Procedure Call (JSON-RPC) interface for CLI commands, configuration, and YANG-modeled actions. It enables you to retrieve and modify configuration and state, execute YANG-modeled actions, and receive responses in JSON format.

If output from a command cannot be displayed in JSON, the text output is wrapped in JSON to allow the application calling the API to retrieve the output. During configuration, if a TCP port is in use when the JSON-RPC server attempts to bind to it, the commit fails. The JSON-RPC supports both normal paths, as well as XPATHs.

JSON message structure

JSON RPC requires a specific message structure. The jsonrpc version, ID, method, and params are required in all requests. For example:

{
  "jsonrpc": "2.0",
  "id": 0,
  "method": "get",
  "params": {
  }
}

Within these required elements can be additional mandatory and conditional elements, as described in the following table.

Table 1. Required JSON request structure
Required request elements	Description
`jsonrpc`	Version, which must be ‟2.0”. No other JSON RPC versions are currently supported.
`id`	Client-provided integer. The JSON RPC responds with the same ID, which allows the client to match requests to responses when there are concurrent requests.
`method`	Defines the method accessed with the JSON RPC. Supported options are as follows. `get` `set` `validate` `cli` `action`
`params`	Defines a container for any parameters related to the request. The type of parameter is dependent on the method used.

method options

The following table defines supported JSON RPC method options.

Table 2. JSON RPC method options
Method option	Description
`get`	Used to retrieve configuration and state details from the system. The `get` method can be used with candidate, running, and state datastores, but cannot be used with the tools datastore.
`set`	Used to set configuration in the candidate datastore. For a YANG-modeled action, use the `action` method,
`validate`	Used to verify that the system accepts a configuration transaction before applying it to the system.
`cli`	Used to execute CLI commands. The `get` and `set` methods are restricted to accessing data structures via the YANG models, but the `cli` method can access any commands added to the system via python plug-ins or aliases. Both the `cli` and `action` methods are valid currently. However, automations that use `cli` method to execute operational commands can be migrated to the `action` method over time to provide structured data input and output aligned with the YANG models.
action	Used to execute a YANG modeled action with input and output encoding aligned with the YANG schema. The path identifies the YANG `action` node and includes an exact value for every list key. An optional JSON payload specifies the action `input` leaves. The response contains the modeled action `output` and does not include the `srl-unstructured-output` field. See Unstructured output for more information. If the action fails because of authorization, validation, or handler errors, the server returns a JSON-RPC error. Each request executes one action.

params options

The following table defines valid JSON RPC params options.

Table 3. JSON RPC params options
params option	Descriptions
action	action command - Conditional mandatory; used with the set and validate methods. Supported options are: replace — Replaces the entire configuration within a specific context with the supplied configuration; equivalent to a delete/update. update — Updates a leaf or container with the specified value. delete — Deletes a leaf or container. All children beneath the parent are removed from the system. Note: When the action command is used with the tools datastore, update is the only supported option. Important: The JSON-RPC `action` method and the action command method serve different purposes. The `action` params command specifies the operation to perform in the JSON-RPC such as replacing, updating, or deleting configuration data.
path	path command - Mandatory with the get, set, validate, and action methods. This value is a string that follows the gNMI path specification¹ in human-readable format: ‟/” separates nodes keys are specified using [<key-name>=<key-value>] if key-value contains ‟]”, it must be escaped (‟\” before the ”]” fields end with ‟.” or ‟,value>” Example: /interface[name=mgmt0]
path-keywords	path-keywords command - Optional; used to substitute named parameters with the path field. More than one keyword can be used with each path.
payload	payload command - Optional. Used with the `action` method. A JSON object containing the YANG structured instance data from the action `input` statement.
datastore	datastore command - Optional; selects the datastore to perform the method against. Supported options are: candidate — Used to change the configuration of the system with the get, set, and validate methods; default datastore is used if the datastore parameter is not provided. running — Used to retrieve the active configuration with the get method. state — Used to retrieve the running (active) configuration along with the operational state. tools — Used to perform operational tasks on the system; only supported with the update action command and the set method. For a YANG modeled action, use the `action` or `cli` method.
recursive	recursive command - Optional; a Boolean used to retrieve children underneath the specific path. The default = true.
include-field-defaults	include-field-defaults command - Optional; a Boolean used to show all fields, regardless if they have a directory configured or are operating at their default setting. The default = false.
output-format - Optional. Defines the output format as: json text table	output-format command - cli method — output-format (optional, default: json): Specifies the output format for ordinary CLI commands. Supported values are json, text, table, yaml, xml, and flat. This parameter does not affect a tools or action line. cli method — tools-output-format (optional): Specifies the output format for a tools command. Supported values are json and unstructured-output. action method — output-format (optional, default: json): Specifies the output format of the action result. The action method does not support a separate tools-output-format parameter.

¹ gNMI path specification reference: https://github.com/openconfig/reference/blob/master/rpc/gnmi/gnmi-path-conventions.md

JSON responses

The JSON RPC returns one entry for each command that was executed. For methods that do not contain response (other than acknowledging the command), a response is returned, but with an empty list.

When the cli method is used, each executed command returns an individual response.

Compressed JSON responses using gzip

If a client request specifies to use HTTP compression, the JSON RPC server compresses the responses using gzip.

Candidate mode

JSON uses its own private exclusive candidate that restricts other users or services from making simultaneous changes to a configuration. If another exclusive session is already active, any commits to the configuration using the JSON-RPC set method fail with an error.

The JSON-RPC server uses the private exclusive candidate name jsonrpc-<n>, where <n> is a 32-bit number starting at 1 that increments for every request received, but resets on a JSON-RPC server restart.

Logical expressions

For logical expressions, support is provided for the asterisk (‟*”) which can be used to reference all keys within a list. This is not applicable for action method.

Interactive CLI commands

A small subset of command require interactive user input. These commands cannot be executed using any interface except the CLI.

JSON examples

The following sections provides JSON examples (both requests and responses) for get, set, delete, validate, cli and action method options.

JSON get examples

The get method allows you to retrieve configuration and state details from the system. The following examples are shown:

get method using the path, datastore, and recursive commands with the recursive option set to true (to retrieve children underneath the specific path)
multiple get request where multiple commands are executed with a single request

Single get with recursive request

{
  "jsonrpc": "2.0",
  "id": 0,
  "method": "get",
  "params": {
    "commands": [
      {
        "path": "/interface[name=mgmt0]",
        "datastore": "state",
        "recursive": true
      }
    ]
  }
}

Response (single get with recursive)

{
  "result": [
    {
      "name": "mgmt0",
      "admin-state": "enable",
      "mtu": 1514,
      "ifindex": 524304383,
      "oper-state": "up",
      "last-change": "2019-07-12T16:53:39.291Z",
      "statistics": {
        "in-octets": "4545395",
        "in-unicast-pkts": "1178",
        "in-broadcast-pkts": "130",
        "in-multicast-pkts": "27560",
        "in-discards": "0",
        "in-errors": "0",
        "in-unknown-protos": "0",
        "in-fcs-errors": "0",
        "out-octets": "1735990",
        "out-unicast-pkts": "1125",
        "out-broadcast-pkts": "38",
        "out-multicast-pkts": "9187",
        "out-discards": "0",
        "out-errors": "0",
        "carrier-transitions": "1"
      },
      "ethernet": {
        "hw-mac-address": "02:42:AC:12:00:05",
        "statistics": {
          "in-mac-control-frames": "0",
          "in-mac-pause-frames": "0",
          "in-oversize-frames": "0",
          "in-jabber-frames": "0",
          "in-fragment-frames": "0",
          "in-crc-errors": "0",
          "out-mac-control-frames": "0",
          "out-mac-pause-frames": "0"
        }
      },
      "subinterface": [
        {
          "index": 0,
          "admin-state": "enable",
          "ip-mtu": 1500,
          "ifindex": 524288000,
          "oper-state": "up",
          "last-change": "2019-07-12T16:53:39.291Z",
          "ipv4": {
            "allow-directed-broadcast": false,
            "dhcp-client": true,
            "address": [
              {
                "ip-prefix": "172.18.0.5/24",
                "origin": "dhcp"
              }
            ],
            "srl_nokia-interfaces-nbr:arp": {
              "timeout": 14400,
              "neighbor": [
                {
                  "ipv4-address": "172.18.0.1",
                  "link-layer-address": "02:42:90:06:D7:26",
                  "origin": "dynamic",
                  "expiration-time": "2019-07-15T21:37:28.987Z"
                },
                {
                  "ipv4-address": "172.18.0.2",
                  "link-layer-address": "02:42:AC:12:00:02",
                  "origin": "dynamic",
                  "expiration-time": "2019-07-16T00:44:17.673Z"
                },
                {
                  "ipv4-address": "172.18.0.3",
                  "link-layer-address": "02:42:AC:12:00:03",
                  "origin": "dynamic",
                  "expiration-time": "2019-07-16T01:20:48.600Z"
                },
                {
                  "ipv4-address": "172.18.0.4",
                  "link-layer-address": "02:42:AC:12:00:04",
                  "origin": "dynamic",
                  "expiration-time": "2019-07-16T01:20:48.597Z"
                },
                {
                  "ipv4-address": "172.18.0.6",
                  "link-layer-address": "02:42:AC:12:00:06",
                  "origin": "dynamic",
                  "expiration-time": "2019-07-16T01:20:48.599Z"
                }
              ]
            }
          },
          "ipv6": {
            "dhcp-client": true,
            "address": [
              {
                "ip-prefix": "2001:172:18::5/80",
                "origin": "dhcp",
                "status": "preferred"
              },
              {
                "ip-prefix": "fe80::42:acff:fe12:5/64",
                "origin": "link-layer",
                "status": "preferred"
              }
            ],
            "srl_nokia-interfaces-nbr:neighbor-discovery": {
              "dup-addr-detect": true,
              "reachable-time": 30,
              "stale-time": 14400
            }
          }
        }
      ]
    }
  ],
  "id": 0,
  "jsonrpc": "2.0"
}

Multiple get request

{
  "jsonrpc": "2.0",
  "id": 0,
  "method": "get",
  "params": {
    "commands": [
      {
        "path": "/interface[name=mgmt0]",
        "datastore": "state",
        "recursive": false
      },
      {
        "path": "/interface[name=ethernet-1/10]",
        "datastore": "state",
        "recursive": false
      }
    ]
  }
}

Response (multiple get)

{
  "result": [
    {
      "name": "mgmt0",
      "admin-state": "enable",
      "mtu": 1514,
      "ifindex": 524304383,
      "oper-state": "up",
      "last-change": "2019-07-12T16:53:39.291Z"
    },
    {
      "name": "ethernet-1/10",
      "description": "dut2-dut4-2",
      "admin-state": "enable",
      "mtu": 9232,
      "ifindex": 180223,
      "oper-state": "up",
      "last-change": "2019-07-12T16:54:15.602Z"
    }
  ],
  "id": 0,
  "jsonrpc": "2.0"
}

JSON set examples

The set method allows you to set candidate configuration. The following examples are shown:

multiple set method using update and replace
set method using path-keywords
set method using an alternative update

Multiple set with update and replace request

{
  "jsonrpc": "2.0",
  "id": 0,
  "method": "set",
  "params": {
     "commands": [
        {
           "action": "update",
           "path": "/interface[name=mgmt0]/description:my-description"
        },
        {
           "action": "replace",
           "path": "/interface[name=mgmt0]/subinterface[index=0]/description:my-subdescription"
        }
     ]
  }
}

Response (multiple set)

{
  "result": {},
  "id": 0,
  "jsonrpc": "2.0"
}

set using path keywords request

{
  "jsonrpc": "2.0",
  "id": 0,
  "method": "set",
  "params": {
    "commands": [
      {
        "action": "update",
        "path": "/interface[name={name}]/description:my-description",
        "path-keywords": {
          "name": "mgmt0"
        }
      },
      {
        "action": "replace",
        "path": "/interface[name={name}]/subinterface[index={index}]/description:my-subdescription",
        "path-keywords": {
          "name": "mgmt0",
          "index": "0"
        }
      }
    ]
  }
}

Response (set using path-keywords)

{
  "result": {},
  "id": 0,
  "jsonrpc": "2.0"
}

set using alternative update (specifying a value) request

{
  "jsonrpc": "2.0",
  "id": 0,
  "method": "set",
  "params": {
    "commands": [
      {
        "action": "update",
        "path": "/interface[name=mgmt0]",
        "value": {
          "description": "my-description",
          "subinterface": {
            "index": "0",
            "description": "my-subdescription"
          }
        }
      }
    ]
  }
}

Response (set using alternative update)

{
  "result": {},
  "id": 0,
  "jsonrpc": "2.0"
}

JSON delete example

The set method allows you to use an action delete command to delete nodes or leafs within a configuration.

The following example shows a multiple set delete request to delete the specified paths.

Multiple set method delete request

{
  "jsonrpc": "2.0",
  "id": 0,
  "method": "set",
  "params": {
    "commands": [
      {
        "action": "delete",
        "path": "/interface[name=mgmt0]/description"
      },
      {
        "action": "delete",
        "path": "/interface[name=mgmt0]/subinterface[index=0]/description"
      }
    ]
  }
}

Response (multiple set delete)

{
  "result": {},
  "id": 0,
  "jsonrpc": "2.0"
}

JSON validate example

The validate method allows you to verify that the system will accept a configuration transaction before applying it to the system. The ‛delete’, ‛replace’, and ‛update’ actions can be used with the validate method. The following examples are shown:

validate request to delete a specified path.
validate request to update and replace a specified path.

validate a delete request

{
  "jsonrpc": "2.0",
  "id": 0,
  "method": "validate",
  "params": {
    "commands": [
      {
        "action": "delete",
        "path": "/interface[name=mgmt0]/description"
      }
    ],
    "datastore": "candidate"
  }
}

Response (validate delete)

{
  "result": {},
  "id": 0,
  "jsonrpc": "2.0"
}

validate an update and replace request

{
    "jsonrpc": "2.0",
    "id": 0,
    "method": "validate",
    "params": {
        "commands": [
            {
                "action": "update",
                "path": "/interface[name=mgmt0]/description:my-description"
            },
            {
                "action": "replace",
                "path": "/interface[name=mgmt0]/subinterface[index=0]
 /description:my-subdescription"
            }
        ]
    }
}

Response (validate update and delete)

{
  "result": {},
  "id": 0,
  "jsonrpc": "2.0"
}

JSON CLI example

The cli method allows you to run CLI commands, including the global tools command for a YANG modeled action. The tools command uses the YANG path of the action, in the same form as the MD-CLI. The cli method can also run commands added to the system with Python plug-ins or aliases.

The following examples are shown:

JSON cli command request.
JSON cli command requesting the output format as text.

You can optionally define these output formats: json, text, or table. JSON is the default.

CLI method input request

{
  "jsonrpc": "2.0",
  "id": 0,
  "method": "cli",
  "params": {
    "commands": [
      "enter candidate",
      "info interface mgmt0"
    ]
  }
}

Response (CLI input)

{
  "result": [
    {},
    {
      "interface": [
        {
          "name": "mgmt0",
          "description": "my-description",
          "admin-state": "enable",
          "subinterface": [
            {
              "index": 0,
              "description": "my-subdescription",
              "admin-state": "enable",
              "ipv4": {
                "dhcp-client": true
              },
              "ipv6": {
                "dhcp-client": true
              }
            }
          ]
        }
      ]
    }
  ],
  "id": 0,
  "jsonrpc": "2.0"
}

CLI method input request with output formatting

{
  "jsonrpc": "2.0",
  "id": 0,
  "method": "cli",
  "params": {
    "commands": [
      "enter candidate",
      "info interface mgmt0"
    ],
    "output-format": "text"
  }
}

Response (CLI with output formatting)

{
  "result": [
    "",
    "    interface mgmt0 {\n      description my-description\n        
admin-state enable\n              subinterface 0 {\n            
description my-subdescription\n   admin-state enable\n       ipv4 {\n
dhcp-client true\n                }\n                        ipv6 {\n 
dhcp-client true\n                }\n                        }\n      }\n"
  ],
  "id": 0,
  "jsonrpc": "2.0"
}

JSON action examples

The action method executes a YANG-modeled action using structured JSON input and output that conform to the YANG schema. The encoding is not CLI text. This method is separate from the action field on the set and validate methods.

Set path to the action node. Use an absolute path or an origin-qualified path. Include the exact key of every keyed list in the path.

Optionally set input to a JSON object mapped from the YANG input leaves. The output is a JSON object mapped from the YANG output leaves. The response does not include srl-unstructured-output. See SR Linux CLI Plug-In Guide for more information about srl-unstructured-output.

Errors are returned as a JSON-RPC error object with the same failure semantics as other management APIs, including authorization, validation, and handler errors.

Action method request - IPv4


ipv4:
Request:
{
  "jsonrpc": "2.0",
  "id": 0,
  "method": "action",
  "params": {
    "commands": [
      {
        "path": "/system/ipfix/flow-cache/dump-flows",
        "payload": {
          "ipv4": [null]
        }
      }
    ],
    "output-format": "json"
  }
}

Response (action method)

{
  "jsonrpc": "2.0",
  "id": 0,
  "result": [
    {
      "flow-dump": "type: 1\nNo IPv4 unicast flow data has been recorded by cflowd\n"
    }
  ]
}

Action method request - IPv6

ipv6:

Request:
{
  "jsonrpc": "2.0",
  "id": 0,
  "method": "action",
  "params": {
    "commands": [
      {
        "path": "/system/ipfix/flow-cache/dump-flows",
        "payload": {
          "ipv6": [null]
        }
      }
    ],
    "output-format": "json"
  }
}

Response

Response:
{
  "jsonrpc": "2.0",
  "id": 0,
  "result": [
    {
      "flow-dump": "type: 2\n\nThe top 20 IPv6 unicast flows seen by cflowd are:\n\n     Current Time: 10/13/2026 23:35:00\nLast Cleared Time: 10/13/2026 21:52:17\n   ifIndexContext: global\n\nSrcIP                                      Intf/Ingr    S-Port   I-vRtrID    ToS\nDstIP                                      Intf/Egr     D-Port   E-vRtrID  Flags\n Nexthop                                   Pkts         Pkt-Size Proto      Time\n--------------------------------------------------------------------------------\n3ffe::13:13:13:3                           98328        0        10284      0x00\n3ffe::12:12:12:2                           0            0        0          0x00\n ::                                        3418         238      58           34\n3ffe::13:13:13:3                           98328        0        10284      0x00\n3ffe::12:12:12:2                           0            0        0          0x00\n ::                                        3400         238      58           33\n3ffe::13:13:13:3                           98328        0        10284      0x00\n3ffe::12:12:12:2                           0            0        0          0x00\n ::                                        3001         238      58           30\n--------------------------------------------------------------------------------\n\n"
    }
  ]
}