VyOS API

For configuration and enabling the API see HTTP API

Authentication

All endpoints except one listen on HTTP POST requests and the API KEY must set as key in the formdata. The only public endpoint listens to HTTP GET request and takes optional query parameters.

Below see one example for curl and one for python. The rest of the documentation is reduced to curl.

curl --location --request POST 'https://vyos/retrieve' \
--form data='{"op": "showConfig", "path": []}' \
--form key='MY-HTTPS-API-PLAINTEXT-KEY'

import requests
url = "https://vyos/retrieve"
payload={'data': '{"op": "showConfig", "path": []}',
         'key': 'MY-HTTPS-API-PLAINTEXT-KEY'
        }
headers = {}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)

API Endpoints

/info

This is the only endpoint provided by the API service that does not require authentication and can be queried by anonymous users. Requesting the info endpoint you obtain general information about the system, namely the VyOS version, the system host name and a welcome banner for anonymous users.

This endpoint responds only to HTTP GET requests.

curl --location --request GET 'https://vyos/info'

response
{
    "success": true,
    "data": {
        "version": "1.5-rolling",
        "hostname: "vyos"
        "banner": "Welcome to VyOS"
    },
    "error": null
}

This endpoint can take two optional query parameters - version and hostname. These parameters accept all values that can be converted to Boolean - e.g. yes/no, 1/0, true/false etc, and they dictate whether to include the respective values into the response.

If request is sent without any query parameters, the endpoints treats them as if they are set to true by default:

curl --location --request GET 'https://vyos/info?version=1&hostname=1'

response {
    "success": true,
    "data": {
        "version": "1.5-rolling",
        "hostname": "vyos",
        "banner": "Welcome to VyOS"
    },
    "error": null
}

If any of the parameters is set to a value that corresponds to false, the response object will have an empty string instead of the respective value:

curl --location --request GET 'https://vyos/info?version=0&hostname=1'

response {
    "success": true,
    "data": {
        "version": "",
        "hostname": "vyos",
        "banner": "Welcome to VyOS"
    },
    "error": null
}

Please note, that there is no need to specify both parameters if you want to hide just one of the fields - a missing query parameter is treated as true:

curl --location --request GET 'https://vyos/info?hostname=no'

response {
    "success": true,
    "data": {
        "version": "1.5-rolling",
        "hostname": "",
        "banner": "Welcome to VyOS"
    },
    "error": null
}

Please note, that while you can disable output for both hostname and version, the banner is included into the response in any case.

Important: The endpoint accepts ONLY hostname and version query parameters. Including any other besides them, or instead of them, will respond with HTTP 400 Bad Request:

curl --location --request GET \
    'https://192.168.56.119/info?hostname=1&url=https://evilsite.com'

response {
    "success": false,
    "error": "{'type': 'extra_forbidden', 'loc': ('query', 'url'), 'msg': 'Extra inputs are not permitted', 'input': 'https://evilsite.com'}",
    "data": null
}

As well as the values passed to the query string are validated to ensure they are strictly Boolean and won’t accept any other data type:

curl --location --request GET 'https://vyos/info?hostname=1; eval"sudo rm -rf /"

response
{
    "success": false,
    "error": "{'type': 'bool_parsing', 'loc': ('query', 'hostname'), 'msg': 'Input should be a valid boolean, unable to interpret input', 'input': '1; eval \"sudo rm -rf /\"'}",
    "data": null
}

/retrieve

With the retrieve endpoint you get parts or the whole configuration.

To get the whole configuration, pass an empty list to the path field

curl --location --request POST 'https://vyos/retrieve' \
--form data='{"op": "showConfig", "path": []}' \
--form key='MY-HTTPS-API-PLAINTEXT-KEY'


