Overview

New imports of a published API version arrive as a draft, unless you let CI pushes publish without review. The draft lists what changes for readers, flags breaking changes, and stays hidden from readers until you publish it. If a published change turns out to be wrong, you can roll back to an earlier revision.

You need the Manage Help Center permission to review, publish, and roll back.

Review and publish a draft

Open the draft

1. Go to Settings → Help Center → API reference

2. Find the version with the Draft to review label and click 'Review' on its row

The version's page opens with a bar above the tabs that sums up the draft, for example: "Not published. 3 endpoints added, 2 changed, 1 removed, 1 breaking. Readers see revision 4 until you publish."

Read the change list

The Endpoints tab shows the draft under Changes to review, in up to four groups:

• Spec: Changes to the servers or security schemes, which apply to every page

• Removed: Endpoints that are no longer in the spec. Their pages are unpublished when you publish

• Changed: Endpoints with new details, one line per change, such as a query parameter added or a response removed

• Added: New endpoints, each with a Publish page checkbox

Changes that can break an existing client are listed first and carry a Breaking label. A change counts as breaking when:

• An endpoint, a parameter, or a request body field is removed

• A required parameter or body field is added, or an optional one becomes required

• The type of a parameter or field changes

• An enum value is removed

• A field is removed from a documented response

Click 'Warnings' in the bar to see the import report, or 'Preview' to open the draft in your Help Center.

Choose which new endpoints get a page

New endpoints get a page by default. Clear Publish page on any endpoint you want to leave out.

To keep every new endpoint off until you pick it, turn on Hide new endpoints until I pick them in the Endpoints tab and click 'Save N pages'. From then on, new endpoints arrive unchecked.

Publish or discard

• Publish: Click 'Publish changes'. When the draft has breaking changes, the button reads 'Publish with breaking changes'

• Discard: Click 'Discard' to drop the draft. Readers keep the published revision

How drafts behave

• One draft at a time: Each version has at most one pending draft. A newer import replaces a draft that nobody reviewed, and the review says which revision it replaced

• Changes during review: If a newer draft arrives while you review, publishing stops with "A newer draft arrived. Review it again."

• Large drops: When more than 20% of the endpoints disappear, the review says so. Check that the spec is the right one before you publish

• Stopped CI pushes: When a safety check kept a CI push from publishing on its own, the review starts with Auto-publish stopped and the reason

Roll back to an earlier revision

Every import creates a revision of the version, and publishing makes it the live one. The History tab lists the live revision and the three before it, with what created each one, its number of pages, and when it was created.

1. Open the version's History tab

2. Click 'Rollback to revision N' on the revision you want

3. Click 'Roll back' to confirm

Readers see that revision at once. Your endpoint choices and the intros you wrote for endpoints stay as they are. A rollback changes only which revision of your API reference is live, not your API.

FAQs