---
title: Fields
description: Document API parameters and response fields with ParamField and ResponseField components. Supports types, defaults, and nested objects.
---

> **For AI agents:** the complete documentation index is at [llms.txt](/docs/llms.txt). Append `.md` to any page URL for its markdown version.

Fields help you document API parameters and response fields in a clear, consistent format.

## Usage

```mdx
<ParamField query="limit" type="number" default={10}>
  Maximum number of results to return.
</ParamField>
```

## ParamField

Use `ParamField` to document API request parameters. Specify the parameter location using one of `body`, `query`, `path`, or `header`.

<ParamField body="user_id" type="string" required>
  The unique identifier for the user.
</ParamField>

<ParamField query="limit" type="number" default={10}>
  Maximum number of results to return.
</ParamField>

<ParamField header="Authorization" type="string" required>
  Bearer token for authentication.
</ParamField>

```mdx
<ParamField body="user_id" type="string" required>
  The unique identifier for the user.
</ParamField>

<ParamField query="limit" type="number" default={10}>
  Maximum number of results to return.
</ParamField>

<ParamField header="Authorization" type="string" required>
  Bearer token for authentication.
</ParamField>
```

### Path Parameters

<ParamField path="id" type="string" required>
  Resource identifier in the URL path.
</ParamField>

```mdx
<ParamField path="id" type="string" required>
  Resource identifier in the URL path.
</ParamField>
```

### ParamField Props

<ParamField name="body" type="string">
  Parameter name for body parameters.
</ParamField>

<ParamField name="query" type="string">
  Parameter name for query string parameters.
</ParamField>

<ParamField name="path" type="string">
  Parameter name for URL path parameters.
</ParamField>

<ParamField name="header" type="string">
  Parameter name for header parameters.
</ParamField>

<ParamField name="type" type="string">
  Data type (string, number, boolean, array, object).
</ParamField>

<ParamField name="required" type="boolean">
  Shows a "required" badge.
</ParamField>

<ParamField name="default" type="string | number | boolean">
  Default value when not provided.
</ParamField>

## ResponseField

Use `ResponseField` to document API response properties.

<ResponseField name="id" type="string" required>
  Unique identifier for the resource.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp of when the resource was created.
</ResponseField>

<ResponseField name="status" type="string" default="pending">
  Current status of the request.
</ResponseField>

```mdx
<ResponseField name="id" type="string" required>
  Unique identifier for the resource.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp of when the resource was created.
</ResponseField>

<ResponseField name="status" type="string" default="pending">
  Current status of the request.
</ResponseField>
```

### Deprecated Fields

Mark fields as deprecated to indicate they'll be removed in a future version:

<ResponseField name="legacy_id" type="number" deprecated>
  Use `id` instead. This field will be removed in v2.
</ResponseField>

```mdx
<ResponseField name="legacy_id" type="number" deprecated>
  Use `id` instead. This field will be removed in v2.
</ResponseField>
```

### Labels

Add context with `pre` and `post` labels:

<ResponseField name="webhook_url" type="string" pre={["optional"]} post={["v2.1+"]}>
  URL to receive webhook notifications.
</ResponseField>

```mdx
<ResponseField name="webhook_url" type="string" pre={["optional"]} post={["v2.1+"]}>
  URL to receive webhook notifications.
</ResponseField>
```

### Nested Objects

Combine with `Expandable` to document nested object properties:

<ResponseField name="user" type="object">
  The user who created the resource.
  <Expandable title="user properties">
    <ResponseField name="id" type="string" required>
      User's unique identifier.
    </ResponseField>
    <ResponseField name="email" type="string" required>
      User's email address.
    </ResponseField>
    <ResponseField name="name" type="string">
      User's display name.
    </ResponseField>
  </Expandable>
</ResponseField>

```mdx
<ResponseField name="user" type="object">
  The user who created the resource.
  <Expandable title="user properties">
    <ResponseField name="id" type="string" required>
      User's unique identifier.
    </ResponseField>
    <ResponseField name="email" type="string" required>
      User's email address.
    </ResponseField>
    <ResponseField name="name" type="string">
      User's display name.
    </ResponseField>
  </Expandable>
</ResponseField>
```

### ResponseField Props

<ParamField name="name" type="string" required>
  Field name.
</ParamField>

<ParamField name="type" type="string">
  Data type.
</ParamField>

<ParamField name="required" type="boolean">
  Shows a "required" badge.
</ParamField>

<ParamField name="deprecated" type="boolean">
  Shows field as deprecated with strikethrough.
</ParamField>

<ParamField name="default" type="string | number | boolean">
  Default value.
</ParamField>

<ParamField name="pre" type="string[]">
  Labels displayed before the field name.
</ParamField>

<ParamField name="post" type="string[]">
  Labels displayed after the field name.
</ParamField>

## What's Next?

<Columns cols={2}>
  <Card title="Components Overview" icon="puzzle-piece" href="/components/overview">
    Browse all available components
  </Card>
  <Card title="MDX Basics" icon="file-code" href="/content/mdx-basics">
    Learn how to use components in MDX
  </Card>
</Columns>