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.
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.

​
Describe response fields

Use <ResponseField> for values returned by the API:
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.
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.
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 define the endpoint structure. Add hand-written guidance for 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.