---
lastproofread: '2026-04-13'
---

(vyosapi)=

# VyOS API

For instructions on configuring and enabling the API, see {ref}`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.

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

```python
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.

```none
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`.

```none
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:

```none
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.

```none
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.
:::

```none
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.

```none
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.

```none
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.

```none
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:

```none
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:

```none
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:

```none
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
}
```

Note that `showConfig` returns an error (HTTP 400) for a path that is valid
in the schema but has no configuration under it:

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

response:
{
   "success": false,
   "data": null,
   "error": "Configuration under specified path is empty"
}
```

Automation that compares a desired state against a fresh or partially
configured system should either probe the path with `exists` first, or
treat this specific error as "no configuration present" rather than as a
failed request.


### /reset

The `/reset` endpoint runs the `reset` command.

```none
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.

```none
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.

```none
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:

```none
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`:

```none
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:

```none
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
}
```

The endpoint can also export the running configuration as flat `set`
commands, equivalent to the operational mode command
`show configuration commands`. This is convenient for mirroring, diffing,
or backing up a configuration:

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

response (shortened):
{
   "success": true,
   "data": "set interfaces ethernet eth0 address 'dhcp'\n
            set interfaces ethernet eth0 hw-id '50:00:00:01:00:00'\n
            set system host-name 'vyos'\n
            ...",
   "error": null
}
```


### /generate

The `/generate` endpoint runs a `generate` command.

```none
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:

```none
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:

```none
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.

Because every request is committed immediately, the fields of a single
configuration node cannot be staged across separate requests: everything the
commit validators require must arrive in the same request, passed as a list
of operations (see below). Common examples:

- `system task-scheduler task <name>`: `executable` together with
  `interval` (or `crontab-spec`).
- `nat destination rule <N>`: `translation` together with the other rule
  fields.
- `firewall ... rule <N>`: `action` in the request that creates the rule;
  `protocol` together with `port` or `port-group`.

Sending such fields in separate requests fails validation with errors such as
`Protocol must be defined if specifying a port or port-group` or
`must define either interval or crontab-spec`, because each request is
validated as a complete commit on its own. Likewise, setting an attribute
such as `description` on a rule that no request has created yet fails with
`Configuration path ... is not valid`.

The endpoint can process multiple commands if you pass them as a list to
the `data` field.

```none
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
}
```

A list of operations is applied and committed as a single transaction: if
any operation fails, nothing is committed *for that component*; partial
commits are possible for a list of operations comprising more than one
component. The error message will indicate the component and the missing
information or conflict.

:::{note}
The `/configure` endpoint commits changes to the running configuration but
does not save them to disk, and it does not accept `{"op": "save"}` (that
returns HTTP 400). To persist changes across reboots, send
`{"op": "save"}` to the `/config-file` endpoint.
:::


### /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`.

```none
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:

```none
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:

```none
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:

```none
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:

```none
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
}
```


## Bulk configuration

Large applies over the API (initial provisioning, firewall migrations with
hundreds of operations) benefit from a few precautions:

- Prefer several requests of moderate size over one very large list of
  operations. A very large single commit can run longer than the HTTP
  gateway allows and return a timeout even though the commit itself
  eventually succeeds — after a timeout, reconcile the configuration
  state (for example with `/retrieve`) before retrying, so an
  already-applied change is not replayed.
- Commits that reference `geoip` country codes or `remote-group` URLs are
  significantly more expensive than plain set operations, because they
  trigger database or remote-list processing. Apply those one per request.
- The request body size is limited by
  `service https request-body-size-limit` (1 MB by default); a very large
  operation list or `config-file` string can exceed it.
- Consider commit-confirm (below) as a safety net when reconfiguring a
  remote system.

## 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:

```none
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:

```none
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:

```none
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)
```