AI-Agent REST API Docs

AI-Agent REST API Docs

rConfig V8 ships a first-class way to hand your REST API surface to an AI coding agent. Instead of copy-pasting endpoints into a prompt, or asking the model to guess from a URL, you feed it a single Markdown file that describes every v1 and v2 endpoint — paths, parameters, validation rules, response codes — generated directly from the running Laravel application.

This page is for operators, developers, and integrators who want to use an AI agent (Claude, ChatGPT, Cursor, Cline, Copilot, and friends) to reason about, call, or build against the rConfig REST API.

Note

This feature produces documentation of the existing REST API in an AI-consumable format. It does not expose a new API surface, and it does not let agents call the API without a token. You still authenticate with a standard rConfig API Token.

Why this exists

Modern AI coding agents perform best when given complete, structured, authoritative context about a system. A generic prompt like “write a Python client for rConfig” tends to produce hallucinated endpoints, missed required fields, or wrong auth headers. Attaching a concise Markdown spec of the API drives a step-change in output quality:

• The agent knows every valid endpoint, method, and path parameter.
• The agent knows which body fields are required, their types, and their validation constraints.
• The agent knows how to authenticate (apitoken header).
• The agent can reason about request/response shapes without probing the server.

Because the spec is generated from the live application, it stays in lock-step with whatever your rConfig install actually serves — no hand-written drift.

What you get

Two Markdown files, one per API version:

Path	Contents
storage/app/api-docs/v1/docs.md	Every v1 endpoint: devices, configurations, tasks, users, templates, snippets, categories, commands, vendors, tags, device profiles, device credentials, dashboard, system health, configuration actions
storage/app/api-docs/v2/docs.md	Every v2 endpoint: devices, configurations, users, policy compliance exports, system health

Both files share the same structure:

# rConfig REST API v{N}

Version: {N}.0.0

## Overview

...

## Authentication

Scheme: default (apiKey, header "apitoken")
Generate an API token under
Settings → REST API → Tokens.
Send it as the `apitoken` request header
on every call.

## Base URL

https://your-rconfig-host

## Devices

### POST /api/v{N}/devices

Request body (required)
Content-Type: `application/json`

- `device_name` (string, required)
  Must match regex /^\S\*$/u.
  Must be at least 5 characters...
- `device_vendor` (string, required)
  Example: `architecto`
- ...

Response codes

- `200` — Success

...

Simple, stable, tokenizer-friendly. No HTML, no scripts, no Swagger/Redoc bundles — just Markdown.

When to use it

Good fits

• Attaching docs.md to an AI coding agent’s system prompt as the canonical API reference
• Generating typed REST clients (TypeScript, Python, Go, etc.) by handing the Markdown to a capable model
• Letting an agent chain rConfig API calls to resolve natural-language ops tasks (e.g. “disable every Cisco 4331 whose last backup failed in the last 7 days”)
• Scaffolding CMDB / IPAM / ITSM sync code without manually curating an endpoint registry
• Seeding an internal AI knowledge base that stays in sync with the deployed API — regenerate on each release
• Onboarding new developers by giving their assistant (Copilot, Cursor, etc.) a complete API picture alongside the codebase

When not to use it

Not a fit

• Not a human-friendly reference. For human browsing, use the existing REST API Documentation pages inside rConfig.
• Not auto-updated. You must regenerate after changes to routes, controllers, or FormRequests.
• Not a public API catalogue. The files are disk-only; they are never served over an unauthenticated URL.
• Not an auth bypass. Giving an agent docs.md does not let it call anything — it still needs a valid apitoken. Never paste a token into the docs file itself.
• Not a replacement for rate-limiting, backups, or change-control. An agent calling your API can make real, possibly destructive changes. Review what you give your agent permission to do.

Finding it in the app

Two places inside rConfig surface this feature for admins.

1. Developers panel

Navigate to Settings → Developers. Alongside Script Integration Engine, Custom Commands, rConfig Automate, and REST API Integration, you will find an AI Agent Documentation section describing the feature and linking directly to the tab below.

2. REST API Access → AI Agent Docs tab

Navigate to Settings → REST API Access. The page has three tabs:

Tab	Purpose
API Token	Create, list, and revoke API Tokens
Documentation	Human-readable API reference (opens the docs page)
AI Agent Docs	Status, preview, copy, and download of the generated Markdown

