rConfig V8 Core REST API guide

rConfig V8 Core ships a token-authenticated REST API for programmatic access to your network configuration data. Use it to manage devices, retrieve and search configurations, trigger on-demand backups, and manage supporting data (templates, categories, commands, vendors, tags, tasks, users) from scripts, schedulers, or other systems.

The API is available from V8 Core 8.2.3 onwards.

Full endpoint reference lives in the app

This page covers authentication and the essentials. The complete, interactive endpoint reference (every route, with parameters, example requests, and example responses) is built into the application under Settings → REST API → Documentation, at /settings/restapi-docs/get-started, and ships with your installed version.

Generating an API token

All requests are authenticated with an API token that you create in the web interface:

1. Go to Settings → REST API.
2. Click New Token, give it a descriptive name, and generate it.
3. Copy the token immediately: it is shown only once. If you lose it, delete it and create a new one.

To revoke access, delete the token from the same screen. Revocation takes effect immediately for any client using that token.

Treat tokens as secrets

An API token grants full access to the REST API. Never commit tokens to version control, embed them in client-side code, or expose them in logs. Store them in a secrets manager or environment variable, always use HTTPS, and rotate or revoke tokens regularly.

Authentication

Send your token in the apitoken request header on every call:

curl -H "apitoken: YOUR_API_TOKEN" \
  -H "Accept: application/json" \
  https://your-rconfig-server.com/api/v1/devices

Alternatively, you can pass it as an apitoken query parameter (useful for quick browser testing of GET endpoints):

https://your-rconfig-server.com/api/v1/devices?apitoken=YOUR_API_TOKEN

The same token works for both the v1 and v2 endpoints. A missing or invalid token returns 401 Unauthorized.

Note

rConfig uses the apitoken header, not an Authorization: Bearer header. Sending the deprecated api_token parameter returns 422: use apitoken.

JavaScript example

fetch("https://your-rconfig-server.com/api/v1/devices", {
  headers: {
    Accept: "application/json",
    "Content-Type": "application/json",
    apitoken: "YOUR_API_TOKEN",
  },
})
  .then((response) => response.json())
  .then((data) => console.log(data));

Versioning and base URLs

The API is exposed under two version prefixes:

Version	Base URL	Focus
v1	https://your-rconfig-server.com/api/v1/	Broad CRUD across devices, configs, templates, categories, commands, vendors, tags, tasks, users, and device credentials
v2	https://your-rconfig-server.com/api/v2/	Newer endpoints: device summary/enable/disable, config search and status, config changes, and dashboard health

The version is part of the URL path and is required on every request. See the in-app documentation for the exact endpoints available in each version.

Responses

Endpoints return JSON and use standard HTTP status codes:

• 200: success
• 401: missing or invalid API token
• 404: resource not found
• 422: validation error (the response body describes the failing fields)

Most endpoints wrap their payload in a consistent envelope:

{
  "success": true,
  "data": {},
  "message": "Success"
}

List endpoints are paginated; pass perPage (and page) to control page size. Some list endpoints also support filtering and sorting query parameters: the in-app reference documents these per endpoint.

What you can do

At a glance, the REST API lets you:

• Devices: list, view, create, update, delete, enable/disable, and a backup summary (v2).
• Configurations: list, view (including the config text), delete, search across stored configs, and fetch configs by device or status. Config change diffs are available in v2. See Working with configurations.
• On-demand backups: trigger a download for a device (/api/v1/download-now/{id}).
• Supporting data: full CRUD for templates, categories, commands, vendors, tags, tasks, users, and device credentials.
• System: basic dashboard and health information.

Device credential secrets are masked

The device credential endpoints do not return readable secrets. On both GET /api/v1/device-credentials and GET /api/v1/device-credentials/{id}, the password and enable password come back masked (first two characters, then asterisks), so the API can inventory credential sets but cannot be used to read a stored device password back out. Writes still accept cleartext values, and the response confirms the change without echoing the secret. Masking is unconditional and is not affected by the MASK_DEVICE_CREDENTIALS setting, which governs the device endpoints only. See Manage device credentials for the full detail.

Tip

