API playground pages

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.

The API page model

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

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

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

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

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

Manual MDX endpoint

<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"
>
  <Fields title="Request body" variant="list">
    <ParamField body="offer" type="string" required>
      Published offer slug, Sqid route key, or UUID.
    </ParamField>
    <ParamField body="metadata" type="object">
      Optional implementation metadata, such as source page or account ID.
    </ParamField>
  </Fields>

  <RequestExample title="Create a session" labels={["Shell", "JavaScript"]}>
    ```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" })
    });
    ```
  </RequestExample>

  <Responses title="Response fields" variant="list">
    <ResponseField name="session" type="object" required expandable defaultOpen>
      The checkout session returned by the API.

      <ResponseField name="session.id" type="string">
        Public checkout session route key.
      </ResponseField>
    </ResponseField>
  </Responses>

  <ResponseExample title="Session response" status={201} statusText="Created" labels={["JSON"]}>
    ```json title="201 checkout session"
    {
      "session": {
        "id": "cs_123",
        "status": "open"
      }
    }
    ```
  </ResponseExample>
</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.

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

{
  "session": {
    "id": "cs_123",
    "status": "open"
  }
}

{
  "message": "The offer field is required.",
  "errors": {
    "offer": ["The offer field is required."]
  }
}

{
  "message": "Unauthenticated."
}

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.

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.

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" })
});

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

AsyncAPI planning

Troubleshooting

Related components