{"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"manage-your-apis-with-the-api-catalog","__idx":0},"children":["Manage your APIs with the API catalog"]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"danger","name":"Deprecated docs"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The developer portal beta is ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/product-timelines"},"children":["approaching end of life"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use Realm and Reunite instead. Read the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs-legacy/developer-portal/migrate-from-legacy-portal"},"children":["migration guide"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The API catalog feature helps you integrate your APIs and files from Redocly API registry into your portal."," ","It also makes it easier to manage multiple versions of APIs in the portal."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The integration flow works as follows:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Upload files to an API in the registry."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Enable your portal to use those files by linking them to the portal configuration."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The portal automatically pulls the files into the project. You can then link to the files from other pages in your portal; for example, insert images into Markdown files or use OpenAPI definitions in portal components."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"prerequisites","__idx":1},"children":["Prerequisites"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To use the API catalog in your portal, you need the following:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A Redocly Workflows account, with permissions to add new APIs to the registry. Read more about ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs-legacy/people/roles-permissions"},"children":["roles and permissions"]},"."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A Redocly Developer portal project set up and ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs-legacy/developer-portal/connect-developer-portal"},"children":["connected to Workflows"]},", with full access to configuration files."]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-1-add-apis-and-files-to-the-registry","__idx":2},"children":["Step 1: Add APIs and files to the registry"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In this step, add one or more APIs and any files you want to integrate into the portal to the API registry."," ","Files can be anything: from Markdown pages and images to Redocly-specific configuration files like ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redocly.yaml"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["permissions.rbac.yaml"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can use any API source except ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["URL"]}," to add your APIs to the registry. Read more about ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs-legacy/workflows/sources"},"children":["API version sources"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In this guide, we're referring to GitHub as the recommended source."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Follow the ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs-legacy/api-registry/guides/add-registry-assets"},"children":["file upload guide"]}," to upload files to the registry."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-2-configure-the-api-catalog-in-the-portal","__idx":3},"children":["Step 2: Configure the API catalog in the portal"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In the previous step, you added APIs to the registry and uploaded some files to one or more API versions."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In this step, collect file links for each version you want to integrate into the portal, and add them to the API catalog."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"copy-files-links","__idx":4},"children":["Copy files links"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In the API registry, find and select the API you want to integrate. APIs in the registry are distinguished by their name and version."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["On the selected API ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["Overview"]}," page, find the branch that contains the files you want to use in the portal. This is either your production (",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["primary"]},") branch, or one of the preview branches."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Select ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Files link"]}," for the branch and save the copied link for later use."," ","The link is in the format ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://api.redoc.ly/registry/assets/your-organization-ID/api-name/api-version/"]},"."," ","If you select a non-primary branch, the link includes the selected branch: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://api.redoc.ly/registry/assets/your-organization-ID/api-name/api-version/?branch=branch-name"]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Repeat the procedure for every API version you want to integrate."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"add-links-to-api-catalog-file","__idx":5},"children":["Add links to API catalog file"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["In the root of your portal project, create a file called ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["catalog.yaml"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The structure of the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["catalog.yaml"]}," file should be as follows:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"# List of APIs from the registry to integrate into the portal.\n\napiCatalog:\n  - title: # Optional custom title to use for the API. If omitted, the API name from the registry is used by default.\n    defaultVersion: # Optional indicator specifying which of the listed 'versions' to treat as the default. If omitted, the last listed version is treated as the default.\n    disableAutoSidebar: # Optional parameter that prevents automatically creating the default 'sidebars.yaml' file. When set, users must manually add files to their existing 'sidebars.yaml' file or include a 'sidebars.yaml' file alongside their registry files.\n    pathPrefix: # Optional parameter to specify where to download files. When set, it replaces the automatically created 'api-name' folder. The 'api-version' subfolder(s) will still be created for non-default versions in the specified path prefix.\n    versions: # One or more versions of the API to integrate.\n      - link: # Must be a 'Files link' for a specific API version in the registry.\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"ol","attributes":{"start":2},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Add the file links you've copied to the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["catalog.yaml"]}," file."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example catalog.yaml"]}]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"Single version","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"apiCatalog:\n  - title: ACME\n    disableAutoSidebar: true\n    versions:\n      - link: https://api.redoc.ly/registry/assets/org/acme/v1/\n","lang":"yaml"},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"Multiple versions","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"apiCatalog:\n  - title: Redocly API\n    defaultVersion: v1\n    pathPrefix: /apis/starter\n    versions:\n      - link: https://api.redoc.ly/registry/assets/org/redocly/v1/\n      - link: https://api.redoc.ly/registry/assets/org/redocly/v2/\n","lang":"yaml"},"children":[]}]}]},{"$$mdtype":"Tag","name":"ol","attributes":{"start":3},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Save the changes to the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["catalog.yaml"]}," file and start the portal build."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"import-files-into-the-portal","__idx":6},"children":["Import files into the portal"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["During the portal build, files are automatically downloaded to your portal project."," ","A ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[".gitignore"]}," file containing the files is automatically created."," ","To update your files, ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["do not commit or push them directly"]}," from the portal project."," ","Instead, upload new versions of files through the registry."," ","When a file is modified in the registry, the portal detects it and automatically triggers a new build."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For the default version, files are downloaded into the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["api-name"]}," folder."," ","For all other versions, files are downloaded into their respective ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["api-name/api-version"]}," subfolders."," ","Use the optional ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pathPrefix"]}," parameter in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["catalog.yaml"]}," to set any other path to replace the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["api-name"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In our examples above:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["files for ACME would be downloaded into ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["acme"]},", because there's only one version, which is the default, and because we didn't set a custom path prefix."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["files for Redocly API v1 (default) would be downloaded into ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/apis/starter/redocly"]},", but files for v2 would be downloaded into ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/apis/starter/redocly/v2"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For the default version, all files are downloaded, including Markdown files, images, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sidebars.yaml"]}," (if it exists), and any other configuration files."," ","For non-default versions, only the API definition file is downloaded."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Markdown and MDX files are automatically turned into pages in the portal, and you can link to them from any other page."," ","Similarly, you can include other files (like images) in your existing portal pages."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"use-the-redocly-configuration-file","__idx":7},"children":["Use the Redocly configuration file"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If a ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs/cli/configuration"},"children":["Redocly configuration file"]}," exists among the files for the default version and has settings in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["theme.openapi"]}," section, the portal uses those settings for all versions of an API (default and non-default)."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["theme.openapi"]}," section supports all ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs-legacy/api-reference-docs/configuration/functionality"},"children":["Reference configuration options"]}," plus two special options for controlling access to content:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["excludeFromSearch"]}," - If set to true, the API documentation is excluded from search results and the sitemap. Default value is false."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["permission"]}," - Defines the permissions using ",{"$$mdtype":"Tag","name":"Link","attributes":{"href":"/docs-legacy/developer-portal/configuration/rbac"},"children":["role-based access controls"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example Redocly configuration file"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"apis:\n  acme@v1:\n    root: ./openapi/acme-v1.yaml\n    theme:\n      openapi:\n        pagination: section\n        showConsole: true\n        permission: 'read:internal-docs'\n        excludeFromSearch: true\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"add-files-to-portal-sidebar","__idx":8},"children":["Add files to portal sidebar"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sidebars.yaml"]}," file doesn't exist for the default version, it is automatically generated."," ","This default ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sidebars.yaml"]}," contains all files from your registry link."," ","The following example shows the contents of the automatically generated ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sidebars.yaml"]}," file."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"- page: ./*\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To skip creating the default ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sidebars.yaml"]}," file for an API, set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["disableAutoSidebar: true"]}," on the API level in your ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["catalog.yaml"]},"."," ","In this case, you must add the files to a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sidebars.yaml"]}," file manually, or include a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sidebars.yaml"]}," file in the registry."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-3-create-api-catalog-page","__idx":9},"children":["Step 3: Create API catalog page"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["By default, the portal does not automatically create any catalog page to display your integrated APIs."," ","Redocly provides a few built-in catalog pages in the future."," ","For now, you can use helpers to build it."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["useCatalog"]}," helper is experimental, so it may change. We are extending it to support filtering."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Here is an example catalog page called ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["apis.mdx"]},":"]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"apis.mdx","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"mdx","header":{"controls":{"copy":{}}},"source":"---\ntitle: API Catalog\n---\n\nimport { Catalog } from './_components/Catalog';\n\n<Catalog />\n","lang":"mdx"},"children":[]}]},{"$$mdtype":"Tag","name":"TabItemFragment","attributes":{"label":"_components/Catalog.tsx","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"tsx","header":{"controls":{"copy":{}}},"source":"import * as React from 'react';\n\nimport {\n  useCatalog,\n  FlexSection,\n  Flex,\n  WideTile,\n  SectionHeader,\n  LoadingAnimation,\n} from '@redocly/developer-portal/ui';\n\nexport function Catalog() {\n  const { apis, loadingRbac } = useCatalog({ offset: 0, limit: 10 });\n\n  if (!apis.length) {\n    return \"You don't have access to any API\";\n  }\n\n  return (\n    <>\n      <Flex flexDirection=\"row\" alignItems=\"baseline\">\n        <SectionHeader> API Catalog</SectionHeader>\n        {loadingRbac ? <LoadingAnimation size={20} /> : null}\n      </Flex>\n      <FlexSection justifyContent=\"space-around\" flexWrap=\"wrap\">\n        {apis.map(api => (\n          <WideTile to={api.link} header={api.title || api.link}>\n            Tags: {api.defaultVersion.metadata?.tags.map(tag => <span> {tag} </span>)}\n          </WideTile>\n        ))}\n      </FlexSection>\n    </>\n  );\n}\n","lang":"tsx"},"children":[]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Notice that ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["metadata"]}," from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["features.catalog"]}," is available in the metadata returned from catalog."]}]},"frontmatter":{"excludeFromSearch":true},"tagList":["admonition","partial","tab","tabs"],"title":"Manage your APIs with the API catalog","lastModified":"2025-05-28T16:01:32.000Z"}