# API fields and examples
Use fields, response fields, request examples, and response examples to build Mintlify-style API docs with endpoint-aware right-rail samples.
Source: /docs/components/api-fields-examples
Last modified: 2026-06-20
API docs should pair readable field definitions with real request and response examples. On API pages, each `ApiEndpoint` renders request information for the call, and `RequestExample` and `ResponseExample` blocks attach to the right rail so the code follows the endpoint the reader is viewing.


> **Every endpoint needs both sides**
>

  Document the request fields, the response fields, a copyable request, and a representative response. The docs audit fails detailed API endpoints that skip request or response examples.


## Manual endpoint page

Use frontmatter for a single endpoint page, or `ApiEndpoint` blocks when one page documents several related calls.

<ApiEndpoint
  id="example-create-session"
  method="POST"
  path="/api/checkout/sessions"
  title="Create checkout session"
  description="Creates a checkout session for a published offer."
  operationId="createCheckoutSession"
>


### Request body


- `offer` (string; required):
    Published offer slug, Sqid route key, or UUID.


- `metadata` (object):
    Optional implementation metadata, such as source page or account ID.


### Create a session


```bash title="POST /api/checkout/sessions"
curl -X POST "https://api.plandalf.com/api/checkout/sessions" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"offer":"pro-plan"}'
```

```js title="create-session.js"
const response = await fetch("https://api.plandalf.com/api/checkout/sessions", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Accept: "application/json"
  },
  body: JSON.stringify({ offer: "pro-plan" })
});
```


### Response fields


- `session` (object; required):
    The checkout session returned by the API.


- `session.id` (string):
      Public checkout session route key.


- `session.status` (string):
      Current session state.


- `offer` (object):
    The offer context attached to the session.


### Session response


```json title="201 checkout session"
{
  "session": {
    "id": "cs_123",
    "status": "open",
    "currency": "USD",
    "total": 2900
  },
  "offer": {
    "id": "off_123",
    "slug": "pro-plan",
    "name": "Pro plan"
  }
}
```


### Validation error


```json title="422 validation error"
{
  "message": "The offer field is required.",
  "errors": {
    "offer": ["The offer field is required."]
  }
}
```


</ApiEndpoint>

## Props


### Endpoint props


- `method` (GET | POST | PUT | PATCH | DELETE; required):
    Renders the method badge in the request summary and the active right-rail call.


- `path` (string; required):
    Renders the endpoint path, copyable request URL, and right-rail call path.


- `baseUrl` (string; default: https://api.plandalf.com):
    Sets the base URL used in the request information summary and copy URL action.


- `auth` (string; default: Bearer token):
    Describes the authentication model for this endpoint, such as `Bearer token` or `Public offer route`.


- `operationId` (string):
    Shows the stable operation name in the request information summary.


### Field props


- `name` (string):
    Generic field name when the location is not important.


- `query | path | body | header` (string):
    Sets the field location label.


- `type` (string):
    Field type, such as `string`, `object`, `array`, or a union.


- `required` (boolean; default: false):
    Marks the field as required.


- `default` (string):
    Shows a default value.


- `deprecated` (boolean; default: false):
    Marks older fields without deleting useful migration context.


### Example props


- `title` (string):
    Heading for the request or response example.


- `status` (string | number):
    Adds an HTTP status badge and, on API pages, lets the right rail switch between multiple response outcomes.


- `statusText` (string):
    Adds the HTTP reason phrase as accessible context for the response status.


- `labels` (string[]):
    Labels multiple fenced code blocks inside one example.


- `dropdown` (boolean; default: false):
    Uses a dropdown selector for examples with many variants.


- `rail` (boolean; default: true):
    Controls whether request and response examples clone into the desktop right rail.


## Related components


  - [Developer API reference](/docs/api/reference): See a multi-endpoint page using the right rail.
  - [Tabs and code groups](/docs/components/tabs-code-groups): Use shared labels for language-specific examples.