Document custom parameter pills for API reference

api-playground/openapi-setup.mdx

@@ -259,6 +259,46 @@
 }
 ```
 
+### Parameter pills
+
+Annotate parameters in the API reference and playground with custom pill labels using `x-mint.pre` and `x-mint.post` on any schema. Pre pills render before the parameter name and post pills render after it, alongside Mintlify's built-in pills like `required`, `read-only`, and `write-only`.
+
+Both fields accept an array of strings. Each string becomes its own pill.
+
+```json {7-10}
+{
+  "components": {
+    "schemas": {
+      "User": {
+        "properties": {
+          "email": {
+            "type": "string",
+            "x-mint": {
+              "pre": ["PII"],
+              "post": ["indexed", "unique"]
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+To surface arbitrary OpenAPI spec fields as pills across every parameter without editing each schema, configure [`api.params.post`](/organize/settings-api#api-params) in your `docs.json`. List the field keys you want to display, and Mintlify reads each value from the schema and renders matching pills automatically.
+
+```json
+{
+  "api": {
+    "params": {
+      "post": ["nullable", "x-internal"]
+    }
+  }
+}
+```
+
+With this configuration, a property like `{ "type": "string", "nullable": true, "x-internal": "admin" }` renders `nullable` and `admin` pills next to its name. Post pills appear in this order: built-in pills (`read-only`, `write-only`), then `api.params.post` config-driven pills, then per-property `x-mint.post` pills.
+
 ### 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,17 @@
     <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 spec field keys to surface as post pills next to every parameter name in API reference pages and the playground. For each key you list, Mintlify reads the value from the schema and renders it as a pill:
+
+      - String values render as the verbatim string.
+      - `true` renders the key name as the pill label. `false`, `null`, and empty strings render nothing.
+      - Number values render the stringified number.
+      - Arrays of strings or numbers render one pill per element.
+      - Objects and other values are skipped.
+
+      Use this to expose custom OpenAPI fields—such as `x-internal`, `nullable`, or vendor extensions—as visual annotations on each parameter without per-property configuration.
+    </ResponseField>
   </Expandable>
 </ResponseField>
 
@@ -171,9 +182,10 @@
       "display": "interactive"
     },
     "params": {
-      "expanded": "all"
+      "expanded": "all",
+      "post": ["nullable", "x-internal"]
     },
     "url": "full",
     "examples": {
       "languages": ["curl", "python", "javascript", "go"],
       "defaults": "required",

organize/settings-reference.mdx

@@ -1,6 +1,6 @@
 ---
 title: "docs.json schema reference"
 description: "Complete reference for every docs.json configuration property with types, default values, descriptions, and usage examples for your docs site."
 keywords: ["docs.json", "schema", "reference", "configuration", "all settings", "properties", "complete"]
 ---
 
@@ -56,6 +56,7 @@
 | `api.playground.proxy` | boolean | No | `true` |
 | `api.playground.credentials` | boolean | No | `false` |
 | `api.params.expanded` | `"all"` \| `"closed"` | No | `"closed"` |
+| `api.params.post` | array of string | No | None |
 | `api.url` | `"full"` | No | None |
 | `api.examples.languages` | array of string | No | None |
 | `api.examples.defaults` | `"required"` \| `"all"` | No | `"all"` |
@@ -151,13 +152,13 @@
 
 ##### `navigation.global.anchors`
 
 Sidebar anchor links.
 
 **Type:** array of object—each with: `anchor` (string, required), `icon` (string), `iconType` (string), `color.light` (string hex), `color.dark` (string hex), `hidden` (boolean), `href` (string uri, required)
 
 ##### `navigation.global.dropdowns`
 
 Dropdown menus.
 
 **Type:** array of object—each with: `dropdown` (string, required), `icon` (string), `iconType` (string), `hidden` (boolean), `href` (string uri, required)
 
@@ -203,13 +204,13 @@
 
 #### `navigation.anchors`
 
 Sidebar anchor links.
 
 **Type:** array of object—see `navigation.global.anchors` for shape.
 
 #### `navigation.dropdowns`
 
 Dropdown menus.
 
 **Type:** array of object—see `navigation.global.dropdowns` for shape.
 
@@ -233,9 +234,9 @@
 
 #### `navigation.directory`
 
 Directory layout for root pages in navigation groups. Inherits recursively; descendants can override. See [Directory listings](/organize/navigation#directory-listings).
 
 **Type:** `"none"` | `"accordion"` | `"card"` — default `"none"`
 
 ---
 
@@ -770,6 +771,12 @@
 **Type:** `"all"` | `"closed"`
 **Default:** `"closed"`
 
+##### `api.params.post`
+
+OpenAPI spec field keys to surface as post pills next to every parameter name. For each key, Mintlify reads the value on the schema and renders it as a pill: strings render verbatim, `true` renders the key name, numbers stringify, and arrays render one pill per element. `false`, `null`, empty strings, and objects are skipped.
+
+**Type:** array of string
+
 #### `api.url`
 
 Base URL display mode.