How to generate AI-friendly REST API docs in rConfig V8
How to generate AI-agent-friendly REST API docs in rConfig V8
Section titled “How to generate AI-agent-friendly REST API docs in rConfig V8”Ask an AI agent to “write a script that adds devices to rConfig from our CMDB” and, without help, it guesses at endpoints, field names, and authentication. Give it rConfig’s API Docs export and it writes against the real API: every v1 and v2 endpoint, its parameters, and the validation rules behind each field, generated from your own install.
MCP, Skills, or API Docs?
Section titled “MCP, Skills, or API Docs?”| You want the agent to… | Use |
|---|---|
| Look things up in rConfig right now (“what changed on this switch?”) | MCP Server |
| Look things up reliably, following rConfig’s recommended workflows | Skills plus MCP |
| Write code that calls rConfig: scripts, integrations, sync jobs | API Docs (this page) |
| Generate a client library, or import the API into Postman | OpenAPI Specification |
The API Docs export and the OpenAPI specification are produced by the same command. The export is the version written for AI agents; the OpenAPI file is for tools.
Prerequisites
Section titled “Prerequisites”- Access to the AI Center in rConfig.
- Shell access to the rConfig server to generate or refresh the docs. Anyone with AI Center access can view, copy, or download an export that already exists.
Step-by-step walkthrough
Section titled “Step-by-step walkthrough”1. Open the API Docs tab
Section titled “1. Open the API Docs tab”Click AI Center in the left sidebar and select the API Docs tab. Two rows are listed, REST API v1 and REST API v2, each with a status badge: Not generated, Stub only, or Generated.
2. Generate the docs
Section titled “2. Generate the docs”A new install shows Stub only, because rConfig ships placeholder files. Run the build command once on the rConfig server:
cd /var/www/html/rconfig8php artisan rconfig:api-docs:build --api-version=allRefresh the API Docs tab and both badges change to Generated. Re-run the command after each rConfig upgrade so the docs match the API you’re running.
3. View, copy, or download
Section titled “3. View, copy, or download”Use View to read the export in the browser, Copy to put it on your clipboard, or Download to save rconfig-api-v2-docs.md (or v1). Use v2 for new work; use v1 for endpoints that only exist there, such as tasks, snippets, and templates.
Use the export with an AI agent
Section titled “Use the export with an AI agent”Save the download into your project and reference it in your prompt, for example @rconfig-api-v2-docs.md. To make it available in every session, mention it in your project’s CLAUDE.md.
Save the download into your project and add it to the agent’s context, or reference it from your project rules.
Save the download into your repository and reference it from .github/copilot-instructions.md.
Upload the downloaded file to the conversation, or paste the sections you need.
Give the agent a REST API token through an environment variable or secret, never by pasting it into the docs file. From V8.4.0, give it a token with only the abilities the script needs.
Example: a CMDB sync script
Section titled “Example: a CMDB sync script”Scenario: you want a nightly script that disables devices in rConfig when your CMDB marks them as decommissioned.
Prompt (with the v2 export attached):
“Using the attached rConfig API docs, write a Python script that reads a CSV of decommissioned hostnames, looks up each device in rConfig, and disables it. Read the token from the RCONFIG_TOKEN environment variable. Do a dry run by default and print what would change.”
Check the endpoints the agent chose against the export before running anything, and run the dry run first.