update-api-reference — Claude Code command: API docs updates
The update-api-reference command for Claude Code compares API schemas with earlier versions and drafts docs, guides, and changelog updates as endpoints or parameters change.
Apache-2.0 ★ 450 updated 2026-04-03
.claude/commands/update-api-reference.mdWhat update-api-reference does
Provide an OpenAPI or AsyncAPI file path or URL, the intended audience, output types, and sample-code languages. The command compares the schema against an earlier baseline, identifies added, changed, or deprecated endpoints, then drafts descriptions, parameters, responses, usage notes, and code samples. Outputs can include a reference, guide, tutorial, or changelog entry.
The result can include updated API reference material in Markdown or HTML, code samples for the selected languages, and a changelog excerpt. Set breaking-change to request migration guidance when applicable. Drafts go through engineering or product validation and an editorial style check; the workflow also covers publishing and version updates. A schema and an earlier version to compare against are needed.
What it helps with
- compare a new API schema with an earlier version
- revise endpoint descriptions and parameter details
- draft code samples in selected languages
- record schema changes and prepare migration guidance
Example prompts for the agent
- Update the API reference for developers from
openapi.yaml, with a guide and samples injsandpython. - Compare this schema with the previous version and draft changelog notes and migration guidance using
--breaking-change true. - Prepare API reference updates and a tutorial for partners from
openapi.yaml. Run/technical-writing:update-api-reference.
How to install update-api-reference
Manually: put the files in place
.claude/commands/update-api-reference.mdCall it with /update-api-reference. For all projects use ~/.claude/commands/
Manually: put the files in place
~/.codex/prompts/update-api-reference.mdCall it with /prompts:update-api-reference. Codex marks this format deprecated in favour of skills
Manually: put the files in place
.github/prompts/update-api-reference.prompt.mdManually: put the files in place
.gemini/commands/update-api-reference.tomlGemini stores commands as TOML: the prompt text goes into the prompt field
Questions about update-api-reference
How do I install update-api-reference in Claude Code?
Add the command file at .claude/commands/update-api-reference.md.
What does update-api-reference do?
It compares an OpenAPI or AsyncAPI schema with an earlier version and drafts changes to API docs, guides, code samples, and changelog entries.
How can I request migration guidance?
Set --breaking-change true. The command includes migration guidance when it applies to the schema changes.
Source text
update-api-reference.md · Apache-2.0
--- name: update-api-reference description: Generates API reference + guides updates from new schema changes with samples and changelog entries. usage: /technical-writing:update-api-reference --spec openapi.yaml --audience developers --outputs reference,guide --languages js,python --- # Command: update-api-reference ## Inputs - **spec** – OpenAPI/AsyncAPI file path or URL. - **audience** – developers | partners | internal | admins. - **outputs** – reference, guide, changelog, tutorial (comma-separated). - **languages** – code sample languages (js, python, curl, java, go, ruby, csharp). - **breaking-change** – true/false toggle for migration guidance. ## Workflow 1. **Spec Diff & Analysis** – compare schema version vs prior baseline, note new/changed/deprecated endpoints. 2. **Content Scope** – determine docs to update (reference tables, tutorials, SDK snippets, changelog entries). 3. **Drafting** – produce updated endpoint descriptions, parameters, responses, usage notes, and code samples per language. 4. **Review Loop** – route drafts to engineering/product for validation and to editorial for style compliance. 5. **Publishing & Versioning** – push updates, tag version support, update changelog + migration guidance. ## Outputs - Updated API reference markdown/HTML with highlighted changes. - Code sample bundle per requested languages. - Changelog excerpt + migration guidance (if applicable). ## Agent/Skill Invocations - `api-docs-editor` – leads spec diff + doc updates. - `documentation-architect` – ensures IA + governance alignment. - `api-style-guide` skill – enforces terminology, formatting, and code sample rules. - `versioning-dashboard` skill – logs version info + deprecation timelines. ---
© gtmagents · Apache-2.0 · gtmagents/gtm-agents