/Docs
Search docs or ask a question⌘K
DocsAgent
Changelog
Components API Components

API Components

Components for documenting HTTP APIs.

6 min read

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:

mdx
<Endpoint method="POST" path="/v1/users" />
POST/v1/users

url 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:

mdx
<ParamField name="email" type="string" required>
User's email address. Must be unique across the organization.
</ParamField>
<ParamField name="role" type="string" default="member">
User role. One of: `admin`, `editor`, `member`.
</ParamField>
<ParamField name="metadata" type="object">
Optional key-value pairs for custom data.
</ParamField>
NameDescription
email:stringRequired
User's email address. Must be unique across the organization.
role:string
User role. One of: admin, editor, member.
Default"member"
metadata:object
Optional key-value pairs for custom data.

ParamField Props

PropTypeDescription
namestringParameter name. Optional when a location prop carries it
path, query, header, body, cookiestringThe parameter name, written as its location — <ParamField query="limit"> — so name isn't needed. Doc engine v2 shows a location chip beside the name
typestringData type, shown as a chip. Optional
requiredbooleanMark as required
defaultstringDefault value
deprecatedboolean or stringBare (deprecated) adds a Deprecated badge; with text (deprecated="Use name instead.") the badge plus the text as a notice. Doc engine v2 only
childrenReactNodeDescription
mdx
<ParamField query="limit" type="integer" default="20">
Results per page, up to 100.
</ParamField>
<ParamField header="Idempotency-Key" name="Idempotency-Key" type="string">
Makes a retried request safe.
</ParamField>
<ParamField query="page_token" type="string" deprecated="Use cursor instead.">
The old pagination token.
</ParamField>

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:

mdx
<ResponseField name="id" type="string">
Unique identifier for the user.
</ResponseField>
<ResponseField name="created_at" type="string">
Timestamp when the user was created, in ISO 8601.
</ResponseField>
NameDescription
id:string
Unique identifier for the user.
created_at:string
Timestamp when the user was created, in ISO 8601.

<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:

mdx
<Property name="timeout" type="number" default="30">
Seconds to wait before the request is abandoned.
</Property>
<Property name="retries" type="integer" required>
How many times to retry a failed delivery.
</Property>
<Property name="legacyMode" type="boolean" deprecated>
Kept for older clients.
</Property>
PropTypeDescription
namestringThe property name (required), in monospace
typestringData type, e.g. string or boolean
requiredbooleanAdds a required badge. Write it bare
defaultstringDefault value, shown under the description
deprecatedbooleanAdds a deprecated badge and strikes the name through. Write it bare
Note

Doc engine v2 only. On pages that must also render on v1, use ResponseField or ParamField.

Expandable (Nested Objects)

Document nested structures:

mdx
<Expandable title="address">
<ResponseField name="street" type="string">
Street address
</ResponseField>
<ResponseField name="city" type="string">
City name
</ResponseField>
<ResponseField name="country" type="string">
ISO country code
</ResponseField>
</Expandable>
Show 3 child attributesobject
PropTypeDescription
titlestringThe label of the toggle line, e.g. the object name
typestringThe type chip on the toggle line, e.g. object or array. Default object. Doc engine v2 only — v1 ignores it

RequestExample

Show example requests:

mdx
<RequestExample>
```bash title="cURL"
curl -X POST https://api.example.com/v1/users \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{"email": "alice@example.com", "name": "Alice"}'
```
</RequestExample>

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:

mdx
<ResponseExample>
```json title="200 OK"
{
"id": "usr_abc123",
"email": "alice@example.com",
"name": "Alice",
"created_at": "2024-01-15T12:00:00Z"
}
```
</ResponseExample>

StatusCodes

A headerless status-code table, each code drawn as a coloured chip. Wrap an ordinary Markdown table:

mdx
<StatusCodes>
| Code | Meaning |
|------|---------|
| 200 | The account was created. |
| 401 | Missing or invalid API key. |
| 403 | The key lacks the required scope. |
| 429 | Rate limited — retry after the `Retry-After` header. |
| 500 | Something went wrong on our side. |
</StatusCodes>

The chip colour follows the code:

CodesChip
2xxsuccess
401, 403error — an unauthorised request is a failure, not a caution
other 4xxwarning
5xxerror
anything elseneutral

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:

mdx
---
title: Order updates
protocol: websocket
event: order.updated
direction: server-to-client
---
### order.updated
Server to client.
<ResponseField name="id" type="string">
The order ID.
</ResponseField>
<ResponseField name="status" type="string">
The new status.
</ResponseField>

See Protocol frontmatter for each protocol's keys.

Complete API Page Example

mdx
---
title: Create User
protocol: rest
method: POST
endpoint: /v1/users
---
# Create User
Create a new user account. The endpoint bar comes from the `method` and
`endpoint` frontmatter.
## Request Body
<ParamField name="email" type="string" required>
User's email address.
</ParamField>
<ParamField name="name" type="string" required>
User's display name.
</ParamField>
<ParamField name="role" type="string" default="member">
User role: `admin`, `editor`, or `member`.
</ParamField>
## Response
<ResponseField name="id" type="string">
Unique user identifier.
</ResponseField>
<ResponseField name="email" type="string">
User's email address.
</ResponseField>
## Examples
<CodeGroup>
\`\`\`bash title="cURL"
curl -X POST https://api.example.com/v1/users \
-H "Authorization: Bearer $API_KEY" \
-d '{"email": "alice@example.com", "name": "Alice"}'
\`\`\`
\`\`\`javascript title="JavaScript"
const res = await fetch("https://api.example.com/v1/users", {
method: "POST",
headers: { Authorization: `Bearer ${API_KEY}` },
body: JSON.stringify({ email: "alice@example.com", name: "Alice" }),
});
\`\`\`
</CodeGroup>
Was this page helpful? Yes No
Previous
Product
Resources
Company
© 2026 SyntextBuilt with Syntext