# API playground pages
Build Mintlify-style API reference pages in Plandalf with endpoint metadata, request fields, response fields, examples, multiple responses, SDK samples, schema notes, visibility, and troubleshooting.
Source: /docs/components/api-playground
Last modified: 2026-06-20
## API reference
- Method: `POST`
- Path: `/api/checkout/sessions`
- Request URL: `https://api.plandalf.com/api/checkout/sessions`
- Authentication: `Public offer route`
- Playground: `simple`
- Operation ID: `createCheckoutSession`
Use this page when an API doc needs to behave like a Mintlify API playground page: the method and path are visible, the request shape is beside the explanation, and the request or response example follows the active endpoint in the right rail.


> **Current support**
>

  Plandalf supports manual MDX API pages today. API playground overview structure, OpenAPI setup, AsyncAPI setup, live request execution, generated SDK examples, complex data types, multiple responses, page visibility, and troubleshooting should be documented from implementation evidence instead of assumed from Mintlify behavior.


## The API page model


### Name the operation


    Start with `ApiEndpoint`. Add `method`, `path`, `title`, `description`, `operationId`, and `auth` so the page has the same request information a generated API reference would expose.


### Document the request


    Use `Fields` with `ParamField` rows for headers, path parameters, query parameters, and request body fields. Prefer `header`, `path`, `query`, or `body` props over a generic `name` when the location matters.


### Attach request examples


    Use `RequestExample` for copyable cURL, JavaScript, or SDK calls. Multiple fenced code blocks become language choices and clone into the right rail on API pages.


### Document response fields


    Use `Responses` and `ResponseField` for the returned shape. Use nested `ResponseField` rows for objects and arrays instead of describing JSON blobs only in prose.


### Show each response outcome


    Add one `ResponseExample` per meaningful outcome: success, validation error, authentication failure, not found, or webhook retry. Include `status` and `statusText` when the HTTP result matters.


## Mintlify API playground coverage


### API playground parity areas


- `API playground overview` (supported manually):
    Use `api`, `openapi`, or `ApiEndpoint` metadata to make the request method, path, auth label, and examples visible before the reader reaches field details.


- `OpenAPI setup` (planned):
    Track OpenAPI source files only after the repo has a schema source and build step. Until then, use manual MDX endpoint pages.


- `AsyncAPI setup` (planned):
    Use this label for WebSocket or event-stream references only after an AsyncAPI source exists. For now, document webhook and event payloads with manual pages.


- `Troubleshooting` (supported manually):
    Add a short troubleshooting section to API pages when auth, missing headers, CORS, schema mismatch, or response-status confusion is likely.


## Manual MDX endpoint

````mdx title="api/manual-endpoint.mdx"
<ApiEndpoint
  id="create-checkout-session"
  method="POST"
  path="/api/checkout/sessions"
  title="Create checkout session"
  description="Creates a checkout session for a published offer."
  operationId="createCheckoutSession"
  auth="Public offer route"
>

### 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 response


    ```json title="201 checkout session"
    {
      "session": {
        "id": "cs_123",
        "status": "open"
      }
    }
    ```


</ApiEndpoint>
````

## Multiple responses

Multiple `ResponseExample` blocks inside one endpoint become separate response outcomes in the API example rail. Keep them close to the endpoint so the reader sees the success path and the likely failure path together.

<ApiEndpoint
  id="api-playground-multiple-responses"
  method="POST"
  path="/api/checkout/sessions"
  title="Multiple response outcomes"
  description="A compact example showing success, validation, and authentication outcomes on one endpoint."
  operationId="createCheckoutSession"
  auth="Public offer route"
>


### Create a checkout 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"}'
```


### Created


```json title="201 created"
{
  "session": {
    "id": "cs_123",
    "status": "open"
  }
}
```


### Validation error


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


### Unauthorized


```json title="401 unauthorized"
{
  "message": "Unauthenticated."
}
```


</ApiEndpoint>

## Complex data types

Use nested response fields for objects and arrays. When a schema has alternatives, document the union in the `type` label and explain each branch in child fields or compact prose.


### Complex response fields


- `session` (object; required):
    Checkout session state returned after the request.


- `session.customer` (object | null):
      Identified buyer context when identity is available.


- `session.line_items` (array<object): ">
      Products, add-ons, order bumps, or selected variants in the session.


- `next_action` (redirect | render | null):
    The next UI action for a custom client. Use a union label when the value can take a small set of shapes.


## SDK examples

Mintlify can generate SDK examples from external tooling. Plandalf docs should only show generated examples when that generator exists in the repo. Until then, use manually maintained examples and label them by runtime.


### Server-side SDK style


```js title="server-checkout.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" })
});
```

```md title="agent-instructions.md"
Create a checkout session from the server.

- Do not expose API credentials in browser code.
- Send Content-Type and Accept headers.
- Handle 201, 401, and 422 responses.
```


## OpenAPI planning


### OpenAPI parity checklist


- `Source schema` (planned):
    Keep OpenAPI source files beside the API implementation once they exist. Do not imply automatic page generation until build code reads those files.


- `Manual page fallback` (supported):
    Use `ApiEndpoint`, `Fields`, `RequestExample`, `Responses`, and `ResponseExample` for hand-authored API references.


- `Navigation` (supported):
    Add the API page to `content/docs/docs.json` so the left sidebar, search index, and markdown export discover it.


- `Page visibility` (supported):
    Use `content/docs/docs.json` for public navigation and `Visibility` for human-only or agent-only MDX sections. Do not hide operational API details in prose only.


- `Generated SDK samples` (planned):
    Only claim generated SDK examples after a generator such as Speakeasy or Stainless is actually configured in this repo.


## AsyncAPI planning


### AsyncAPI parity checklist


- `Event source` (planned):
    Add AsyncAPI references only when Plandalf has a maintained event, channel, or message schema source in the repo.


- `Manual fallback` (supported):
    Use `ApiEndpoint`, `Fields`, `Responses`, and `ResponseExample` to document webhook-style event payloads until generated AsyncAPI pages exist.


- `Navigation` (supported):
    Keep event and webhook pages in `content/docs/docs.json` so they are visible in the public docs, search index, and agent markdown export.


## Troubleshooting


### Troubleshooting checklist


- `Missing auth` (401):
    Show the required auth method near the endpoint header and include the likely unauthenticated response.


- `Invalid payload` (422):
    Pair request fields with a validation response so developers can match field names to error keys.


- `Wrong route` (404):
    Keep method and path visible in the right rail and use stable endpoint IDs so deep links land on the intended operation.


## Related components


  - [API fields and examples](/docs/components/api-fields-examples): See the lower-level endpoint, field, and example props.
  - [Developer API reference](/docs/api/reference): Review a real multi-endpoint page using the API rail.
  - [Mintlify compatibility](/docs/components/mintlify-compatibility): Check component names and imported MDX aliases.