OpenAPI Specification

rConfig generates an OpenAPI 3.0.3 specification for each version of its REST API, built from the routes and validation rules of your own install. Import it into Postman or Insomnia to get a ready-made request collection, render it in Swagger UI for your team, or feed it to a code generator to build a typed client in Python, Go, or TypeScript.

From V8.2.1, the specification is produced by the rconfig:api-docs:build Artisan command. There is one file per API version, and both are written to disk on the rConfig server.

Note

The specification is never served over a URL. It lives under storage/app/api-docs/ on the server, and you copy it from there to wherever you need it. This keeps your endpoint inventory off the network unless you choose to publish it.

---

What gets generated

API version	Specification file	Covers
v1	storage/app/api-docs/v1/scribe/openapi.yaml	Devices, device credentials, device profiles, templates, categories, commands, vendors, tags, configurations, configuration actions, snippets, tasks, users, dashboard, system health
v2	storage/app/api-docs/v2/scribe/openapi.yaml	Devices, configurations, config changes, policy compliance exports, users, system health

Each version’s folder also holds an index.html with a static, browsable rendering of the same endpoints. Open it locally in a browser after copying the folder off the server.

Inside each openapi.yaml you’ll find:

• info: the title (rConfig REST API v1 or rConfig REST API v2) and version (1.0.0 or 2.0.0).
• servers: your rConfig URL, taken from APP_URL when the file was generated.
• components.securitySchemes: an API key scheme that sends the token in the apitoken header, applied to every operation.
• tags: one tag per resource group (Devices, Configurations, Users, and so on), which Postman and Swagger UI use as folders.
• paths: every api/v1/* or api/v2/* route, with its HTTP method, path parameters, query parameters, and request body. Request body fields carry the types and constraints from the endpoint’s validation rules, so a field that must be at least 5 characters says so in the spec.

The same generation run also writes the AI-Agent REST API Docs Markdown file, which is rendered from this specification.

---

Generate the specification

Run the build command from the rConfig application root on the server:

cd /var/www/html/rconfig8

# Both API versions
php artisan rconfig:api-docs:build --api-version=all

# A single version
php artisan rconfig:api-docs:build --api-version=v2

The command writes openapi.yaml, index.html, and docs.md for each version and sets file ownership so the web server can read them. Expect output like this:

Building API docs for v2...
  Running scribe:generate...
  Parsing /var/www/html/rconfig8/storage/app/api-docs/v2/scribe/openapi.yaml
  Wrote /var/www/html/rconfig8/storage/app/api-docs/v2/docs.md (...)

Generation reads route definitions, controller signatures, and validation rules only. It doesn’t call your API, write to the database, or make outbound requests, so it’s safe to run on a production server.

Regenerate after every rConfig upgrade. The specification reflects the API at the moment you ran the command, and new endpoints or changed fields won’t appear until you build it again.

Caution

APP_URL is copied into the servers entry at generation time. If you generate on a staging server and hand the file to a team that works against production, their requests go to staging. Generate on the server the spec is meant for, or edit the servers URL after copying.

Copy the file off the server

Pull the specification to your workstation with scp, or any file transfer tool you already use:

# v2 specification
scp root@your-rconfig-server:/var/www/html/rconfig8/storage/app/api-docs/v2/scribe/openapi.yaml ./rconfig-api-v2.yaml

# Whole v2 folder, including the static HTML rendering
scp -r root@your-rconfig-server:/var/www/html/rconfig8/storage/app/api-docs/v2/scribe ./rconfig-api-v2

---

Use the specification

Best for: v2 for new integrations. Use v1 when you need resources that only exist there, such as tasks, snippets, templates, or device credentials.

Postman / Insomnia

1. In Postman, click Import and select openapi.yaml. Insomnia has the same option under Import.
2. Postman creates a collection with one folder per tag.
3. Open the collection’s Authorization settings, choose API Key, set the key to apitoken, the value to your token, and Add to to Header.

Store the token in a Postman environment variable rather than in the collection itself, so you can share the collection without sharing the token.

Swagger UI

Serve the file with the official Swagger UI container to give your team a browsable reference:

docker run -p 8080:8080 \
  -e SWAGGER_JSON=/spec/openapi.yaml \
  -v "$(pwd)/rconfig-api-v2:/spec" \
  swaggerapi/swagger-ui

Then open http://localhost:8080. Click Authorize and enter a token to send test requests to the server listed in the spec. Redoc and Stoplight can render the same file.

Client generation

Generate a client library with OpenAPI Generator:

# Python client from the v2 specification
npx @openapitools/openapi-generator-cli generate \
  -i rconfig-api-v2.yaml \
  -g python \
  -o ./rconfig-client

Swap -g python for go, typescript-axios, java, or any other supported generator. Generated clients send the token in the apitoken header, matching the security scheme in the spec.

---

Authentication and abilities

Every operation in the specification requires the apitoken header. Create a token under Settings → REST API → API Token, as described in the REST API overview.

From V8.4.0, tokens also carry abilities, such as devices.read or configs.read. OpenAPI has no field for this, so the specification doesn’t list which ability each endpoint needs. A request outside the token’s abilities returns 403 Forbidden with the message Invalid ability provided. Check the token abilities table before you hand a token to a generated client.

---

Known limitations

• Response bodies are mostly undocumented. To keep generation side-effect free, rConfig doesn’t call endpoints to capture real responses. Many operations list no response schema, so generated clients return untyped data for those calls. Send a test request to see the actual shape.
• Summaries are often blank. Operations are named by method and path (for example getApiV2Devices) rather than by a written summary.
• Example values are placeholders. Request body examples are generated from validation rules and contain random words. Treat them as hints about type and format, not real payloads.
• No live “Try it out” in the static HTML. The bundled index.html is a read-only reference. Use Swagger UI or Postman to send requests.
• Regeneration is manual. Nothing rebuilds the specification on upgrade. Run the build command again after each release.

For the human-readable reference with request and response examples, open Settings → REST API → Documentation inside rConfig. For the Markdown export aimed at AI coding agents, see API Docs in the AI Center.