Response Field

Reference for documenting API response fields with types, requirements, and status indicators.

Overview

The ResponseField component documents the fields returned by your API responses. It shows:

• Field name: The key in the JSON or response object.
• Type: The data type such as string, integer, or object.
• Status: Required and Deprecated badges.
• Rich descriptions: Human-readable explanations of what the field represents.

You can use ResponseField in two ways:

• Editor UI: Add and edit response fields visually with a form-based panel.
• MDX: Use the <ResponseField> component directly in your content.

ResponseField is similar to ParamField but specifically designed for documenting API response bodies and returned data structures.

Using with Web Editor

Add a ResponseField block

1. Place your cursor where you want to describe a response field.
2. Type / to open the command menu and search for Response Field.
3. Select Response Field to insert the component.

A new response field row appears with a default name and type plus a description placeholder.

ResponseField block in the Web Editor

Prefer writing in code?

You can switch to MDX view inside the Web Editor to write or edit this component using the same syntax as the Code Editor. This is useful if you want full control while staying in the Web Editor.

Edit field metadata

To change the label and status:

1. Click the three-dot menu on the right side of the ResponseField block.
2. In the Response Field settings panel, you can edit:

• Field Name: The name of the field in the response payload (for example, id, status, user).
• Type: The data type of the field (for example, string, integer, boolean, object, array).
• Required: Toggle on to mark the field as required in the response.
• Deprecated: Toggle on to show that the field is deprecated.

Click Save to apply your changes.

Edit the description

• Click in the description area under the badges (for example, Response field description…).

• Add your explanation using any supported content:

  • Text and headings
  • Lists and tables
  • Code blocks showing example responses
  • Callouts and other MDX components

Using with Code Editor

Basic syntax

Use the <ResponseField> component to document API response fields with their type and status.

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

idstring

Required

Unique identifier for the resource.

Examples

Optional field

<ResponseField name="description" field-type="string">
  Optional description text for the resource.
</ResponseField>

descriptionstring

Optional description text for the resource.

Deprecated field

<ResponseField name="legacy_id" field-type="integer" deprecated="true">
  Deprecated legacy identifier. Use `id` instead.
</ResponseField>

legacy_idinteger

Deprecated

Deprecated legacy identifier. Use id instead.

Complex type

<ResponseField name="user" field-type="object" required="true">
  User object containing profile information and preferences.
</ResponseField>

userobject

Required

User object containing profile information and preferences.

Advanced options

Attributes

[path

namestring](/content/docs/components/responsefield#path-name/index.html)

Field name displayed in the response documentation (default: "response").

[path

field-typestring](/content/docs/components/responsefield#path-field-type/index.html)

Data type: string, integer, boolean, object, array, etc.

[path

requiredstring](/content/docs/components/responsefield#path-required/index.html)

Set to "true" for required fields (default: "false").

[path

deprecatedstring](/content/docs/components/responsefield#path-deprecated/index.html)

Set to "true" to mark as deprecated (default: "false").