response (shorted)
{
   "success": true,
   "data": {
      "interfaces": {
            "ethernet": {
               "eth0": {
                  "address": "dhcp",
                  "duplex": "auto",
                  "hw-id": "50:00:00:01:00:00",
                  "speed": "auto"
               },
               "eth1": {
                  "duplex": "auto",
                  "hw-id": "50:00:00:01:00:01",
                  "speed": "auto"
   ...
   },
   "error": null
}

To only get a part of the configuration, for example system syslog.

curl -k --location --request POST 'https://vyos/retrieve' \
--form data='{"op": "showConfig", "path": ["system", "syslog"]}' \
--form key='MY-HTTPS-API-PLAINTEXT-KEY'


response:
{
   "success": true,
   "data": {
      "global": {
            "facility": {
               "all": {
                  "level": "info"
               },
               "protocols": {
                  "level": "debug"
               }
            }
      }
   },
   "error": null
}

if you just want the Value of a multi-valued node, use the returnValues operation.

For example, get the addresses of a dum0 interface.

curl -k --location --request POST 'https://vyos/retrieve' \
--form data='{"op": "returnValues", "path": ["interfaces","dummy","dum0","address"]}' \
--form key='MY-HTTPS-API-PLAINTEXT-KEY'

respone:
{
   "success": true,
   "data": [
      "10.10.10.10/24",
      "10.10.10.11/24",
      "10.10.10.12/24"
   ],
   "error": null
}

To check existence of a configuration path, use the exists operation.

For example, check an existing path:

curl -k --location --request POST 'https://vyos/retrieve' \
--form data='{"op": "exists", "path": ["service","https","api"]}' \
--form key='MY-HTTPS-API-PLAINTEXT-KEY'

response:
{
   "success": true,
   "data": true,
   "error": null
}

versus a non-existent path:

curl -k --location --request POST 'https://vyos/retrieve' \
--form data='{"op": "exists", "path": ["service","non","existent","path"]}' \
--form key='MY-HTTPS-API-PLAINTEXT-KEY'

response:
{
   "success": true,
   "data": false,
   "error": null
}

/reset

The reset endpoint run a reset command.

curl --location --request POST 'https://vyos/reset' \
--form data='{"op": "reset", "path": ["ip", "bgp", "192.0.2.11"]}' \
--form key='MY-HTTPS-API-PLAINTEXT-KEY'

respone:
{
  "success": true,
  "data": "",
  "error": null
}

/reboot

To initiate a reboot use the reboot endpoint.

curl --location --request POST 'https://vyos/reboot' \
--form data='{"op": "reboot", "path": ["now"]}' \
--form key='MY-HTTPS-API-PLAINTEXT-KEY'

respone:
{
  "success": true,
  "data": "",
  "error": null
}

/poweroff

To power off the system use the poweroff endpoint.

curl --location --request POST 'https://vyos/poweroff' \
--form data='{"op": "poweroff", "path": ["now"]}' \
--form key='MY-HTTPS-API-PLAINTEXT-KEY'

respone:
{
  "success": true,
  "data": "",
  "error": null
}

/image

To add or delete an image, use the /image endpoint.

add an image

curl -k --location --request POST 'https://vyos/image' \
--form data='{"op": "add", "url": "https://downloads.vyos.io/rolling/current/amd64/vyos-rolling-latest.iso"}' \
--form key='MY-HTTPS-API-PLAINTEXT-KEY'

respone (shorted):
{
   "success": true,
   "data": "Trying to fetch ISO file from https://downloads.vyos.io/rolling-latest.iso\n
            ...
            Setting up grub configuration...\nDone.\n",
   "error": null
}

delete an image, for example 1.3-rolling-202006070117

curl -k --location --request POST 'https://vyos/image' \
--form data='{"op": "delete", "name": "1.3-rolling-202006070117"}' \
--form key='MY-HTTPS-API-PLAINTEXT-KEY'

response:
{
   "success": true,
   "data": "Deleting the \"1.3-rolling-202006070117\" image...\nDone\n",
   "error": null
}

/show

The /show endpoint is to show everything in the operational mode.

For example, show which images are installed.

curl -k --location --request POST 'https://vyos/show' \
--form data='{"op": "show", "path": ["system", "image"]}' \
--form key='MY-HTTPS-API-PLAINTEXT-KEY'

response:
{
   "success": true,
   "data": "The system currently has the following image(s) installed:\n\n
             1: 1.4-rolling-202102280559 (default boot)\n
             2: 1.4-rolling-202102230218\n
             3: 1.3-beta-202102210443\n\n",
   "error": null
}

/generate

The generate endpoint run a generate command.

curl -k --location --request POST 'https://vyos/generate' \
--form data='{"op": "generate", "path": ["pki", "wireguard", "key-pair"]}' \
--form key='MY-HTTPS-API-PLAINTEXT-KEY'

response:
{
   "success": true,
   "data": "Private key: CFZR2eyhoVZwk4n3JFPMJx3E145f1EYgDM+ubytXYVY=\n
            Public key: jjtpPT8ycI1Q0bNtrWuxAkO4k88Xwzg5VHV9xGZ58lU=\n\n",
   "error": null
}

/configure

You can pass a set, delete or comment command to the /configure endpoint.

set a single command

curl -k --location --request POST 'https://vyos/configure' \
--form data='{"op": "set", "path": ["interfaces", "dummy", "dum1", "address", "10.11.0.1/32"]}' \
--form key='MY-HTTPS-API-PLAINTEXT-KEY'

response:
{
   "success": true,
   "data": null,
   "error": null
}

delete a single command

curl -k --location --request POST 'https://vyos/configure' \
--form data='{"op": "delete", "path": ["interfaces", "dummy", "dum1", "address", "10.11.0.1/32"]}' \
--form key='MY-HTTPS-API-PLAINTEXT-KEY'

response:
{
   "success": true,
   "data": null,
   "error": null
}

The API pushes every request to a session and commit it. But some of VyOS components like DHCP and PPPoE Servers, IPSec, VXLAN, and other tunnels require full configuration for commit. The endpoint will process multiple commands when you pass them as a list to the data field.

curl -k --location --request POST 'https://vyos/configure' \
--form data='[{"op": "set","path":["interfaces","vxlan","vxlan1","remote","203.0.113.99"]}, {"op": "set","path":["interfaces","vxlan","vxlan1","vni","1"]}]' \
--form key='MY-HTTPS-API-PLAINTEXT-KEY'

response:
{
   "success": true,
   "data": null,
   "error": null
}

/config-file

The endpoint /config-file is to save or load a configuration.

Save a running configuration to the startup configuration. When you don’t specify the file when saving, it saves to /config/config.boot.

curl -k --location --request POST 'https://vyos/config-file' \
--form data='{"op": "save"}' \
--form key='MY-HTTPS-API-PLAINTEXT-KEY'

response:
{
   "success": true,
   "data": "Saving configuration to '/config/config.boot'...\nDone\n",
   "error": null
}

Save a running configuration to a file.

curl -k --location --request POST 'https://vyos/config-file' \
--form data='{"op": "save", "file": "/config/test.config"}' \
--form key='MY-HTTPS-API-PLAINTEXT-KEY'

response:
{
   "success": true,
   "data": "Saving configuration to '/config/test.config'...\nDone\n",
   "error": null
}

To Load a configuration file.

curl -k --location --request POST 'https://vyos/config-file' \
--form data='{"op": "load", "file": "/config/test.config"}' \
--form key='MY-HTTPS-API-PLAINTEXT-KEY'

response:
{
   "success": true,
   "data": null,
   "error": null
}

To Merge a configuration file.

curl -k --location --request POST 'https://vyos/config-file' \
--form data='{"op": "merge", "file": "/config/test.config"}' \
--form key='MY-HTTPS-API-PLAINTEXT-KEY'

response:
{
   "success": true,
   "data": null,
   "error": null
}

In either of the last two cases, one can pass a string in the body of the request, for example:

curl -k --location --request POST 'https://vyos/config-file' \
--form data='{"op": "merge", "string": "interfaces {\nethernet eth1 {\naddress "192.168.2.137/24"\ndescription "test"\n}\n}\n"}' \
--form key='MY-HTTPS-API-PLAINTEXT-KEY'

response:
{
   "success": true,
   "data": null,
   "error": null
}

Commit-confirm

For the previous two endpoints discussed, a commit command is implicit following a succesful request operation (set | delete | load | merge, or a list of set and delete operations). One can instead request a commit-confirm command by including the field confirm_time of type int > 0. An example follows, in the alternative JSON format, for brevity, although the standard form-data format is fine:

curl -k -X POST -d '{"key": "MY-HTTPS-API-PLAINTEXT-KEY", "op": "merge", "string": "interfaces {\nethernet eth1 {\naddress '192.168.137.1/24'\ndescription 'internal'\n}\n}\n", "confirm_time": 1}' https://vyos/config-file

response:
{
   "success": true,
   "data": "Initialized commit-confirm; 1 minutes to confirm before reload\n",
   "error": null
}

The committed changes will be reverted at the timeout unless confirmed. To confirm and keep the changes:

curl -k -X POST -d '{"key": "MY-HTTPS-API-PLAINTEXT-KEY", "op": "confirm"}' https://vyos/config-file

response:
{
   "success": true,
   "data": "Reload timer stopped\n",
   "error": null
}

If allowed to revert to the previous configuration, the manner in which changes are reverted is governed by:

vyos@vyos# set system config-management commit-confirm action
Possible completions:
   reload               Reload previous configuration if not confirmed
   reboot               Reboot to saved configuration if not confirmed (default)