You can deep-link straight to it: /settings/restapi?tab=ai-agent-docs.

The AI Agent Docs tab shows, per API version:

• Presence indicator — whether the file has been generated
• Size and last-generated timestamp — so you know how fresh it is
• View — inline preview of the raw Markdown (monospace, scrollable)
• Copy — one-click copy to clipboard for pasting into an agent prompt
• Download — saves the file with an explicit text/markdown Content-Type and a filename like rconfig-api-v1-docs.md

The tab also shows the exact CLI command to generate or refresh the docs (see Regenerating below) and a typical end-to-end agent workflow.

Using it with an AI agent

A representative workflow:

1. Create an API Token on the API Token tab. Store it as a secret your agent can read (environment variable, secret manager, tool definition); do not paste it into the Markdown file.
2. Download or copy the appropriate docs.md — v2 for new integrations, v1 for legacy endpoints still in use.
3. Attach it to your agent’s context. Examples:
   • Claude Code / Cursor / Cline: drop the file into the workspace; reference it in the task prompt.
   • Claude / ChatGPT web: paste the Markdown into the system prompt or upload it as a document.
   • Copilot / Codeium agents: include the file in the repository; the agent will index it.
   • Custom agents via the Anthropic or OpenAI API: include the Markdown in the system message, or load it into a retrieval store and retrieve relevant sections per turn.
4. Ask the agent to perform work against rConfig — call endpoints via a tool, generate a typed client, draft an integration. The Markdown is its ground truth.
5. Regenerate and replace the file after any API change, release, or patch (see next section).

Tip

