ResponseField | NookDocs

Usage

<ResponseField> is the output twin of <ParamField>. Use one per field in an API response body to explain what the caller can expect back.

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

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

<ResponseField name="status" type="enum">
  One of `queued`, `building`, `deployed`, or `failed`.
</ResponseField>

idstringrequired

Unique identifier for the resource, generated on the server.

created_atstring (ISO 8601)

UTC timestamp when the resource was created.

statusenum

One of queued, building, deployed, or failed.

Deprecated fields

Mark a field as deprecated to strikethrough the name and add a warning badge:

<ResponseField name="legacy_id" type="string" deprecated>
  Use `id` instead. Will be removed in v2.
</ResponseField>

legacy_idstringdeprecated

Use id instead. Will be removed in v2.

Grouping by status code

When an endpoint returns different shapes for different status codes, group each shape under its own heading:

## 200 — Success

<ResponseField name="id" type="string" required>
  The created resource ID.
</ResponseField>

<ResponseField name="status" type="string" required>
  Always `created` on a successful response.
</ResponseField>

## 400 — Bad Request

<ResponseField name="error" type="string" required>
  Error code (e.g. `invalid_request`).
</ResponseField>

<ResponseField name="message" type="string" required>
  Human-readable error description.
</ResponseField>

A future version of the platform will introduce a dedicated <ResponseExample> wrapper for tabbed status-code rendering — until then, h2 sections are the convention.

Auto-generation from OpenAPI

If your project has an OpenAPI spec, ResponseField entries are generated automatically from the response schema on API reference pages. See the OpenAPI integration guide.

Default value

Show the default value for an optional field using the default prop:

<ResponseField name="page_size" type="number" default="20">
  Number of items per page. Omit to use the server default.
</ResponseField>

page_sizenumberdefault: 20

Number of items per page. Omit to use the server default.

Pre and post annotations

The pre and post props add inline text immediately before or after the field name. Use them for path prefixes, array indicators, or units:

<ResponseField name="items" type="object[]" pre="data." post="[*]">
  Array of resource objects nested under the `data` key.
</ResponseField>

<ResponseField name="latency" type="number" post=" ms">
  Server-side processing time in milliseconds.
</ResponseField>

data.items[*]object[]

Array of resource objects nested under the data key.

latency msnumber

Server-side processing time in milliseconds.

Props

Prop	Type	Required	Description
`name`	`string`	Yes	Field name as it appears in the response JSON
`type`	`string`	No	Type annotation (e.g. `string`, `number`, `object`, enum)
`required`	`boolean`	No	Marks the field as always-present
`deprecated`	`boolean`	No	Strikethrough name + "deprecated" badge
`default`	`string`	No	Default value shown as a badge next to the type
`pre`	`string \| string[]`	No	Labels rendered immediately before the field name
`post`	`string \| string[]`	No	Labels rendered immediately after the field name
`enum`	`string[]`	No	Closed set of possible values — rendered as small `options:` chips below the description