{"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"per-api-configuration","__idx":0},"children":["Per-API configuration"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["apis"]}," object is used to configure one or more APIs."," ","Every API in the object is identified by its name and version in the format ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["name@version"]},"."," ","The version is optional, and when not provided, Redocly apps interpret it as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["latest"]}," by default."," ","Every ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["name@version"]}," combination listed in the object must be unique."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For every API listed in the object, you must provide the path to the OpenAPI description using the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["root"]}," property."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["rules"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["decorators"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["preprocessors"]}," aren't defined for an API, root settings are used."," ","If ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["rules"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["decorators"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["preprocessors"]}," are defined for an API, they apply together with the root configuration."," ","If the same ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["rules"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["decorators"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["preprocessors"]}," are defined on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["apis"]}," and the root level, per-API ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["rules"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["decorators"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["preprocessors"]}," override the root ones."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For example, if you include the same ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["decorator"]}," at the root level and for a specific API, but with different properties, the API-level settings replace the root ones."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["So if you have the following ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redocly.yaml"]}," configuration, adding ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["filter-in"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["plugin/change-title"]}," at the root level and applying ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["plugin/change-title"]}," with a different ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["title"]}," property to the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["storefront@latest"]}," API:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"decorators:\n  filter-in:\n    property: x-products\n    value:\n      - Core\n  plugin/change-title:\n    title: All APIs\n    extraProperty: This property will be ignored at the per-API level.\n\napis:\n  storefront@latest:\n    root: ./openapi.yaml\n    decorators:\n      plugin/change-title:\n        title: Storefront APIs\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["plugin/change-title"]}," decorator with the \"Storefront APIs\" ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["title"]}," property is applied to the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["storefront@latest"]}," API with the value ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Storefront APIs"]},", and the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["filter-in"]}," decorator is also applied to the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["storefront@latest"]}," API."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For all other APIs, not including the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["storefront@latest"]}," API, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["filter-in"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["plugin/change-title"]}," with the \"Core\" ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["title"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["extraProperty"]}," properties are applied."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"patterned-properties","__idx":1},"children":["Patterned properties"]},{"$$mdtype":"Tag","name":"JsonSchema","attributes":{"schema":{"$ref":"./api.yaml"},"options":{},"schemaResolved":{"openapi":"3.1.0","components":{"schemas":{"__root":{"$ref":"#/components/schemas/api"},"api":{"type":"object","title":"APIs object","description":"Lets you configure one or more API description files. This gives you the flexibility to reference specific files in commands, and configure each file at a granular level.","additionalProperties":{"x-additionalPropertiesName":"{name}@{version}","type":"object","title":"API object","minItems":1,"required":["root"],"description":"Specifies the name and version of an API associated with the root API description with the pattern `{name}@{version}`. If the version is omitted, Redocly apps interpret it as 'latest' by default.","properties":{"root":{"type":"string","description":"The path to the root API description file of the specified API."},"output":{"type":"string","description":"The path to the output file produced by the `bundle` command."},"labels":{"type":"array","description":"Use it to assign one or more existing Redocly Workflows organization-wide labels to your APIs. You must have a Redocly Workflows account with an active organization, and add the top-level `organization` property to the configuration file.\nIf you try to assign labels that don't already exist for your organization, Redocly apps display a warning in the output and only assigns the existing labels (if any).","items":{"type":"string"}},"preprocessors":{"type":"object","title":"Preprocessors object","description":"Change the severity level of any preprocessors in your extended configurations. Preprocessors run first during `lint` and `bundle`.","additionalProperties":{"description":"List each preprocessor by name. For example, `do-this-first`.","oneOf":[{"type":"string","description":"Specifies the severity level as a string shortcut (or more explicitly as an object).","enum":["on","off"]},{"type":"object","description":"Specifies the severity level as an object. Useful when you need to supply additional properties for configuration.","properties":{"severity":{"type":"string","enum":["on","off"],"description":"The severity level if the problem occurs."}},"additionalProperties":true}]}},"rules":{"type":"object","title":"Rules object","description":"Change the severity level of any rules in your extended configurations. Some rules may also receive additional configurations. Rules run during the `lint` command after preprocessors.","additionalProperties":{"description":"List each rule by name. For example, `no-empty-servers`.","oneOf":[{"type":"string","description":"Specifies the severity level as a string shortcut (or more explicitly as an object).","enum":["error","warn","off"]},{"type":"object","title":"Rule configuration object","description":"Specifies the severity level as an object. Useful when you need to supply additional properties for configuration.","required":["severity"],"properties":{"severity":{"type":"string","enum":["error","warn","off"],"description":"The severity level if the problem occurs."}},"additionalProperties":true}]}},"decorators":{"type":"object","description":"Used to enable or disable decorators. Decorators run during the `bundle` command after linting.","additionalProperties":{"description":"List each decorator by name. For example, `remove-x-internal`.","oneOf":[{"type":"string","description":"Specifies the severity level as a string shortcut (or more explicitly as an object).","enum":["off","on"]},{"type":"object","title":"Decorator configuration object","description":"Specifies the severity level as an object. Useful when you need to supply additional properties for configuration.","properties":{"severity":{"type":"string","enum":["on","off"],"description":"The severity level if the problem occurs."}},"additionalProperties":true}]}},"theme":{"type":"object","properties":{"openapi":{"type":"object","description":"Defines theming and functionality for an API description. Supports the same format and options as the [root `openapi` object](https://redocly.com/docs/api-reference-docs/configuration/functionality/). API-level configuration always overrides the root configuration."},"mockServer":{"type":"object","description":"Defines mock server behavior for an API description. Supports the same format and options as the root `mockServer` object. API-level configuration always overrides the root configuration."}}}}}}}}},"schemaResolvedErrors":[]},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"example","__idx":2},"children":["Example"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"apis:\n  name@version:\n    root: ./openapi/openapi.yaml\n    labels:\n      - production\n    openapi: {}\n    output: ./openapi/bundled.yaml\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Important"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Per-API configurations take priority over global settings."]}]}]},"frontmatter":{},"tagList":["admonition","json-schema"],"title":"Per-API configuration","lastModified":"2026-07-02T13:51:07.000Z"}