Keep API reference docs in sync with a staging OpenAPI spec

A technical writer pairs a scheduled Node.js watcher with a Cursor Automation that drafts one docs pull request per product area whenever the staging API contract changes.

Done withCursorinGitHub· Nov 18, 2026

What they did

Harshit Satyaseel keeps his team's API reference in step with a staging OpenAPI file that changes often. His first version simply fed the spec to an agent on a schedule and had it open pull requests. He rebuilt it so that a scheduled GitHub Action running plain Node.js does the deciding: it stores one snapshot per endpoint, compares contract facts rather than wording, groups changes by product area and by new versus changed endpoints, counts open draft PRs as known work, and refuses to run if too many routes vanish at once. Each group lands on its own branch, which triggers a Cursor Automation. The agent claims the branch with an empty commit, reads a brief from the watcher, edits only the OpenAPI file, matching pages, navigation and changelog, and opens a draft PR.

How it went

The first version produced pull requests for reworded descriptions, piled unrelated changes into one review, drafted the same change twice and nearly documented a broken deploy as removed endpoints. After the rebuild, most runs do nothing, which he counts as success, and a person still merges every PR. The agent writes better pages when pointed at a nearby sibling page to copy. Removed endpoints and changelog version clashes stay manual. He gives no time or volume numbers.

Worth knowing

The agent never deletes pages or merges; the watcher's checks matter more than the prompt. The git claim only works if every run starts from the branch tip. If someone renames a PR and drops its title prefix, the watcher no longer sees it and may draft the change again. The author also sells a book on docs automation.

Try it

With Cursor· 5 parts to fill in

You are drafting docs for one group of API changes on branch [branch name]. Read the brief at [path to brief] listing each changed endpoint, the before and after facts and where pages live. Update only [the OpenAPI file], the matching endpoint pages, navigation for new pages and [the changelog]. Copy the structure of the closest existing page. Never delete a page for a removed endpoint; flag it instead. List other pages that mention these endpoints without editing them. Open a draft pull request titled [prefix] and stop; do not merge.

Square brackets are the parts to fill in. The prompt is ours; the story is theirs.

Where they said it

Related