API Components
Components for documenting HTTP APIs.
Syntext provides components for documenting HTTP APIs. For WebSocket, GraphQL, gRPC and event-driven APIs, set the page's protocol frontmatter or import a schema — there are no separate MDX components for them. See Other protocols.
Endpoint
Display API endpoint information:
/v1/usersurl is a deprecated name for path (<Endpoint url="/v1/users">). It still
works until the end of its notice window;
stx migrate renames it.
Methods are colour-coded by your theme. On doc engine v2: GET green, POST
blue, PUT and PATCH amber, DELETE red.
On API reference pages the endpoint bar comes from the page's method and
endpoint frontmatter, so <Endpoint> belongs on guide pages.
ParamField
Document request parameters:
emailroleadmin, editor, member."member"metadataParamField Props
| Prop | Type | Description |
|---|---|---|
name | string | Parameter name. Optional when a location prop carries it |
path, query, header, body, cookie | string | The parameter name, written as its location — <ParamField query="limit"> — so name isn't needed. Doc engine v2 shows a location chip beside the name |
type | string | Data type, shown as a chip. Optional |
required | boolean | Mark as required |
default | string | Default value |
deprecated | boolean or string | Bare (deprecated) adds a Deprecated badge; with text (deprecated="Use name instead.") the badge plus the text as a notice. Doc engine v2 only |
children | ReactNode | Description |
cookie and the location chip are doc engine v2 only. On doc engine v1, guide
pages show the name from name; API pages also read it from path, query
or body, but a header or cookie field needs name to show its name.
ResponseField
Document response fields:
idcreated_at<ResponseField> takes name, type, required, default and deprecated,
as ParamField does. deprecated is doc engine v2 only:
bare, it adds a Deprecated badge; with text, the badge plus a notice.
Property
One documented property of an object or a config — the name, its type, required and deprecated badges, the description, and the default underneath:
| Prop | Type | Description |
|---|---|---|
name | string | The property name (required), in monospace |
type | string | Data type, e.g. string or boolean |
required | boolean | Adds a required badge. Write it bare |
default | string | Default value, shown under the description |
deprecated | boolean | Adds a deprecated badge and strikes the name through. Write it bare |
Doc engine v2 only. On pages that must also render on v1, use ResponseField or ParamField.
Expandable (Nested Objects)
Document nested structures:
streetcitycountry| Prop | Type | Description |
|---|---|---|
title | string | The label of the toggle line, e.g. the object name |
type | string | The type chip on the toggle line, e.g. object or array. Default object. Doc engine v2 only — v1 ignores it |
RequestExample
Show example requests:
On doc engine v2 endpoint pages, <RequestExample> and <ResponseExample> go in the right-hand column. A request with several languages gets a language menu beside its tabs (on phones, in place of them); the reader's choice is remembered across pages. Ordinary Example and Response sections are moved there too, and a page with no examples gets generated ones. Beside an authored request, your tabs stay first and a generated tab is added for each configured language they leave out, sending the request from your cURL; see REST frontmatter.
ResponseExample
Show example responses:
StatusCodes
A headerless status-code table, each code drawn as a coloured chip. Wrap an ordinary Markdown table:
The chip colour follows the code:
| Codes | Chip |
|---|---|
2xx | success |
401, 403 | error — an unauthorised request is a failure, not a caution |
other 4xx | warning |
5xx | error |
| anything else | neutral |
Colours come from your theme's status tokens, so a site that sets its own status palette gets it here too.
The table header is hidden visually but kept for screen readers, so the component stays readable with assistive technology. Wrap only the tables you want chipped — an ordinary table elsewhere on the page keeps its header.
Other protocols
Document WebSocket, GraphQL, gRPC and event APIs with protocol frontmatter
for the endpoint bar, <ParamField> / <ResponseField> for fields, and ###
headings for each event or method:
See Protocol frontmatter for each protocol's keys.