For the authoritative list of routes, parameters, and example payloads, open Settings → REST API → Documentation in your rConfig instance. It ships with your installed version, so it reflects the endpoints that version provides.

Working with configurations (v2)

The v2 configs endpoints are the documented way to pull stored configurations into another system, such as an NMS or an audit script.

Version requirement

includeConfig and the device_id, device_name, and created_at filters on /api/v2/configs were listed in the in-app reference in earlier releases but did not work until V8 Core 8.2.18. On older versions includeConfig is ignored and those filters return 400.

List configs

curl -s -H "apitoken: YOUR_API_TOKEN" \
  "https://your-rconfig-server.com/api/v2/configs?filter[device_id]=1001&filter[latest_version]=1&includeConfig=true"

Returns a paginated list, newest first. This endpoint returns the paginator directly (current_page, data, total, next_page_url, and so on), not the success/data/message envelope.

Parameter	Description
filter[device_id]	Exact device ID. Accepts a comma-separated list, for example 1001,1002.
filter[device_name]	Partial match on the device name.
filter[command]	Exact command, for example show run. Accepts a comma-separated list.
filter[download_status]	0 failed, 1 success, 2 unknown.
filter[latest_version]	1 returns only the newest version of each device and command pair.
filter[created_at]	A date (YYYY-MM-DD). Matches configs downloaded at any time on that day.
filter[created_at_between]	Two dates separated by a comma, for example 2026-01-01,2026-01-31.
filter[q]	Partial match on the config ID or device name.
sort	id, device_name, command, download_status, or created_at. Prefix with - for descending. Defaults to -created_at.
fields	Comma-separated columns to return, for example id,device_id,command,created_at.
includeConfig	true adds a config field to each row containing the file contents.
perPage, page	Page size (default 10) and page number.

An unknown filter, sort, or field returns 400 with a message listing the allowed values.

includeConfig reads each file from disk, so keep perPage modest when you use it. If a file is missing or unreadable, the row is still returned and config holds a message such as File does not exist at path ... instead of the contents.

Get a single config

curl -s -H "apitoken: YOUR_API_TOKEN" \
  "https://your-rconfig-server.com/api/v2/configs/42?includeConfig=true"

Returns the config’s metadata (id, device_id, device_name, device_category, command, type, download_status, config_location, config_filename, config_filesize, config_hash, config_version, latest_version, start_time, end_time, duration, created_at, updated_at). With includeConfig=true it also includes config, the file contents as a string. An unknown ID returns 404.

Search config contents

GET or POST /api/v2/configs/search finds lines that contain a term and returns each match with two lines of context either side.

curl -s -X POST -H "apitoken: YOUR_API_TOKEN" -H "Content-Type: application/json" \
  -d '{"searchTerm": "snmp-server community", "devices": [1001, 1002], "limit": 20}' \
  https://your-rconfig-server.com/api/v2/configs/search

Parameter	Description
searchTerm	Required, at least 3 characters. search_term is accepted as an alias.
devices	Array of device IDs to limit the search to.
commands	Array of command IDs or command strings, for example [1, "show run"].
dateFrom, dateTo	YYYY-MM-DD bounds on the download date. from_date and to_date are accepted as aliases.
case_sensitive	true for a case-sensitive match. Defaults to false.
limit	Maximum number of matching configs to return. Without it, every matching config is returned.

The response uses the standard envelope. Each item in data has id, device_id, config_location, config_filename, config_command, config_date, device (id, device_name, device_ip), and matches, an array of line_number, line_text, and context. Search runs against every stored version, not just the latest, so use dateFrom or limit to keep large searches fast.

Note

Multi-term search (criteria, criteria_mode), category, tag, and vendor filters, and configurable context lines are not part of the V8 Core search API. They are available in the Pro and Enterprise editions, documented at docs.rconfig.com.

Count configs by status

GET /api/v2/configs/status/{deviceid}/{status} returns data.count for a device ID (or all) and a status of failed, success, unknown, or all.

What’s next

• System settings reference: where the REST API token screen lives, alongside other administrative settings.
• Search your stored configurations: the UI counterpart to the config search endpoints the API exposes.
• Add and manage devices: the device records the API lists, creates, and backs up on demand.