Publish an API Document
Publishing releases a version of your API documentation from one commit. The version includes:
- the OpenAPI specs, AsyncAPI documents and GraphQL schemas at that commit
- the Markdown documents at that commit
- the navigation and theme from that commit’s
apigit.json
A version is a name pointing at a commit, so a publish is instant and shows exactly what was committed. Publish as many versions as your plan allows. Versions are identified by name, so any number of them can point at one commit.
Version names llms.txt, llms-full.txt, skill.md and mcp are reserved for agent addresses and cannot be used
for a new version or a rename.
Preview before you publish
A publish shows exactly what was committed, so it helps to see the result first. In the editor, the Preview tab renders the file you are working on. In a clone of the repository, the command line shows the whole site, with its navigation and theme, as the published page will draw it:
apigit previewIt serves your working copy on your own machine and reloads as you edit; see Preview the site on your machine.
Where to publish
From a branch
Open the repository, switch to the branch, click Publish, and choose Publish API & Doc. Only a publish from a branch can follow that branch.
From a specific commit
Open the commit list and publish from any commit in the history. This is useful for documenting an earlier release. A publish from a commit is always pinned.
While editing
In editing mode, click Publish and choose a commit, without leaving the editor.
The publish dialog
| Option | What it sets |
|---|---|
| Publish Target | The branch and commit being published |
| Update Strategy | Pin to commit, the default, or Follow branch (paid plans) |
| Publish Mode | Shown when the repository already has a version: Overwrite an existing document publish or New document publish |
| Version | The version’s name, such as 2.1 or next. It is part of the URL and unique within the repository. |
| Description | A note shown in the version list |
| Try It Out | Lets readers send requests from OpenAPI operations, on every plan |
| Access Control | Who can read this version. See Share API Documents. |
Pin or follow a branch
| Pin to commit | Follow branch | |
|---|---|---|
| Shows | The commit it was published from | The head of the branch |
| Updates | When you publish it again | Automatically, at every update of the branch |
| Good for | Released versions that must not change | A next or preview version |
| Plans | Every plan | Team and Enterprise |
Pinning is the default. A following version moves within seconds of a push, a merged pull request, a file saved in the APIGit editor, or a pull-mirror sync. Its URL, access control, external viewers and shared links stay the same. If an update is ever missed, the version catches up within about 10 minutes.
To change the strategy later, open the version and use Update Strategy. Pin to commit it serves now keeps the current commit. Follow branch moves the version to the head of the chosen branch at once.
A following version shows the branch as it is, and nothing is checked first. Follow a branch that only takes reviewed changes, and use branch protection if readers outside your team can see the version.
If the branch is deleted, or the publisher’s account moves to the Free plan, the version stays on its last commit and its page shows why. Follow another branch or pin it.
Overwrite a version
To move a version to a new commit, choose Overwrite an existing document publish and pick the version. An overwrite keeps its URL, access control, external viewers and shared links. Other versions at the old commit do not move, and deleting a version removes only that version.
View published documents
Open the repository’s Publish Center for all its versions, with each one’s commit, access and link:
Open a version to see whether it is pinned or following, and to manage it:
To see the documents of all your repositories, click Publishes Center in the top navigation.