For very large agent contexts, consider splitting the docs by resource group (the ## Devices, ## Configurations, ## Tasks sections) and loading only the parts relevant to the task. The Markdown is intentionally structured to make this cheap to do programmatically.

Regenerating

The Markdown is produced by a dedicated Artisan command. Run it from the rConfig application root on the server:

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

# Single version
php artisan rconfig:api-docs:build --api-version=v1
php artisan rconfig:api-docs:build --api-version=v2

# Re-render the Markdown only, without re-running the upstream extractor
php artisan rconfig:api-docs:build --api-version=v1 --no-generate

The command:

1. Loads the version-specific extractor config (config/scribe_v1.php or config/scribe_v2.php).
2. Runs Scribe against the matching routes to produce an OpenAPI 3.0 YAML under storage/app/api-docs/v{N}/scribe/openapi.yaml.
3. Parses that spec with a small custom renderer (App\Services\ApiDocs\OpenApiMarkdownRenderer) and writes the final AI-friendly Markdown to storage/app/api-docs/v{N}/docs.md.

You typically regenerate:

• Before cutting a release
• After adding or removing API routes
• After changing a FormRequest that backs an API endpoint
• After changing an API controller’s group or authentication semantics

Note

Intermediate Scribe artifacts (HTML preview, OpenAPI YAML) are written under storage/app/api-docs/v*/scribe/ and are gitignored. Only the final docs.md files are committed.

Architecture (under the hood)

For curious readers or contributors.

Components

Component	Responsibility
knuckleswtf/scribe (dev dependency)	Scans routes, resolves FormRequests and API Resources, emits OpenAPI 3.0
config/scribe_v1.php, config/scribe_v2.php	Per-version Scribe configuration: route matchers, auth header name, output path
App\Console\Commands\ApiDocsBuildCommand	Orchestration — swaps Scribe config at runtime, runs generation, parses spec, renders Markdown
App\Services\ApiDocs\OpenApiMarkdownRenderer	Pure OpenAPI → Markdown conversion. Suppresses the apitoken header from per-endpoint listings (it’s covered once in the Authentication section)
App\Http\Controllers\Api\ApiDocsController	Sanctum-protected endpoints that serve the on-disk files to admins inside the UI

Safety properties

• Side-effect-free generation. Scribe’s ResponseCall strategy (which makes live HTTP requests to discover response bodies) is intentionally disabled. Generation reads routes, controller signatures, FormRequests, and API Resources — nothing else. No database writes, no outbound requests.
• Disk-only by default. The generated files live inside storage/app/api-docs/ and are never mapped to a public URL.
• UI surface is sanctum + admin. When the in-app panel fetches file content for preview, it goes through ApiDocsController which sits behind auth:sanctum (same guard as the rest of the settings API).
• Version isolation. v1 and v2 produce independent files and independent OpenAPI specs; neither can pollute the other.

Keeping the docs honest

The quality of the generated Markdown is only as good as the metadata Scribe can infer. rConfig enforces two conventions on API controllers so that generated docs stay well-structured:

1. Every routed api/v1/* and api/v2/* controller class carries a class-level @group <Name> PHPDoc tag. This controls how endpoints are grouped under headings in the final Markdown.
2. Every routed api/v1/* and api/v2/* controller class carries a class-level @authenticated PHPDoc tag. This marks endpoints as requiring a token in the generated OpenAPI.

Example:

/**
 * @group Devices
 *
 * @authenticated
 */
class DeviceController
{
    // ...
}

Beyond those two tags, Scribe infers parameters, types, and validation constraints automatically from:

• Route definitions (path parameters, HTTP methods)
• Controller method signatures and injected FormRequest classes
• FormRequest::rules() arrays (validation constraints become human-readable sentences in the docs)
• Return types and API Resources (where present)

A test (Tests\Unit\ApiDocs\ControllerAnnotationComplianceTest) enumerates every routed v1/v2 controller and fails the build if either tag is missing — so new controllers cannot silently drop out of the AI-agent docs.

Where else to look (internal developer references)

When working on this feature inside the rConfig repo, these are the canonical internal references:

Location	What it covers
docs/api-docs-generation.md	Developer-facing quick reference — regenerate commands, how the pipeline works, how to extend coverage. Kept minimal and repo-local.
app/Console/Commands/ApiDocsBuildCommand.php	The orchestration command source.
app/Services/ApiDocs/OpenApiMarkdownRenderer.php	The renderer source; covered by unit tests.
config/scribe_v1.php, config/scribe_v2.php	Versioned Scribe configs.
tests/Unit/Services/ApiDocs/OpenApiMarkdownRendererTest.php	Renderer contract.
tests/Unit/ApiDocs/ControllerAnnotationComplianceTest.php	Longevity guard — fails when controllers lose their annotations.
tests/Fasttests/ControllersTests/Api/ApiDocsControllerTest.php	Behavioural tests for the admin-facing endpoints.

In-product references for admins:

Location	What it does
Settings → Developers → AI Agent Documentation	Narrative introduction + deep link into the panel.
Settings → REST API Access → AI Agent Docs (tab)	File status, preview, copy, download, regenerate instructions.

Limitations and known gaps

• Response bodies are currently under-documented. The generated spec captures response status codes (from controller returns and FormRequest failures) but not response shapes, because live response-calls are disabled for safety. To improve this, refactor endpoints to return typed JsonResource / ResourceCollection or add @response / @apiResource PHPDoc tags — Scribe will pick those up automatically.
• Regeneration is manual. There is intentionally no in-UI “regenerate” button. The command runs from the server CLI, typically by whoever cuts releases.
• APP_URL embeds into the Base URL section at generation time. If you generate on a staging host, the staging URL will appear in the Markdown until you regenerate on production.
• Examples are fake-data. FormRequest rules drive plausible values via Faker; use them as shape hints, not as real payloads.

FAQ

Is this different from the “Documentation” tab? Yes. The Documentation tab is a human-friendly, hand-curated reference inside the rConfig UI. The AI Agent Docs tab exposes a separate, machine-generated Markdown file intended for programmatic / LLM consumption. They live side by side because they serve different audiences.

Can I serve docs.md publicly? Not by default, and not recommended. The endpoint that surfaces it is admin-only (Sanctum auth). If you really need a public spec for partners, the intermediate openapi.yaml at storage/app/api-docs/v{N}/scribe/openapi.yaml is the right artifact — but that’s a separate decision about your threat model, not something the feature turns on for you.

Do I need Scribe installed in production? No. Scribe is a dev dependency. The generated docs.md files are committed; customers consume pre-built files. Only developers who regenerate need Scribe installed.

Which version should I point my agent at? v2 for new integrations. v1 remains fully documented for legacy code paths.

Can I split the docs per resource? Yes — the Markdown is intentionally structured around ## <Group> section headings, so splitting by resource is a straightforward programmatic transform.