# API fields

> Document request parameters and response fields with name, type, and required markers. Nest child fields and show request and response examples.

API fields list the parameters an endpoint takes and the fields it returns. Each one shows the name, its type, and markers like `required`, with a description underneath. Write them by hand on any page. For a full reference built from a spec file, see [OpenAPI](https://docs.typemark.dev/api-reference/openapi).

<ParamField path="id" type="string" required>
  The ID of the user to fetch.
</ParamField>

<ParamField query="expand" type="string[]" default="[]">
  Related objects to include in the response, such as `team`.
</ParamField>

```mdx
<ParamField path="id" type="string" required>
  The ID of the user to fetch.
</ParamField>

<ParamField query="expand" type="string[]" default="[]">
  Related objects to include in the response, such as `team`.
</ParamField>
```

## Parameters

`<ParamField>` documents something the request sends. Name the field with the prop for where it goes: `path`, `query`, `body`, or `header`. That location is shown next to the name.

<ParamField header="Authorization" type="string" required>
  `Bearer` followed by your API key.
</ParamField>

<ParamField body="email" type="string" required>
  The new user's email address.
</ParamField>

<ParamField body="nickname" type="string" deprecated>
  Use `display_name` instead.
</ParamField>

```mdx
<ParamField header="Authorization" type="string" required>
  `Bearer` followed by your API key.
</ParamField>

<ParamField body="email" type="string" required>
  The new user's email address.
</ParamField>

<ParamField body="nickname" type="string" deprecated>
  Use `display_name` instead.
</ParamField>
```

## Response fields

`<ResponseField>` documents something the response returns. Name it with `name`.

<ResponseField name="id" type="string" required>
  Unique ID for the user.
</ResponseField>

<ResponseField name="created_at" type="string">
  When the user was created, as an ISO 8601 timestamp.
</ResponseField>

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

<ResponseField name="created_at" type="string">
  When the user was created, as an ISO 8601 timestamp.
</ResponseField>
```

## Nested fields

Wrap child fields in `<Expandable>` inside the parent field. Readers click **Show** to see them, so long objects don't take over the page.

<ResponseField name="team" type="object">
  The team the user belongs to.

  <Expandable title="properties">
    <ResponseField name="team.id" type="string">
      Unique ID for the team.
    </ResponseField>
    <ResponseField name="team.name" type="string">
      The team's display name.
    </ResponseField>
  </Expandable>
</ResponseField>

```mdx
<ResponseField name="team" type="object">
  The team the user belongs to.

  <Expandable title="properties">
    <ResponseField name="team.id" type="string">
      Unique ID for the team.
    </ResponseField>
    <ResponseField name="team.name" type="string">
      The team's display name.
    </ResponseField>
  </Expandable>
</ResponseField>
```

The toggle reads "Show" followed by the `title`, so `title="properties"` gives **Show properties**. Without a title it reads **Show details**.

## Request and response examples

`<RequestExample>` and `<ResponseExample>` turn the code blocks inside them into a [code group](https://docs.typemark.dev/components/code-blocks#code-groups), with one tab per block. They appear where you put them in the page.

<RequestExample>
  ```bash cURL
  curl https://api.acme.com/v1/users/usr_123 \
    -H "Authorization: Bearer sk_live_abc123"
  ```
  ```javascript Node.js
  const user = await acme.users.retrieve("usr_123");
  ```
</RequestExample>

<ResponseExample>
  ```json 200
  { "id": "usr_123", "email": "ada@example.com" }
  ```
  ```json 404
  { "error": "not_found" }
  ```
</ResponseExample>

````mdx
<RequestExample>
  ```bash cURL
  curl https://api.acme.com/v1/users/usr_123 \
    -H "Authorization: Bearer sk_live_abc123"
  ```
  ```javascript Node.js
  const user = await acme.users.retrieve("usr_123");
  ```
</RequestExample>

<ResponseExample>
  ```json 200
  { "id": "usr_123", "email": "ada@example.com" }
  ```
  ```json 404
  { "error": "not_found" }
  ```
</ResponseExample>
````

## Endpoint lines

`<API>` shows one endpoint: its method and path on a single line. When your site has a page for the same method and path, the line links to it: a page you [wrote for the endpoint](https://docs.typemark.dev/api-reference/openapi#write-an-endpoints-page), or else the one your [OpenAPI reference](https://docs.typemark.dev/api-reference/openapi) generates.

<API method="GET" path="/users/{id}" />

```mdx
<API method="GET" path="/users/{id}" />
```

Use it in guides to point readers at the endpoint a step calls. Write the path exactly as it is in your spec, including parameters in braces.

## Props

### API

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `method` | string | `GET` | The HTTP method, like `GET` or `POST`. |
| `path` | string | none | The endpoint's path, like `/users/{id}`. |

### ParamField and ResponseField

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `path`, `query`, `body`, `header` | string | none | `ParamField` only. The field's name; the prop you use sets the location label. |
| `name` | string | none | The field's name. Use it on `ResponseField`, or on a `ParamField` without a location. |
| `type` | string | none | Type shown next to the name, like `string` or `object`. |
| `required` | boolean | `false` | Shows a `required` marker. |
| `deprecated` | boolean | `false` | Shows a `deprecated` marker. |
| `default` | string | none | Shows `default:` with the value. |

The content between the tags is the field's description.

### Expandable

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `title` | string | none | Completes the toggle label: **Show** + `title`. |
| `defaultOpen` | boolean | `false` | Starts expanded. |

`<RequestExample>` and `<ResponseExample>` take no props. Label each code block the way you would in a code group.

## In the visual editor

These components show as read-only source in the visual editor and save back unchanged. Edit them in source mode. `<API>` shows as an endpoint block you can move or delete.
