Add assets to your API registry

The API registry serves as a single source of truth for your APIs, and allows you to reuse APIs across your Reference docs and Developer portals.

You can also use the API registry to store other types of files. These files are called assets.

The API registry supports the following file formats:

  • Markdown (md, mdx)
  • Web formats (js, css, woff, woff2, html, js.map, xml, graphql, gql)
  • YAML (yaml and yml) and JSON (json) files
  • Image files (png, jpeg, jpg, gif, webp, svg, ico)
  • Common document formats (pdf, txt, xlsx, doc, docx)
  • Other formats (mp4, zip, gz, webmanifest, ttf, otf, opvn)
warning

The build process automatically blocks unsupported file types. These files are not added by the API registry build process, and an unsuccessful message is displayed in the build logs.

How to add assets

attention

You can add assets up to a size limit of 100 MB combined, or a maximum file size of 20 MB per file.

  • If the file size exceeds 20 MB or has an incorrect extension, the file is not added and an error message is displayed in the build log.
  • If the combined size exceeds 100 MB, the add process fails and an error message is displayed in the build log.
  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.
  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. The Redocly app must be installed and configured for this organization. For more information, refer to the API registry quickstart guide.
    • 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. API and assets add
  6. Select Finish to add the API definition file and other assets to the registry. The API registry details page displays with the build information.

View build information

To view the build information, on the API details page, under Logs, select the build name. The API build log displays. View API log

The build information page displays the following:

  • Build summary: Build summary with a step-by-step view of various stages, including validation status of your OpenAPI definition file.

    API build summary

  • Results: Results of the build, including the status of the assets (accepted and rejected data types).

    API build results

Next steps

Create Reference docs using API registry

When you add assets along with a valid API definition file, the assets are added to the API registry, and you can create Reference docs using the API definition.

Under Usages, the Create Reference option is enabled and a success message displays. Select Create Reference to create Reference docs using this API definition.

add assets with API

For more information, refer to the Reference docs quickstart guide.