API playground docs refresh

api-playground/asyncapi/setup.mdx

@@ -71,9 +71,9 @@
   the **api-reference** folder of the docs repo.
 </Note>
 
-## Channel Page
+## Channel page
 
 If you want more control over how you order your channels or if you want to just reference a single channel, you can create an MDX file with the `asyncapi` field in the frontmatter.
 
 ```mdx
 ---

api-playground/customization/adding-sdk-examples.mdx

@@ -0,0 +1,49 @@
+---
+title: "Adding SDK examples"
+description: "Display language-specific code samples alongside your API endpoints to show developers how to use your SDKs"
+---
+
+If your users interact with your API using an SDK rather than directly through a network request, you can use the `x-codeSamples` extension to add code samples to your OpenAPI document and display them in your OpenAPI pages.
+
+This property can be added to any request method and has the following schema.
+
+<ParamField body="lang" type="string" required>
+  The language of the code sample.
+</ParamField>
+
+<ParamField body="label" type="string">
+  The label for the sample. This is useful when providing multiple examples for a single endpoint.
+</ParamField>
+
+<ParamField body="source" type="string" required>
+  The source code of the sample.
+</ParamField>
+
+Here is an example of code samples for a plant tracking app, which has both a Bash CLI tool and a JavaScript SDK.
+
+```yaml
+paths:
+  /plants:
+    get:
+      ...
+      x-codeSamples:
+        - lang: bash
+          label: List all unwatered plants
+          source: |
+            planter list -u
+        - lang: javascript
+          label: List all unwatered plants
+          source: |
+            const planter = require('planter');
+            planter.list({ unwatered: true });
+        - lang: bash
+          label: List all potted plants
+          source: |
+            planter list -p
+        - lang: javascript
+          label: List all potted plants
+          source: |
+            const planter = require('planter');
+            planter.list({ potted: true });
+```
+

api-playground/customization/complex-data-types.mdx

@@ -0,0 +1,95 @@
+---
+title: "Complex data types"
+description: "Describe APIs with flexible schemas, optional properties, and multiple data formats using `oneOf`, `anyOf`, and `allOf` keywords"
+---
+
+When your API accepts multiple data formats, has conditional fields, or uses inheritance patterns, OpenAPI's schema composition keywords help you document these flexible structures. Using `oneOf`, `anyOf`, and `allOf`, you can describe APIs that handle different input types or combine multiple schemas into comprehensive data models.
+
+## `oneOf`, `anyOf`, `allOf` keywords
+
+For complex data types, OpenAPI provides keywords for combining schemas:
+
+- `allOf`: Combines multiple schemas (like merging objects or extending a base schema). Functions like an `and` operator. 
+- `anyOf`: Accepts data matching any of the provided schemas. Functions like an `or` operator.
+- `oneOf`: Accepts data matching exactly one of the provided schemas. Functions like an `exclusive-or` operator.
+
+<Warning>Mintlify treats `oneOf` and `anyOf` identically since the practical difference rarely affects using the API.</Warning>
+
+For detailed specifications of these keywords see the [OpenAPI documentation](https://swagger.io/docs/specification/data-models/oneof-anyof-allof-not/).
+
+<Info>The `not` keyword is currently unsupported.</Info>
+
+### Combining schemas with `allOf`
+
+When you use `allOf`, Mintlify performs some preprocessing on your OpenAPI document to display complex combinations in a readable way. For example, when you combine two object schemas with `allOf`, Mintlify combines the properties of both into a single object. This becomes especially useful when leveraging OpenAPI's reusable [`components`](https://swagger.io/docs/specification/components/).
+
+```yaml
+org_with_users:
+  allOf:
+    - $ref: '#/components/schemas/Org'
+    - type: object
+      properties:
+        users:
+          type: array
+          description: An array containing all users in the organization
+...
+components:
+  schemas:
+    Org:
+      type: object
+      properties:
+        id:
+          type: string
+          description: The ID of the organization
+```
+
+<ParamField body="org_with_users" type="object">
+  <Expandable>
+    <ParamField body="id" type="string">
+      The ID of the organization
+    </ParamField>
+    <ParamField body="users" type="object[]">
+      An array containing all users in the organization
+    </ParamField>
+  </Expandable>
+</ParamField>
+
+### Providing options with `oneOf` and `anyOf`
+
+When you use `oneOf` or `anyOf`, Mintlify displays the options in a tabbed container. Specify a `title` field in each subschema to give your options names. For example, here's how you might display two different types of delivery addresses:
+
+```yaml
+delivery_address:
+  oneOf:
+    - title: StreetAddress
+      type: object
+      properties:
+        address_line_1:
+          type: string
+          description: The street address of the recipient
+        ...
+    - title: POBox
+      type: object
+      properties:
+        box_number:
+          type: string
+          description: The number of the PO Box
+        ...
+```
+
+<ParamField body="delivery_address" type="object">
+  <div className="mt-4 rounded-xl border border-gray-100 px-4 pb-4 pt-2 dark:border-white/10">
+    <Tabs>
+      <Tab title="StreetAddress">
+        <ParamField body="address_line_1" type="string">
+          The street address of the residence
+        </ParamField>
+      </Tab>
+      <Tab title="POBox">
+        <ParamField body="box_number" type="string">
+          The number of the PO Box
+        </ParamField>
+      </Tab>
+    </Tabs>
+  </div>
+</ParamField>

api-playground/customization/managing-page-visibility.mdx

@@ -0,0 +1,85 @@
+---
+title: "Managing page visibility"
+description: "Control which endpoints from your OpenAPI specification appear in your documentation navigation"
+---
+
+You can control which OpenAPI operations get published as documentation pages and their visibility in navigation. This is useful for internal-only endpoints, deprecated operations, beta features, or endpoints that should be accessible via direct URL but not discoverable through site navigation.
+
+If your pages are autogenerated from an OpenAPI document, you can manage page visibility with the `x-hidden` and `x-excluded` extensions.
+
+## `x-hidden`
+
+The `x-hidden` extension creates a page for an endpoint, but hides it from navigation. The page is only accessible by navigating directly to its URL.
+
+Common use cases for `x-hidden` are:
+
+- Endpoints you want to document, but not promote.
+- Pages that you will link to from other content.
+- Endpoints for specific users.
+
+## `x-excluded`
+
+
+The `x-excluded` extension completely excludes an endpoint from your documentation.
+
+Common use cases for `x-excluded` are:
+
+- Internal-only endpoints.
+- Deprecated endpoints that you don't want to document.
+- Beta features that are not ready for public documentation.
+
+## Implementation 
+
+Add the `x-hidden` or `x-excluded` extension under the HTTP method in your OpenAPI specification.
+
+Here are examples of how to use each property in an OpenAPI schema document for an endpoint and a webhook path.
+
+```json {11, 19}
+"paths": {
+  "/plants": {
+    "get": {
+      "description": "Returns all plants from the store",
+      "parameters": { ... },
+      "responses": { ... }
+    }
+  },
+  "/hidden_plants": {
+    "get": {
+      "x-hidden": true,
+      "description": "Returns all somewhat secret plants from the store",
+      "parameters": { ... },
+      "responses": { ... }
+    }
+  },
+  "/secret_plants": {
+    "get": {
+      "x-excluded": true,
+      "description": "Returns all top secret plants from the store (do not publish this endpoint!)",
+      "parameters": { ... },
+      "responses": { ... }
+    }
+  }
+},
+```
+
+```json {9, 15}
+"webhooks": {
+  "/plants_hook": {
+    "post": {
+      "description": "Webhook for information about a new plant added to the store",
+    }
+  },
+  "/hidden_plants_hook": {
+    "post": {
+      "x-hidden": true,
+      "description": "Webhook for somewhat secret information about a new plant added to the store"
+    }
+  },
+  "/secret_plants_hook": {
+    "post": {
+      "x-excluded": true,
+      "description": "Webhook for top secret information about a new plant added to the store (do not publish this endpoint!)"
+    }
+  }
+}
+```

api-playground/customization/multiple-responses.mdx

@@ -0,0 +1,31 @@
+---
+title: "Multiple responses"
+description: "Show response variations for the same endpoint"
+---
+
+If your API returns different responses based on input parameters, user context, or other conditions of the request, you can document multiple response examples with the `examples` property.
+
+This property can be added to any response and has the following schema.
+
+```yaml
+responses:
+  "200":
+    description: Successful response
+    content:
+      application/json:
+        schema:
+          $ref: "#/components/schemas/YourResponseSchema"
+        examples:
+          us:
+            summary: Response for United States
+            value:
+              countryCode: "US"
+              currencyCode: "USD"
+              taxRate: 0.0825
+          gb:
+            summary: Response for United Kingdom
+            value:
+              countryCode: "GB"
+              currencyCode: "GBP"
+              taxRate: 0.20
+```

api-playground/mdx/authentication.mdx

@@ -3,13 +3,13 @@
 description: "You can set authentication parameters to let users use their real API keys."
 ---
 
-## Enabling Authentication
+## Enabling authentication
 
-You can add an authentication method to your docs.json to enable it on every page or you can set it on a per-page basis.
+You can add an authentication method to your `docs.json` to enable it globally on every page or you can set it on a per-page basis.
 
-The page's authentication method will override docs.json if both are set.
+A page's authentication method will override a global method if both are set.
 
-### Bearer Token
+### Bearer token
 
 <CodeGroup>
 
@@ -32,7 +32,7 @@
 
 </CodeGroup>
 
-### Basic Authentication
+### Basic authentication
 
 <CodeGroup>
 
@@ -55,7 +55,7 @@
 
 </CodeGroup>
 
-### API Key
+### API key
 
 <CodeGroup>
 
@@ -87,7 +87,7 @@
 ```md Page Metadata
 ---
 title: "Your page title"
 authMethod: "none"
 ---
 ```
 </CodeGroup>