API pages use frontmatter to configure settings, including the API endpoint's name, description, and more.

To make a page an API page, add the api key to the page's frontmatter.

Here's an example of an API page frontmatter for an endpoint:

---
api:
  endpoint:
    post /v1/users:
      summary: Create a new user
      description: Creates a user account in the system
      auth: bearer
      params:
        query:
          include?: string
      request:
        body:
          example:
            email: user@example.com
            name: Jane Doe
            role: member
      responses:
        201:
          description: User created successfully
          example:
            id: usr_123
            email: user@example.com
            name: Jane Doe
            createdAt: "2024-01-15T10:30:00Z"
        400:
          description: Invalid request data
        401:
          description: Authentication required
---

serverUrl

The serverUrl value is used to override the default API URL for individual API pages.

---
api:
  serverUrl: "https://api.example.com/v2"
---

endpoint

The endpoint value is used to define the endpoint for the API page.

---
api:
  endpoint:
    post /v1/users:
      summary: Create a new user

summary

The summary value is used to define the summary for the endpoint, like in the OpenAPI/Swagger spec. This should be a short description of only a few words.

description

The description value is used to define the description for the endpoint, like in the OpenAPI/Swagger spec. This is useful for providing a longer description of the endpoint.

---
api:
  endpoint:
    post /v1/users:
      description: Creates a user account in the system

Add multi-line Markdown content to the description to make it more readable and add more details.

---
api:
  endpoint:
    post /v1/users:
      description: |
        If you use a pipe character on the first line of the description, you can add content freely below.

        - add lists

        Add **bold text** and _italic text_.

        Add [links](https://www.example.com).

params

The params value is used to define any headers and URL query parameters for the request.

You can define the query parameters with a query key.

You can define the headers with a header key.

---
api:
  endpoint:
    post /v1/users:
      params:
        query:
          include?: string
        header:
          X-Custom-Header: string
---          

Path parameters are defined in the endpoint URL, using curly braces like /path/{userId}.

---
api:
  endpoint:
    patch /v1/users/{userId}:
      summary: Update a user
---

Path parameters are alays considered required and strings.

You can add a description to a path parameter like any other field.

---
api:
  endpoint:
    patch /v1/users/{userId}:
      summary: Update a user
      params:
        path:
          userId:
            type: string
            description: The ID of the user to update
---

---
api:
  endpoint:
    patch /v1/users/{userId}:
      summary: Update a user
      params:
        path:
          userId: string
            The ID of the user to update
---

request

The request value is used to define the request for the API page.

You can define the request body with a body key.

Inside the body key, you can define both a schema and an example (or examples) for the request body, to show readers the expected request body format or a real example.

schema and example/examples are both optional. If both are defined, the example will be used in the code examples on the final page.

---
api:
  endpoint:
    post /v1/users:
      request:
        body:
          schema:
            email: string
            name: string
          example:
            email: user@example.com
            name: Jane Doe

When using examples, summary will be displayed as the example's name. value lists the fields for the example.

---
api:
  endpoint:
    post /v1/users:
      request:
        body:
          schema: CreateCheckoutRequest
          examples:
            creditPack:
              summary: Credit pack purchase
              value:
                pack_id: pack_...            
            

Example of schema:

{
  "email": "<string>",
  "name": "<string>"
}

Example of example:

{
  "email": "user@example.com",
  "name": "Jane Doe"
}

If you have schemas that can be used in multiple endpoints, you can add schema files in a /schemas folder.

responses

The responses value is used to define the responses for the API page.

You can add a description to describe the response.

You can also define a custom title. If omitted the official HTTP status code name (e.g. "OK", "Created", "Bad Request") will be displayed instead.

---
api:
  endpoint:
    post /v1/users:
      responses:
        201:
          title: User created successfully
        400:
          description: Invalid request data
        401:
          description: Authentication required

schema

Schemas describe or define the structure of the request body and response body for an API endpoint.

You can define the schema in the frontmatter, or you can reference a schema file. Using schema files is useful when you have schemas that are repeated across multiple endpoints, as they can be imported into endpoint frontmatter.

Schemas are created using a simple key-value format, where the key is the field name and the value is the type of the field.

Schemas can be added to requests and responses, in the request.body.schema and responses.*.schema keys.

---
api:
  endpoint:
    post /v1/users:
      request:
        body:
          schema:
            email: string
            name: string
      responses:
        201:
          schema:
            id: string
        400:
          schema:
            error: string
        401:
          schema:
            error: string

Example value types are:

• string
• number
• integer
• boolean
• datetime
• array
• object
• uuid
• null
• undefined

You can use the ? operator to make a field optional. (By default all fields are required.)

schema:
  name?: string

You can add descriptions to fields by indenting a line below.

Descriptions can be a single line, or a multi-line block of text or Markdown.

schema:
  email: string
    User's email address. Must be valid and unique.

Alternatively you can use type and description keys:

schema:
  email:
    type: string
    description: User's email address. Must be valid and unique.

To add a multi-line or Markdown description use a pipe character on the first line:

schema:
  email:
    type: string
    description: |
      User's email address. Must be **valid** and unique.
      Supports `+` aliases (e.g., `user+tag@example.com`).

In the code examples on the page (inside <RequestExamples />), the schema will be displayed as a JSON object showing the field names and types.

{
  "email": "<string>",
  "name": "<string>"
}

For more flexibility or organisation you can choose to define schemas in separate files. This helps reduce duplication in your API endpoint pages.

Schema files are also the only supported way to nest objects or use arrays in your endpoint definition.

example

When defining a schema in the frontmatter, you can also define a related example for the request or response body.

This is useful if you want to show a real example of the request or response body, rather than the schema definition.

example can be added to requests and responses, in the request.body.example and responses.*.example keys.

---
api:
  endpoint:
    post /v1/users:
      request:
        body:
          schema:
            email: string
            name: string
          example:
            email: user@example.com
            name: Jane Doe

example data will be shown in the code examples on the page instead of the schema definition.

{
  "email": "user@example.com",
  "name": "Jane Doe"
}