API Playground

The API Playground lets users test API endpoints directly from your documentation. It supports all HTTP methods, authentication, path/query/header parameters, and displays formatted responses.

Basic Usage

Get User

Retrieve a user by their ID.

GET/users/{id}

Authorization

Authorizationstringheaderrequired

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Bearer

mdx

<ApiPlayground
  method="GET"
  endpoint="/users/{id}"
  baseUrl="https://jsonplaceholder.typicode.com"
  title="Get User"
  description="Retrieve a user by their ID."
>
  <PlaygroundParam name="id" path required type="integer">
    The unique identifier of the user.
  </PlaygroundParam>
</ApiPlayground>

When you define body parameters using PlaygroundParam, the API Playground renders individual form fields instead of a raw JSON textarea. Values are automatically converted to their correct types and assembled into a JSON request body.

Create Post

Create a new blog post.

POST/posts

Body

mdx

<ApiPlayground
  method="POST"
  endpoint="/posts"
  baseUrl="https://jsonplaceholder.typicode.com"
  title="Create Post"
  description="Create a new blog post."
  noAuth
>
  <PlaygroundParam name="userId" body required type="integer">
    The ID of the user creating the post.
  </PlaygroundParam>
  <PlaygroundParam name="title" body required type="string">
    The title of the post.
  </PlaygroundParam>
  <PlaygroundParam name="body" body required type="string">
    The content of the post.
  </PlaygroundParam>
</ApiPlayground>

Type Conversion

Body parameters are automatically converted based on their type:

string — Input: hello → Output: "hello"
integer — Input: 42 → Output: 42
number — Input: 3.14 → Output: 3.14
boolean — Input: true → Output: true
array — Input: ["a","b"] or a, b → Output: ["a", "b"]
object — Input: {"key": "value"} → Output: {"key": "value"}

Complex Body Schema

Here's an example with multiple field types, pattern validation, and enum dropdowns:

Create User

Create a new user with various field types.

POST/users

Body

mdx

<ApiPlayground method="POST" endpoint="/users" noAuth>
  <PlaygroundParam name="name" body required type="string">
    User's full name.
  </PlaygroundParam>
  <PlaygroundParam
    name="email"
    body
    required
    pattern="^[^\s@]+@[^\s@]+\.[^\s@]+$"
    patternMessage="Please enter a valid email address"
  >
    User's email address.
  </PlaygroundParam>
  {/* Enum creates a dropdown select */}
  <PlaygroundParam name="role" body required enum={["admin", "editor", "viewer"]}>
    User's role.
  </PlaygroundParam>
  <PlaygroundParam name="status" body enum={["active", "inactive"]} default="active">
    Account status.
  </PlaygroundParam>
</ApiPlayground>

Raw JSON Body

If you don't define any body parameters, a raw JSON textarea is shown instead, allowing users to enter custom JSON:

Update Post (Raw JSON)

Update a post using raw JSON input.

PUT/posts/1

Body

mdx

<ApiPlayground
  method="PUT"
  endpoint="/posts/1"
  baseUrl="https://jsonplaceholder.typicode.com"
  title="Update Post (Raw JSON)"
  description="Update a post using raw JSON input."
  noAuth
/>

With Query Parameters

List Posts

Get a list of posts with optional filtering.

GET/posts

Props

ApiPlayground

method

string

required

HTTP method: GET, POST, PUT, PATCH, or DELETE.

endpoint

string

required

The API endpoint path. Use {param} syntax for path parameters.

baseUrl

string

The base URL for the API. Can be set globally in config.

showBaseUrl

boolean

default: false

When true, displays the full URL (baseUrl + endpoint) in the endpoint bar. The baseUrl appears dimmed while the endpoint path is highlighted.

title

string

A descriptive title for the endpoint.

description

string

A brief description of what the endpoint does.

noAuth

boolean

default: false

Set to true to hide the authentication button.

authType

string

default: bearer

Authentication type: bearer, apiKey, or basic.

authHeaderName

string

default: Authorization

The header name to use for authentication.

examples

Record<string, unknown>

Example responses keyed by HTTP status code. Supports any status code (200, 201, 400, 401, 403, 500, etc.). Displays as tabbed interface with color-coded status indicators.

headers

Record<string, string>

Fixed headers to include with every request. These are automatically added to both the generated code and actual requests. Useful for User-Agent, API versioning, or custom headers.

PlaygroundParam

name

string

required

The name of the parameter.

path

boolean

Mark as a path parameter (e.g., /users/{id}).

query

boolean

Mark as a query parameter (e.g., ?limit=10).

header

boolean

Mark as a header parameter.

body

boolean

Mark as a body parameter.

type

string

default: string

The data type: string, integer, boolean, array, object.

required

boolean

Whether the parameter is required.

default

string

Default value for the parameter.

enum

string[]

List of allowed values. Renders as a dropdown.

