Published Versions

A published version is what readers of a public site see: a frozen copy of the services you chose. This page explains how to build one, check it and put it on the site.

Roles: An admin publishes versions of any service. An editor publishes versions only of the services in their teams. It needs the publish license feature and is limited by the number of versions per domain. See License and Tiers.

What a version is#

A version is a full copy of the chosen services, independent of the live documentation. Later changes to a service, a deleted service or a revoked token do not affect it. The copy is built in the background into small, ready-to-serve files: the menu, one file per endpoint and per page, the page pictures and a search index. Overlays are already applied.

Environments, tokens, saved requests and notes never get into it.

Add a version#

  1. Choose the domain in the Domain picker of the top bar.
  2. Open Publishing → Versions and click Add version.
  3. Give it a name.
  4. Choose the services with the same tree as in the Export Wizard: per service the version of its documentation and the part to publish.
  5. Decide per service whether to include overlays and whether to publish the request and response examples. Examples are off by default, because they can contain secrets.
  6. Save. The version appears at the top of the list with the status Building.

The build replaces the previous files only when it fully succeeded. If it fails, the version shows Build failed with the reason.

Hidden by default#

A new version starts hidden: the public site does not list it and answers 404 for it. A hidden version can be opened with a preview link.

  • Click Preview on the site on the version. A link https://<domain>/?preview=<token> opens in a new tab.
  • The token is valid for one hour. The portal keeps it in a cookie for that time and does not cache the answers.
  • When the version looks right, click Show. Hide takes it off the site again.

Order and the default version#

Versions are listed in order, and the order is the order of the version picker on the site. Use Move up and Move down. The first version of the list that is shown is the default: / on the site redirects to it.

Change a version service by service#

Open a version to change what is in it:

  • Rename it.
  • Add a service with its own parameters, or remove one.
  • Reorder the services; the order is the order of the site's menu.

The parameters of a service that is already in a version cannot be edited. Remove the service and add it again, because the documentation it was made from may be gone.

Delete a version#

Delete removes the version and its files. This cannot be undone. The number of versions per domain is limited by your plan, so deleting an old one frees a place.

Next steps#

Screenshots

Last updated: