VyOS API

For instructions on configuring and enabling the API, see HTTP API.

Authentication

All endpoints, except one, accept HTTP POST requests. The API key must be provided as the key field in the form data. The only public endpoint accepts HTTP GET requests and supports optional query parameters.

Below are examples of API requests in cURL and Python. All other code examples in this documentation use 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 API endpoint that does not require authentication and can be accessed by anonymous users. The info endpoint returns general system information, including the VyOS version, system hostname, and a welcome banner.

This endpoint accepts only 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
}

Query parameters

This endpoint accepts two optional query parameters, version and hostname. Each parameter accepts values convertible to Boolean (e.g., yes/no, 1/0, or true/false) to control the inclusion of related fields in the response.

If no query parameters are provided, both parameters default to true.

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 either parameter is set to a value corresponding to false, its field is returned as an empty string in the response:

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

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

You do not need to specify both parameters if you want to hide only one. Any missing query parameter defaults to 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
}

Note that while you can disable output for both hostname and version, the banner is always included in the response.

Important

The endpoint accepts ONLY hostname and version query parameters. Including any other parameters results in an 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
}

Values passed to the query string are validated to ensure they are strictly Boolean. Other data types are not accepted.

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

The /retrieve endpoint returns either specific parts or the entire configuration.

To retrieve the entire 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 (shortened)
{
   "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 retrieve a specific configuration part, such as system syslog, specify the desired path.

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 only need the value of a multi-valued node, use the returnValues operation.

For example, to 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'

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

To check whether a configuration path exists, use the exists operation. It returns true for 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
}

It returns false for a non-existing 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 runs the 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'

response:
{
  "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'

response:
{
  "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'

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

/image

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

To 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'

response (shortened):
{
   "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
}

To 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 runs operational mode commands and returns the resulting output.

For example, to show the installed images:

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 runs 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

The /configure endpoint accepts set, delete, and comment commands.

To apply a set 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
}

To apply a delete 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 processes each request in a session and commits it. For components such as DHCP and PPPoE servers, IPsec, VXLAN, and other tunnels, VyOS requires the entire configuration block for a commit.

The endpoint can process multiple commands if 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 /config-file endpoint allows you to save, load, or merge a configuration.

If you do not specify a file during the save operation, the configuration is automatically saved 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
}

To 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
}

For both load and merge operations, you can pass a string in the request body. 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, a commit command is executed automatically after a successful request operation (set, delete, load, merge, or a list of set and delete operations).

Alternatively, you can initiate a commit-confirm. Include the confirm_time field in your request and set it to an integer greater than 0.

The following example uses the JSON format for brevity, though the standard form data format is equally valid:

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
}

If not confirmed within the specified time, the committed changes will be reverted. 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 the commit is not confirmed, the revert behavior is controlled 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)