Skip to main content
Someone reading an API reference usually arrives with a specific question like “Is this parameter required?” or “What type does this field return?” or “What does a successful response look like?” Mintlify’s API components put those answers in predictable places. Readers can scan the page instead of digging through paragraphs or decoding a hand-built table.

​
Document request parameters

Use <ParamField> for path, query, body, and header parameters. The prop identifies where the parameter belongs. Add its type and whether it is required, then describe any limits a reader could otherwise miss.
Example of request parameters
Don’t make readers guess about allowed values, formats, units, or limits. “The number of results” leaves questions. “Maximum results per page, from 1 to 100” answers them. Adding a <ParamField> to a page also adds an API playground, where readers can fill in the parameters and send a real request. If a parameter is being phased out, add deprecated so readers see it before they build on it.

​
Describe response fields

Use <ResponseField> for values returned by the API:
Example of a response field
For a nested object, put an <Expandable> inside its parent field. Readers can see that id and email belong to user without having every child property open by default.
Example of nested response fields
Use expandables for this kind of nested reference data. If you’re hiding optional explanation rather than child properties, use an accordion.

​
Pair requests with responses

<RequestExample> and <ResponseExample> show the complete exchange in the page’s side panel. Start with a successful request, then add the error responses readers are likely to encounter.
Example of request and response examples
Check examples against the field documentation whenever the API changes. A field marked as required shouldn’t be missing from the example, and a renamed field shouldn’t survive in an old response block.

​
Generated reference versus hand-written reference

If you have an OpenAPI document, let it generate your API reference and define the endpoint structure. Use these components for hand-written guidance on the parts a schema can’t explain well: why someone would choose an option, how a workflow fits together, or what to do when a request fails. Try not to define the same field by hand in several places. When its type or behavior changes, one of those copies will eventually be missed. Next up: Images, frames, and diagrams—add visual context that explains a task or relationship.