pattern

string

Regex pattern for input validation. Shows a warning if the value doesn't match, but doesn't block sending the request.

patternMessage

string

Custom error message to display when the pattern validation fails. Defaults to "Invalid format for {name}".

children

string

Description of the parameter.

Showing Full URL

Use showBaseUrl to display the complete URL in the endpoint bar:

List All Posts

GEThttps://jsonplaceholder.typicode.com/posts

mdx

<ApiPlayground
  method="GET"
  endpoint="/posts"
  baseUrl="https://jsonplaceholder.typicode.com"
  showBaseUrl
  noAuth
/>

Authentication

The API Playground supports three authentication types:

Bearer Token - Sent as Authorization: Bearer <token>
API Key - Sent in a custom header
Basic Auth - Base64 encoded credentials

Users can click the key icon to configure their authentication token, which is stored locally in their browser.

Get User (with Auth)

This endpoint works without auth, but demonstrates the authentication UI. Enter any token to see it in the generated code.

GET/users/1

Authorization

Authorizationstringheaderrequired

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Bearer

Enum Parameters

Use the enum prop to provide a dropdown of allowed values:

List Posts

GET/posts

mdx

<PlaygroundParam name="_sort" query enum={["id", "title", "userId"]}>
  Field to sort by.
</PlaygroundParam>

Example Responses

Use the examples prop to display example responses for different status codes. Each key is an HTTP status code, and the value is the example response body:

Create Post

Create a new blog post with example responses.

POST/posts

Body

mdx

<ApiPlayground
  method="POST"
  endpoint="/posts"
  baseUrl="https://jsonplaceholder.typicode.com"
  title="Create Post"
  noAuth
  examples={{
    "201": {
      "id": 101,
      "title": "My Post",
      "body": "Post content here",
      "userId": 1
    },
    "400": {
      "error": "validation_error",
      "message": "Title is required"
    }
  }}
>
  ...
</ApiPlayground>

Status codes are color-coded:

2xx (Success) - Green
3xx (Redirect) - Blue
4xx (Client Error) - Amber
5xx (Server Error) - Red

Fixed Headers

Use the headers prop to include headers with every request. These appear in the generated code and are sent automatically:

List Posts with Custom Headers

GET/posts

mdx

<ApiPlayground
  method="GET"
  endpoint="/posts"
  baseUrl="https://jsonplaceholder.typicode.com"
  noAuth
  headers={{
    "X-API-Version": "2024-01",
    "User-Agent": "MyApp/1.0"
  }}
/>

The API Playground lets users test API endpoints directly from your documentation. It supports all HTTP methods, authentication, path/query/header parameters, and displays formatted responses.

Basic Usage

Get User

Retrieve a user by their ID.

GET/users/{id}

Authorization

Authorizationstringheaderrequired

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Bearer

mdx

<ApiPlayground
  method="GET"
  endpoint="/users/{id}"
  baseUrl="https://jsonplaceholder.typicode.com"
  title="Get User"
  description="Retrieve a user by their ID."
>
  <PlaygroundParam name="id" path required type="integer">
    The unique identifier of the user.
  </PlaygroundParam>
</ApiPlayground>

POST Request with Body

Create Post

Create a new blog post.

POST/posts

Body

mdx

<ApiPlayground
  method="POST"
  endpoint="/posts"
  baseUrl="https://jsonplaceholder.typicode.com"
  title="Create Post"
  description="Create a new blog post."
  noAuth
>
  <PlaygroundParam name="userId" body required type="integer">
    The ID of the user creating the post.
  </PlaygroundParam>
  <PlaygroundParam name="title" body required type="string">
    The title of the post.
  </PlaygroundParam>
  <PlaygroundParam name="body" body required type="string">
    The content of the post.
  </PlaygroundParam>
</ApiPlayground>

Type Conversion

Body parameters are automatically converted based on their type:

string — Input: hello → Output: "hello"
integer — Input: 42 → Output: 42
number — Input: 3.14 → Output: 3.14
boolean — Input: true → Output: true
array — Input: ["a","b"] or a, b → Output: ["a", "b"]
object — Input: {"key": "value"} → Output: {"key": "value"}

Complex Body Schema

Here's an example with multiple field types, pattern validation, and enum dropdowns:

Create User

Create a new user with various field types.

POST/users

Body

mdx

<ApiPlayground method="POST" endpoint="/users" noAuth>
  <PlaygroundParam name="name" body required type="string">
    User's full name.
  </PlaygroundParam>
  <PlaygroundParam
    name="email"
    body
    required
    pattern="^[^\s@]+@[^\s@]+\.[^\s@]+$"
    patternMessage="Please enter a valid email address"
  >
    User's email address.
  </PlaygroundParam>
  {/* Enum creates a dropdown select */}
  <PlaygroundParam name="role" body required enum={["admin", "editor", "viewer"]}>
    User's role.
  </PlaygroundParam>
  <PlaygroundParam name="status" body enum={["active", "inactive"]} default="active">
    Account status.
  </PlaygroundParam>
