Skip to main content

Response Fields

2 min readStableIntermediate

ResponseField documents the shape of an API response body: the field name, its data type, and whether it always comes back. Pair it with API blocks for the endpoint itself and parameter fields for the request side.

Quick Start

Two fields that every successful response includes.

idstringrequired

Unique identifier for the resource.

titlestringrequired

Document title as provided during creation.

api-reference.mdx
MDX
<ResponseField name="id" type="string" required>
  Unique identifier for the resource.
</ResponseField>
 
<ResponseField name="title" type="string" required>
  Document title as provided during creation.
</ResponseField>

Adding Options

Drop required for fields the API only sometimes returns, and put anything you like in the type label.

createdAtstring (ISO 8601)

Timestamp of when the document was created.

statusstring

Current document status. Only included for authenticated editors.

api-reference.mdx
MDX
<ResponseField name="createdAt" type="string (ISO 8601)">
  Timestamp of when the document was created.
</ResponseField>
 
<ResponseField name="status" type="string">
  Current document status. Only included for authenticated editors.
</ResponseField>

Advanced

Dot notation in name is the convention for nested objects — the component prints whatever string you give it, so the dots do the explaining. deprecated strikes through a field on its way out and stacks with required. The last field carries nothing but a name: no type chip, no labels, no description line.

paginationobjectrequired

Pagination metadata for navigating result pages.

pagination.pageintegerrequired

Current page number.

pagination.totalintegerrequired

Total number of items across all pages.

pagination.hasMorebooleanrequired

Whether additional pages are available.

pagination.nextCursorstringdeprecated

Cursor for the next page. Read pagination.hasMore instead.

pagination.offsetintegerrequireddeprecated

Offset of the first item. Always sent, and removed in v3.

_links
api-reference.mdx
MDX
<ResponseField name="pagination" type="object" required>
  Pagination metadata for navigating result pages.
</ResponseField>
 
<ResponseField name="pagination.page" type="integer" required>
  Current page number.
</ResponseField>
 
<ResponseField name="pagination.total" type="integer" required>
  Total number of items across all pages.
</ResponseField>
 
<ResponseField name="pagination.hasMore" type="boolean" required>
  Whether additional pages are available.
</ResponseField>
 
<ResponseField name="pagination.nextCursor" type="string" deprecated>
  Cursor for the next page. Read `pagination.hasMore` instead.
</ResponseField>
 
<ResponseField name="pagination.offset" type="integer" required deprecated>
  Offset of the first item. Always sent, and removed in v3.
</ResponseField>
 
<ResponseField name="_links" />

Options

name is the only required prop. ResponseField takes four props plus its children — it shares its rendering with ParamField but leaves out location and defaultValue, which describe a request rather than a response.

namestringrequired

Field name, rendered in bold monospace. Dot notation for nesting is a convention; the string renders as written.

typestring

Data type label shown in a small outlined chip next to the name. Any string works, so string (ISO 8601) and array of object are both fine. Omit it and no chip renders.

requiredboolean

Shows a red "required" label. Leave it off for fields the API only sometimes returns; there is no "optional" label.

deprecatedboolean

Shows an amber "deprecated" label, strikes through the name, and drops the field to 60% opacity. It stacks with required.

childrenReactNode

Description text under the field; supports inline Markdown. With no children, the description line is skipped and only the name row renders.

Related pages

API Blocks

Parameter Fields

Was this page helpful?