RequestExample and ResponseExample

RequestExample and ResponseExample move their code blocks into the right-hand column, in place of the table of contents, where they stay in view as the reader scrolls - the layout of an API reference page. This page uses them: the request and responses are on the right.

curl --request POST \
  --url https://api.example.com/v1/payments \
  --header "Authorization: Bearer $API_KEY" \
  --data '{ "amount": 1000, "currency": "usd" }'

const payment = await fetch("https://api.example.com/v1/payments", {
  method: "POST",
  headers: { Authorization: `Bearer ${apiKey}` },
  body: JSON.stringify({ amount: 1000, currency: "usd" }),
}).then((res) => res.json());

payment = requests.post(
    "https://api.example.com/v1/payments",
    headers={"Authorization": f"Bearer {api_key}"},
    json={"amount": 1000, "currency": "usd"},
).json()

{
  "id": "pay_123",
  "amount": 1000,
  "currency": "usd",
  "status": "succeeded"
}

{
  "error": {
    "code": "invalid_amount",
    "message": "amount must be a positive integer"
  }
}

<RequestExample>
```bash cURL
curl --request POST \
  --url https://api.example.com/v1/payments \
  --header "Authorization: Bearer $API_KEY" \
  --data '{ "amount": 1000, "currency": "usd" }'
```

```js JavaScript
const payment = await fetch("https://api.example.com/v1/payments", { ... });
```

```python Python
payment = requests.post("https://api.example.com/v1/payments", ...).json()
```
</RequestExample>

<ResponseExample dropdown>
```json 201 Created
{ "id": "pay_123", "amount": 1000, "currency": "usd", "status": "succeeded" }
```

```json 400 Bad Request
{ "error": { "code": "invalid_amount", "message": "amount must be a positive integer" } }
```
</ResponseExample>

How they work

• Several code blocks become tabs, named by each block’s title - like a CodeGroup. With dropdown, a menu picks the block instead, as in the response above.
• The response goes under the request, whichever is written first in the page.
• They replace the table of contents on that page, so use them on pages where the example matters more than the list of sections - an endpoint’s page, say.
• On a narrower screen, where the right-hand column isn’t shown, they stay in the page where you wrote them, as ordinary code blocks.
• Only in the default page mode - in the other modes there’s no right-hand column, and they stay in the page.

Pages generated from an OpenAPI spec get this layout without either component. To pin other content - a note, an image - use a Panel.

Props

Both components take the same prop.