diff --git a/agent-context/context/skills/mintlify/reference/api-docs.md b/agent-context/context/skills/mintlify/reference/api-docs.md
index 39b27307b..cc49890de 100644
--- a/agent-context/context/skills/mintlify/reference/api-docs.md
+++ b/agent-context/context/skills/mintlify/reference/api-docs.md
@@ -109,6 +109,13 @@ For OpenAPI 3.1 and 3.2 specs, describe a file upload field as a string schema w
 - `contentEncoding` of `base64` or `base64url` sends the file as base64; other values use binary handling. A `contentEncoding` without a binary `contentMediaType` stays a text field.
 - The legacy `format: "binary"` and `format: "base64"` fields remain supported.
 
+### Conditional requirements
+
+OpenAPI 3.1 schemas can require a property only in some cases with `if`/`then`/`else`, `dependentRequired`, and `dependentSchemas`. Endpoint pages label each affected field with a "required" pill followed by its condition, for example "required if `method` = `card`", "required unless `method` = `card`" (from `else`), or "required if `tax_id` is set" (from `dependentRequired`).
+
+- Conditions are summarized when `if` tests sibling properties with `const`, `enum`, `type`, or presence (`required`). Anything more complex shows a generic "conditionally required" pill.
+- A property test in `if` also passes when the property is missing, so the tested property must be required (in the object's `required` or the `if` schema's `required`) to get a specific label. Otherwise the field shows "conditionally required".
+
 ## OpenAPI extensions
 
 - `x-hidden`: Creates page but hides from navigation.
diff --git a/api-playground/complex-data-types.mdx b/api-playground/complex-data-types.mdx
index 0fae9d13f..9d1adc994 100644
--- a/api-playground/complex-data-types.mdx
+++ b/api-playground/complex-data-types.mdx
@@ -98,3 +98,53 @@ delivery_address:
     </Tabs>
   </div>
 </ParamField>
+
+## Conditional requirements
+
+In OpenAPI 3.1, you can make a property required only in certain cases with the `if`, `then`, `else`, `dependentRequired`, and `dependentSchemas` keywords. Mintlify reads these keywords and labels each affected field on the endpoint page with a **required** pill followed by its condition.
+
+For example, this schema requires a card number for card payments, an account number for every other payment method, and a company name whenever the request includes a tax ID:
+
+```yaml
+Payment:
+  type: object
+  required:
+    - method
+  properties:
+    method:
+      type: string
+      enum: [card, bank_transfer]
+    card_number:
+      type: string
+    account_number:
+      type: string
+    tax_id:
+      type: string
+    company_name:
+      type: string
+  if:
+    properties:
+      method:
+        const: card
+  then:
+    required:
+      - card_number
+  else:
+    required:
+      - account_number
+  dependentRequired:
+    tax_id:
+      - company_name
+```
+
+The endpoint page labels these fields:
+
+- `card_number`: required if `method` = `card`
+- `account_number`: required unless `method` = `card`
+- `company_name`: required if `tax_id` is set
+
+Mintlify summarizes conditions that test sibling properties for specific values with `const` or `enum`, or for presence with `required`. When a condition is too complex to summarize, the field shows a **conditionally required** pill instead.
+
+<Tip>
+  A property test in `if` also passes when the property is missing. To get a specific label, make the tested property required, either in the object's `required` list or in the `if` schema's `required` list. Otherwise, the field shows the **conditionally required** pill.
+</Tip>
diff --git a/mint-instructions/api-docs/sdk.mdx b/mint-instructions/api-docs/sdk.mdx
index 9a16cd580..711478d8e 100644
--- a/mint-instructions/api-docs/sdk.mdx
+++ b/mint-instructions/api-docs/sdk.mdx
@@ -42,6 +42,7 @@ OpenAPI extensions and schemas:
 - Speakeasy users: point `openapi` at the registry's `*-with-code-samples` combined spec URL, not the source spec.
 - `oneOf` and `anyOf` render the same: tabs named by each subschema's `title`. `not` is unsupported.
 - `allOf` of object schemas is merged into one object with all properties.
+- `if`/`then`/`else`, `dependentRequired` and `dependentSchemas` (OpenAPI 3.1) add a required pill plus its condition (`required if` or `required unless`) to affected fields. Mark properties tested in `if` as required, or the field gets a generic `conditionally required` pill.
 - Fields typed `any` or `undefined` render like `oneOf`, with a picker.
 - `audio/*` response content with a URL example renders an audio player.
 - `x-hidden`: page exists at its URL but is not in navigation. `x-excluded`: no page at all.