</ApiPlayground>

Raw JSON Body

If you don't define any body parameters, a raw JSON textarea is shown instead, allowing users to enter custom JSON:

Update Post (Raw JSON)

Update a post using raw JSON input.

PUT/posts/1

Body

mdx

<ApiPlayground
  method="PUT"
  endpoint="/posts/1"
  baseUrl="https://jsonplaceholder.typicode.com"
  title="Update Post (Raw JSON)"
  description="Update a post using raw JSON input."
  noAuth
/>

With Query Parameters

List Posts

Get a list of posts with optional filtering.

GET/posts

Props

ApiPlayground

method

string

required

HTTP method: GET, POST, PUT, PATCH, or DELETE.

endpoint

string

required

The API endpoint path. Use {param} syntax for path parameters.

baseUrl

string

The base URL for the API. Can be set globally in config.

showBaseUrl

boolean

default: false

When true, displays the full URL (baseUrl + endpoint) in the endpoint bar. The baseUrl appears dimmed while the endpoint path is highlighted.

title

string

A descriptive title for the endpoint.

description

string

A brief description of what the endpoint does.

noAuth

boolean

default: false

Set to true to hide the authentication button.

authType

string

default: bearer

Authentication type: bearer, apiKey, or basic.

authHeaderName

string

default: Authorization

The header name to use for authentication.

examples

Record<string, unknown>

Example responses keyed by HTTP status code. Supports any status code (200, 201, 400, 401, 403, 500, etc.). Displays as tabbed interface with color-coded status indicators.

headers

Record<string, string>

Fixed headers to include with every request. These are automatically added to both the generated code and actual requests. Useful for User-Agent, API versioning, or custom headers.

PlaygroundParam

name

string

required

The name of the parameter.

path

boolean

Mark as a path parameter (e.g., /users/{id}).

query

boolean

Mark as a query parameter (e.g., ?limit=10).

header

boolean

Mark as a header parameter.

body

boolean

Mark as a body parameter.

type

string

default: string

The data type: string, integer, boolean, array, object.

required

boolean

Whether the parameter is required.

default

string

Default value for the parameter.

enum

string[]

List of allowed values. Renders as a dropdown.

pattern

string

Regex pattern for input validation. Shows a warning if the value doesn't match, but doesn't block sending the request.

patternMessage

string

Custom error message to display when the pattern validation fails. Defaults to "Invalid format for {name}".

children

string

Description of the parameter.

Showing Full URL

Use showBaseUrl to display the complete URL in the endpoint bar:

List All Posts

GEThttps://jsonplaceholder.typicode.com/posts

mdx

<ApiPlayground
  method="GET"
  endpoint="/posts"
  baseUrl="https://jsonplaceholder.typicode.com"
  showBaseUrl
  noAuth
/>

Authentication

The API Playground supports three authentication types:

Bearer Token - Sent as Authorization: Bearer <token>
API Key - Sent in a custom header
Basic Auth - Base64 encoded credentials

Users can click the key icon to configure their authentication token, which is stored locally in their browser.

Get User (with Auth)

This endpoint works without auth, but demonstrates the authentication UI. Enter any token to see it in the generated code.

GET/users/1

Authorization

Authorizationstringheaderrequired

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Bearer

Enum Parameters

Use the enum prop to provide a dropdown of allowed values:

List Posts

GET/posts

mdx

<PlaygroundParam name="_sort" query enum={["id", "title", "userId"]}>
  Field to sort by.
</PlaygroundParam>

Example Responses

Use the examples prop to display example responses for different status codes. Each key is an HTTP status code, and the value is the example response body:

Create Post

Create a new blog post with example responses.

POST/posts

Body

mdx

<ApiPlayground
  method="POST"
  endpoint="/posts"
  baseUrl="https://jsonplaceholder.typicode.com"
  title="Create Post"
  noAuth
  examples={{
    "201": {
      "id": 101,
      "title": "My Post",
      "body": "Post content here",
      "userId": 1
    },
    "400": {
      "error": "validation_error",
      "message": "Title is required"
    }
  }}
>
  ...
</ApiPlayground>

Status codes are color-coded:

2xx (Success) - Green
3xx (Redirect) - Blue
4xx (Client Error) - Amber
5xx (Server Error) - Red

Fixed Headers

Use the headers prop to include headers with every request. These appear in the generated code and are sent automatically:

List Posts with Custom Headers

GET/posts

mdx

<ApiPlayground
  method="GET"
  endpoint="/posts"
  baseUrl="https://jsonplaceholder.typicode.com"
  noAuth
  headers={{
    "X-API-Version": "2024-01",
    "User-Agent": "MyApp/1.0"
  }}
/>