Manage API versions

Add a version

When you add an API in Redocly, you connect it to a source. You can create a version when you are adding an API, or add a new version to an existing API.

You can use the same source for multiple versions.

  1. Log in to your organization in Workflows and select API registry.
  2. Select Add API to add a new API to your registry. The Name page displays.
  3. On the Name page, type in a name and version for your API, and select Next.


    If you are adding a version for an existing API, select the API name from the dropdown.

  4. On the Choose source page, select the source where you have the OpenAPI definition stored. For this example, we will use GitHub. Select Next.
  5. On the Source settings page, complete the following:

    • Under GitHub organizations, select the GitHub organization associated with your GitHub account.
    • Under Repositories, select the repository where you have stored the OpenAPI definition.
    • Under Source settings, select the branch you want to use for your API definition. The API Definition and the Include other assets from this repo options display.
    • Select the path to the API definition root file (in this example, we use the openapi/openapi.yaml file).
    • To add other files (assets), check the Include other assets from this repo option, and provide the path to the folder where the assets are stored (in this example, we use the openapi folder).
    • By default, the Validate and bundle from PRs option is selected.
  6. Select Finish to add the API to the registry. The API registry page displays the API and versions created for the API.

Edit version name

You can edit the version name from Settings > API Info page. For more information, refer to the API info page.

Delete a version

Delete a version from the registry from Settings > Delete version page. For more information, refer to the Delete version page.

View version history

A version can change. It has its own history shown in the logs from the version overview screen.

version logs

The version overview will show the recent logs from any branches associated with the version.

Manage version branches

A version can have one or more branches. It will have one default branch that is set when you connect your source.

For more information, refer to the Branches page.

About version environment variables

You can use environment variables to set up different configuration options for different builds, or to define conditions under which specific content appears in a particular build.

For every version added to Redocly Workflows, you can create custom environment variables from the Settings > Environment variables page.

Select Add variable and provide the name and value for the variable in the dialog that opens. To encrypt the variable and prevent it from being included in the logs, select the optional Secret checkbox before saving changes.

Environment variables in Portals

You can configure environment variables for developer portals via the Redocly Workflows interface in Developer portal > Settings > Environment variables (for production builds) page, or by creating an environment file in your developer portal project repository (for non-production builds).

Environment files are used only for building developer portals. Any existing .env. files in your project don't apply to versions or reference docs managed via Redocly Workflows.

More details about supported environment variables and their usage are available in the Developer portal section of the documentation.

Note that environment variables cannot be used within the OpenAPI definitions themselves. They are supported within custom plugins, rules, and decorators.