Skip to main content
Endpoint pages and the API playground render whatever your OpenAPI specification describes. This page covers the parts of a specification that change how Mintlify displays requests and responses: composed schemas, conditional fields, file uploads, response examples and content types, webhooks, and callbacks.

Combine schemas

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.
Mintlify treats oneOf and anyOf identically, and doesn’t support the not keyword. For detailed specifications of these keywords, see oneOf, anyOf, allOf, not in the OpenAPI documentation.

Merge objects with allOf

When you combine two object schemas with allOf, Mintlify merges the properties of both into a single object. This is useful with OpenAPI’s reusable components.
object

Offer options with oneOf and anyOf

When you use oneOf or anyOf, the options display in a tabbed container. Specify a title field in each subschema to name the tabs. For example, here’s how you might display two different types of delivery addresses:
object
string
The street address of the residence
Fields typed as any or undefined render the same way as oneOf schemas, with a picker that lets users select a concrete shape before sending a request.

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:
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. If a condition is too complex to summarize, the field shows a conditionally required pill instead.
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.

File uploads

For OpenAPI 3.1 and 3.2 specifications, define a file upload as a string schema with a binary contentMediaType. The API playground shows the field as a file input and sends it as part of a multipart/form-data request.
You can use binary media types such as application/octet-stream, images, audio, video, PDFs, and archives. The playground doesn’t treat structured media types such as application/json as file uploads. Use contentEncoding to describe how the file content is encoded. For base64-encoded files, set contentEncoding to base64 or base64url, and the playground treats the field as a base64 file. For other values or no value, the playground uses binary file handling. A contentEncoding value without a binary contentMediaType remains a text field. The older format: "binary" and format: "base64" values remain supported.

Multiple response examples

If your API returns different responses based on input parameters, user context, or other conditions of the request, document each one with the examples property on the response.

Response content types

The playground renders responses based on the Content-Type header that your API returns:
  • Images (image/*): Rendered inline.
  • Audio (audio/*): Rendered with an audio player.
  • Video (video/*): Rendered with a video player.
  • All other responses: Displayed in a code block.
To show an audio player in a response example, set the response content type to audio/* and use the URL of an audio file as the example value:

Streaming responses

If an endpoint’s responses declare a streaming media type, the playground shows the response as it arrives instead of waiting for the request to finish. Streaming media types are text/event-stream, application/jsonl, application/x-ndjson, application/json-seq, and multipart/mixed. Requests with a multipart/form-data body don’t stream. While the response streams, the response panel shows Streaming… and the send button changes to Stop. Click Stop to end the request. The playground keeps the data it received and shows Stream stopped. The playground displays a streamed body as plain text, without JSON formatting. A stream can also end early:
  • The playground stops reading after 10 MB and shows Stream truncated at 10 MB.
  • If the connection closes before the stream finishes, the playground shows Stream interrupted.
  • When the playground proxy is on, your API must send response headers within 30 seconds, and the proxy ends the stream after five minutes.

Webhooks

Webhooks are HTTP callbacks that your API sends to notify external systems when events occur. OpenAPI 3.1 and later documents support webhooks. Add a webhooks field to your OpenAPI document alongside the paths field. For more information on defining webhooks, see Webhooks in the OpenAPI specification. To create an MDX page for a webhook, use webhook instead of an HTTP method in the openapi frontmatter:
The webhook name must exactly match the key in your OpenAPI spec’s webhooks field.

Callbacks

Callbacks describe out-of-band requests that your API sends to a URL provided by the caller, such as event notifications tied to a specific operation. When an operation defines callbacks, the endpoint page shows them in a collapsible section between the request body and response sections. Each callback shows its HTTP method and expression, and uses the same body and response layout as the parent operation. For more information on defining callbacks, see Callback object in the OpenAPI specification.