Skip to content
Guides & References

How the rConfig REST API behaves

What to expect from the rConfig REST API: v1 and v2, paging and filters, response shapes, errors, and calls that start work in the background.

API & DeveloperUpdated
On this page

How the rConfig REST API behaves

The REST API grew over several releases, so v1 and v2 endpoints don’t all behave the same way. This page covers what a client needs to cope with: which version to call, how lists are paged and filtered, what responses look like, and which calls finish straight away and which only start work. The full endpoint list is in the in-app API docs and the OpenAPI file.


Every request

  • Base URLs are https://<your-rconfig>/api/v1/ and https://<your-rconfig>/api/v2/.
  • Send the token in the apitoken header. Every response is JSON, whatever Accept header you send.
  • GET /api/v1/apitest or GET /api/v2/apitest checks a token without needing any ability. Use it as a connection test.
Terminal window
curl -sS -H "apitoken: $RCONFIG_TOKEN" https://rconfig.example.com/api/v2/apitest

v1 or v2?

v2 is the better choice where it covers what you need: it pages and filters. Some things only exist in v1.

You need Use
List or look up devices v2 GET /devices, GET /devices/{id}
A backup summary across all devices v2 GET /devices/summary
Create or update a device v1 POST /devices, PUT /devices/{id}
Enable, disable or delete a device v2 POST /devices/{id}/enable, POST /devices/{id}/disable, DELETE /devices/{id}
List or read configs v2 GET /configs, GET /configs/{id}
Search config text v2 POST /configs/search
The diff for a config v2 GET /config-changes/by-config/{configId}
Start a backup now v1 GET /download-now/{deviceId}
Snippets, tasks, templates, categories, commands, vendors, tags, credentials v1
Policy compliance exports v2 GET /policy-compliance-*/…/export
Health checks v2 GET /dashboard/health-latest

The OpenAPI page has the full coverage table.


Paging and filtering

v2 list endpoints return a standard page object. The items are in data, and the paging fields sit beside it:

{
"current_page": 1,
"data": [ { "id": 12, "device_name": "edge-rtr-01" } ],
"last_page": 4,
"next_page_url": "https://rconfig.example.com/api/v2/devices?page=2",
"per_page": 100,
"total": 361
}

Follow next_page_url until it’s null, or count up page to last_page.

Endpoint Page size parameter Default Filters
v2 /devices per_page (or perPage), at most 100 10 filter[device_name] (contains), filter[device_ip] (exact), filter[created_at]
v2 /configs perPage 10 filter[device_id], filter[device_name], filter[command], filter[download_status], filter[latest_version], filter[created_at], filter[config_downloaded] (all exact except device_name)

Both sort newest first.

v1 list endpoints don’t page: GET /api/v1/devices returns every device the token can see in one response, wrapped as {"success": true, "data": [...], "message": "..."}. Prefer v2 for lists on large estates.


Useful fields on v2 devices

Each device from v2 GET /devices carries two fields worth knowing:

Field Meaning
last_backup_status Status of the device’s most recent config: 1 downloaded and passed its integrity check (or none applies), 2 downloaded but integrity unknown, 3 downloaded but failed its integrity check, 0 download failed, null never backed up
last_backup_at When that config download finished, as YYYY-MM-DD HH:MM:SS in rConfig’s local time (its TIMEZONE setting), with no zone attached

The backup coverage recipe is built on them. Pass with_credentials=false so device passwords aren’t returned; see tokens and least privilege.


Reading configs and diffs

  • GET /api/v2/configs/{id}?includeConfig=true adds the config text in a config field. Without includeConfig you get only the metadata.
  • When config obfuscation is on, the text is masked as it is in the UI. raw=true returns it unmasked only if the server allows it (CONFIG_OBFUSCATION_API_ALLOW_RAW).
  • GET /api/v2/config-changes/by-config/{configId} returns the stored diff for that config, as the HTML rConfig shows in the UI, in data.config_diff. It returns data: null with status 200 when there’s no diff (the first version, or an unchanged download). Add mode=side for a side-by-side rendering.

If you need a plain-text diff, fetch the two configs with includeConfig=true and compare them yourself, as the CI/CD change gate does.


Calls that only start work

Some calls hand the work to a background queue and return straight away. A success response means “started”, not “done”:

Call Returns How to know it finished
v1 GET /download-now/{deviceId} {"success": true, "message": "Download started for device id: 12"} Poll v2 GET /devices/{id} until last_backup_at is later than when you started
v1 GET /send-snippet/{snippetId}/{deviceId}, POST /snippets/{id}/deploy A started message Check the snippet result in rConfig, or watch for the snippet.sent webhook

Post-backup compliance (where an assignment has Run on backup on) also runs in the background after the download finishes. Its results appear in the compliance exports with the new config’s ID once it’s done.


Response shapes and errors

The two versions wrap responses differently, so check both forms in a client:

Situation What you get
v2 list The page object above
v2 single item The item itself, or {"success": true, "data": {...}} on the config-changes endpoints
v1 most calls {"success": true, "data": ..., "message": "..."}
Missing or wrong token 401
Valid token, missing ability 403 with Invalid ability provided.
Item that doesn’t exist, or the owner’s role can’t see 404
Validation failure on create or update 422 with the field errors
Wrong token parameter name (api_token) 422 with Token param name needs to be updated to apitoken.

The compliance export endpoints return a file (format=csv or format=xlsx, default xlsx), not JSON.


Type to search.