DEV Community

Cover image for How to Let an AI Agent Create API Documentation with the Apidog CLI
Hassann
Hassann

Posted on • Originally published at apidog.com

How to Let an AI Agent Create API Documentation with the Apidog CLI

API documentation is important, repetitive, and easy to defer. A new endpoint ships, the reference falls behind, and the getting-started guide still describes an authentication flow you replaced two sprints ago.

Try Apidog today

An AI agent can take on that repeatable work. If it can run terminal commands, it can create endpoints, write Markdown guides, and publish a documentation site from a plain-language request. The Apidog CLI makes this workflow scriptable: documentation actions are commands with structured JSON output that an agent can read and use.

Why use the CLI instead of the GUI or MCP?

These approaches solve different problems:

Approach Direction Who drives it Reviewable diff?
GUI Human edits in a browser A person clicking No
MCP server Reads your spec → writes code An agent in your editor In your code repo, not the docs
CLI Writes documentation resources An agent in a terminal Yes, commands are logged

An MCP server is useful when an agent needs to read an API definition and generate client code. The Cursor doc-through-MCP flow is an example.

This article covers the reverse workflow: an agent produces the documentation itself by creating endpoints, authoring Markdown guides, and publishing a site.

The CLI is a good fit because it is:

  • Deterministic: the same command produces the same result.
  • Scriptable: you can run the workflow in CI.
  • Agent-friendly: JSON responses include agentHints.nextSteps, which tells the agent what it can do next.

Set up the agent environment

Install the CLI and authenticate it once. See the installation guide for Node.js and PATH requirements, and the authentication guide for tokens and CI secrets.

npm install -g apidog-cli
apidog login --with-token <TOKEN>
Enter fullscreen mode Exit fullscreen mode

Apidog CLI installation

Get the token from the Apidog app: user avatar → Account Settings → API Access Token. After login, the CLI stores it locally so the agent does not need to pass it with every command.

API access token settings

Every write command needs a project ID. Find it in Project Settings → Basic Settings, or list available projects:

apidog project list
Enter fullscreen mode Exit fullscreen mode

Any coding agent that can run shell commands can use this workflow, including Claude Code, Cursor, Codex, and similar tools.

Apidog CLI in a coding agent

Apidog CLI workflow

The write ritual: schema, validate, create

Create and update commands accept JSON payload files. Do not let an agent invent those payloads from memory.

Instead, use this sequence for every write:

# 1. Get the current payload schema
apidog cli-schema get doc-create

# 2. Generate a JSON file that matches the schema

# 3. Validate locally before writing
apidog cli-schema validate doc-create --file ./doc.json

# 4. Create the resource
apidog doc create --project <projectId> --file ./doc.json
Enter fullscreen mode Exit fullscreen mode

Add these rules to the agent's system prompt, CLAUDE.md, or .cursorrules file:

Apidog CLI rules:
- Never hand-write a JSON payload. Run `apidog cli-schema get <key>` first and build from that schema.
- Validate every file with `apidog cli-schema validate <key> --file <path>` before any create or update.
- Always pass --project <id> on write commands.
- Read the `agentHints.nextSteps` field in each JSON response to choose the next command.
- If a write comes back blocked by permissions, stop and ask the human; do not pick a workaround.
Enter fullscreen mode Exit fullscreen mode

This prevents common failures such as missing required fields or model-invented field names.

Step 1: Create the API reference from endpoints and schemas

In Apidog, API reference documentation is generated from the endpoints and data schemas in the project.

For example, give an agent this request:

“Add a POST /refunds endpoint that takes an order ID and an amount, and document its success and validation-error responses.”

Start by creating a reusable schema. First, inspect the schema:

apidog cli-schema get schema-create
Enter fullscreen mode Exit fullscreen mode

Then create refund-schema.json:

