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/andhttps://<your-rconfig>/api/v2/. - Send the token in the
apitokenheader. Every response is JSON, whateverAcceptheader you send. GET /api/v1/apitestorGET /api/v2/apitestchecks a token without needing any ability. Use it as a connection test.
curl -sS -H "apitoken: $RCONFIG_TOKEN" https://rconfig.example.com/api/v2/apitestv1 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=trueadds the config text in aconfigfield. WithoutincludeConfigyou get only the metadata.- When config obfuscation is on, the text is masked as it is in the UI.
raw=truereturns 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, indata.config_diff. It returnsdata: nullwith status200when there’s no diff (the first version, or an unchanged download). Addmode=sidefor 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.