Document parameter labels and api.params.post

api-playground/openapi-setup.mdx

@@ -259,6 +259,37 @@
 }
 ```
 
+### Parameter labels
+
+Add custom labels next to a parameter's type in your API reference and playground using `x-mint.pre` and `x-mint.post` on any property in your OpenAPI specification.
+
+- `x-mint.pre`: An array of strings that render as labels before the parameter type.
+- `x-mint.post`: An array of strings that render as labels after the parameter type.
+
+Use these to surface property-specific information that doesn't fit in the description, such as scope requirements, PII flags, or feature gates. Mintlify automatically renders `read-only` and `write-only` labels for properties marked `readOnly` or `writeOnly`, so you don't need to add them manually.
+
+```json {7-10}
+{
+  "components": {
+    "schemas": {
+      "User": {
+        "properties": {
+          "email": {
+            "type": "string",
+            "x-mint": {
+              "pre": ["PII"],
+              "post": ["requires admin scope"]
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+To turn an existing OpenAPI field—including custom `x-` extensions—into a label on every property without editing each one, use the [`api.params.post`](/organize/settings-api) setting in your `docs.json`.
+
 ### Group display names
 
 Set a custom display name for a tag's navigation group using the `x-group` extension on a tag object. By default, Mintlify uses the tag `name` as both the navigation group label and the URL path segment. The `x-group` extension overrides the group label while keeping the tag name for the URL.

organize/settings-api.mdx

@@ -1,6 +1,6 @@
 ---
 title: "API settings"
 description: "Configure OpenAPI and AsyncAPI specs, the interactive API playground, SDK code examples, and authentication settings in your docs.json file."
 keywords: ["api", "openapi", "asyncapi", "playground", "docs.json", "api reference"]
 ---
 
@@ -113,6 +113,11 @@
     <ResponseField name="expanded" type='"all" | "closed"'>
       Whether to expand all parameters by default. Defaults to `closed`.
     </ResponseField>
+    <ResponseField name="post" type="array of string">
+      OpenAPI schema field keys to render as labels next to the type on every parameter. For each key listed, Mintlify reads the value from the property's schema and surfaces it as a label: strings render verbatim, `true` renders the key name, and arrays of strings or numbers render one label per item. Booleans set to `false`, objects, and missing values are skipped.
+
+      Use this to expose custom or vendor-specific OpenAPI fields—such as `x-required-scope` or `x-pii`—without editing every property individually. To add labels to a single property instead, use the [`x-mint.pre` and `x-mint.post`](/api-playground/openapi-setup#parameter-labels) extensions.
+    </ResponseField>
   </Expandable>
 </ResponseField>
 
@@ -171,9 +176,10 @@
       "display": "interactive"
     },
     "params": {
-      "expanded": "all"
+      "expanded": "all",
+      "post": ["x-required-scope"]
     },
     "url": "full",
     "examples": {
       "languages": ["curl", "python", "javascript", "go"],
       "defaults": "required",