{
  "name": "Refund",
  "description": "A refund issued against an order",
  "jsonSchema": {
    "type": "object",
    "required": ["orderId", "amount"],
    "properties": {
      "orderId": { "type": "string" },
      "amount": { "type": "number" },
      "reason": { "type": "string" }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Validate and create it:

apidog cli-schema validate schema-create --file ./refund-schema.json
apidog schema create --project <projectId> --file ./refund-schema.json
Enter fullscreen mode Exit fullscreen mode

Next, create the endpoint. Inspect the endpoint payload requirements first:

apidog cli-schema get endpoint-create
Enter fullscreen mode Exit fullscreen mode

The endpoint can reference the schema with $ref using #/definitions/{schemaId}. Create refunds-endpoint.json:

{
  "name": "Create refund",
  "method": "post",
  "path": "/refunds",
  "status": "developing",
  "requestBody": {
    "type": "application/json",
    "jsonSchema": {
      "$ref": "#/definitions/<refundSchemaId>"
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Validate and create the endpoint:

apidog cli-schema validate endpoint-create --file ./refunds-endpoint.json
apidog endpoint create --project <projectId> --file ./refunds-endpoint.json
Enter fullscreen mode Exit fullscreen mode

The /refunds reference documentation is now generated from the same API definition your team maintains. There is no separate reference-export step, so the reference cannot drift from the schema.

Step 2: Add Markdown guides

Generated API reference is only part of useful documentation. You also need prose guides, such as quickstarts, authentication walkthroughs, and migration notes.

In Apidog, these are Markdown documents managed with the doc command group.

Inspect the document schema:

apidog cli-schema get doc-create
Enter fullscreen mode Exit fullscreen mode

A document requires a name. Its Markdown goes in content, and folderId controls its position in the docs tree. Use 0 for the root folder.

Create quickstart.json:

{
  "name": "Quickstart: Your first refund",
  "content": "# Quickstart\n\nThis guide takes you from API key to your first refund in five minutes...",
  "folderId": 0
}
Enter fullscreen mode Exit fullscreen mode

Then validate and create it:

apidog doc list --project <projectId>
apidog cli-schema validate doc-create --file ./quickstart.json
apidog doc create --project <projectId> --file ./quickstart.json
Enter fullscreen mode Exit fullscreen mode

An agent can now take a request such as “write a quickstart from API key to first refund,” generate the Markdown, wrap it in a valid payload, validate it, and publish it to the project docs tree.

Step 3: Publish the documentation site

Use the correct command group for the result you need:

  • doc: a Markdown document inside the project's API tree.
  • docs-site: a hosted public documentation site.
  • shared-doc: a shareable link for a partner or reviewer.

To create a hosted docs site:

apidog docs-site list --project <projectId>
apidog cli-schema get docs-site-create
apidog docs-site create --project <projectId> --file ./docs-site.json
Enter fullscreen mode Exit fullscreen mode

Use docs-site when you need a public site. Use shared-doc when you only need a link to share.

Because publishing is a command, it can become part of an agent workflow or CI job after each documentation change.

Step 4: Export a portable copy

Use export when you need documentation files for another system, such as HTML for external hosting, Markdown for a static-site generator, or OpenAPI for downstream consumers.

apidog export --project <projectId> --format html --output ./api-docs.html
apidog export --project <projectId> --format markdown --output ./api-docs.md
apidog export --project <projectId> --format openapi --oas-version 3.1 --output ./openapi.json
Enter fullscreen mode Exit fullscreen mode

For multi-service projects, inspect available filtering options:

apidog export --help
Enter fullscreen mode Exit fullscreen mode

Use --scope, --api-ids, and --folder-ids to export only the APIs or folders you need.

End-to-end example

Suppose you ask:

You: “We just added a payments service with POST /refunds and GET /refunds/{id}. Document both, write a short guide explaining idempotency keys, and publish it to our docs site.”

The agent can run the following sequence:

# Create the shared data model
apidog cli-schema validate schema-create --file ./refund-schema.json
apidog schema create --project $PID --file ./refund-schema.json

# Create both endpoints
apidog endpoint create --project $PID --file ./post-refunds.json
apidog endpoint create --project $PID --file ./get-refund.json

# Create the idempotency guide
apidog doc create --project $PID --file ./idempotency-guide.json

# Publish the hosted documentation site
apidog docs-site create --project $PID --file ./docs-site.json
Enter fullscreen mode Exit fullscreen mode

Review the generated changes, then merge or publish. The workflow replaces manual browser edits and context switching with an agent request plus review.

Run it in an agent loop or CI

Because the workflow uses CLI commands, it can run in CI. This example exports Markdown documentation on every push:

- name: Regenerate API docs
  run: |
    npm install -g apidog-cli
    apidog login --with-token ${{ secrets.APIDOG_TOKEN }}
    apidog export --project ${{ secrets.APIDOG_PROJECT }} --format markdown --output ./docs/api-docs.md
Enter fullscreen mode Exit fullscreen mode

For more agent workflow examples, see From PRD to Testing Loop and How to Set Up 5 AI Agents to Build a Complete API.

The pattern is consistent:

  1. Describe the intended documentation change.
  2. Generate payloads from the CLI schema.
  3. Validate before writing.
  4. Review the result.

Permission note

Agent writes can be restricted. If a create command is blocked, External AI Edit Permissions may be disabled for the branch.

You have two options:

  1. Enable direct-edit permission in Project Settings → Feature Settings → AI Feature Settings in Apidog client 2.8.32+.
  2. Have the agent work on an isolated AI branch and open a merge request.

The guide for updating an API spec covers the AI-branch workflow. The same approach applies when an agent creates documentation on a protected branch.

Common problems

The agent hand-built JSON.

Require cli-schema get → cli-schema validate → create in agent instructions. Build from the real schema instead of guessed fields.

Missing project ID.

Every doc, docs-site, and export call requires --project <projectId>. Use the project ID from settings, not the readable project name.

Confusing doc, docs-site, and shared-doc.

They represent different resources: a Markdown page, a hosted site, and a share link. Confirm which outcome is required before writing.

Token missing in CI.

apidog login stores credentials on the machine where it runs. Fresh CI runners have no saved token, so run login --with-token in the same job and store the token as a secret.

A $ref points nowhere.

When an endpoint uses #/definitions/{schemaId}, create that schema before creating the endpoint.

FAQ

Which AI agents can run the Apidog CLI?

Any agent that can run shell commands, including Claude Code, Cursor, Codex, and similar coding agents.

Do I need a paid plan?

No. Apidog is not open source, but the free tier and apidog-cli cover the create-and-publish workflow described here.

Can an agent overwrite existing documentation accidentally?

create adds resources. Existing resources require update, which needs separate guardrails. See the update-your-API-spec companion guide.

How is this different from an AI documentation generator?

Generic AI documentation tools generate text from code. This workflow creates structured documentation inside an API platform: endpoints, schemas, Markdown guides, and a published site built from a live source of truth.

Wrap up

An agent that can run the Apidog CLI can create endpoints, write documentation guides, and publish a site from a plain-language request.

The key reliability rule is simple:

Get the schema → validate the payload → create the resource
Enter fullscreen mode Exit fullscreen mode

Give the agent that loop, the rules block, and a project ID. Documentation becomes a reviewable workflow instead of a task that trails behind the code.

Download Apidog to get the CLI, or read the Apidog CLI complete guide for the full command reference.

Top comments (0)