From 40b7bc57400daa156a35d48c3225fd2c80370215 Mon Sep 17 00:00:00 2001
From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com>
Date: Mon, 27 Apr 2026 19:11:18 +0000
Subject: [PATCH] Document parameter labels and api.params.post setting

Generated-By: mintlify-agent
---
 api-playground/openapi-setup.mdx | 31 +++++++++++++++++++++++++++++++
 organize/settings-api.mdx        |  8 +++++++-
 2 files changed, 38 insertions(+), 1 deletion(-)

diff --git a/api-playground/openapi-setup.mdx b/api-playground/openapi-setup.mdx
index 60cc5eb0f..9d55f659e 100644
--- a/api-playground/openapi-setup.mdx
+++ b/api-playground/openapi-setup.mdx
@@ -259,6 +259,37 @@ Set the URL of the autogenerated endpoint page using `x-mint: href`. When `x-min
 }
 ```
 
+### 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.
diff --git a/organize/settings-api.mdx b/organize/settings-api.mdx
index 601dda27e..c284dae81 100644
--- a/organize/settings-api.mdx
+++ b/organize/settings-api.mdx
@@ -113,6 +113,11 @@ Define all API-related settings under the `api` key.
     <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,7 +176,8 @@ Define all API-related settings under the `api` key.
       "display": "interactive"
     },
     "params": {
-      "expanded": "all"
+      "expanded": "all",
+      "post": ["x-required-scope"]
     },
     "url": "full",
     "examples": {