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

API Documentation

How to create beautiful API reference documentation with Syntext.

5 min read

This guide shows how to create structured API reference documentation with individual endpoint pages, grouped navigation, and rich parameter documentation.

Structure

Syntext recommends organizing API docs with one file per endpoint:

text
docs/
├── api-reference/
│ ├── overview.mdx # API introduction
│ ├── authentication.mdx # Auth guide
│ ├── projects/
│ │ ├── list.mdx # GET /projects
│ │ ├── get.mdx # GET /projects/{id}
│ │ ├── create.mdx # POST /projects
│ │ ├── update.mdx # PATCH /projects/{id}
│ │ └── delete.mdx # DELETE /projects/{id}
│ ├── builds/
│ │ ├── list.mdx
│ │ ├── get.mdx
│ │ └── trigger.mdx
│ └── search/
│ └── query.mdx

Endpoint Frontmatter

Each endpoint file should include protocol-specific frontmatter:

mdx
---
title: Create Project
protocol: rest
method: POST
endpoint: /v1/projects
description: "Create a new documentation project"
---

REST Endpoints

FieldRequiredDescription
titleYesPage title and sidebar label
protocolYesSet to rest
methodYesHTTP method: GET, POST, PUT, PATCH, DELETE
endpointYesAPI path (e.g., /v1/projects/{id})
descriptionNoBrief description for search results

GraphQL Operations

mdx
---
title: Get Session
protocol: graphql
operation: query
name: GetSession
---

WebSocket Events

mdx
---
title: Session Connected
protocol: websocket
event: session.connected
direction: server-to-client
---

Group endpoints under sections in your syntext.json:

json
{
"navigation": [
{
"group": "API Reference",
"pages": [
"api-reference/overview",
"api-reference/authentication"
]
},
{
"group": "Projects",
"pages": [
"api-reference/projects/list",
"api-reference/projects/get",
"api-reference/projects/create",
"api-reference/projects/update",
"api-reference/projects/delete"
]
},
{
"group": "Builds",
"pages": [
"api-reference/builds/list",
"api-reference/builds/get",
"api-reference/builds/trigger"
]
}
]
}

Each group becomes a labelled group in the sidebar, in the order listed.

Endpoint Component

On an endpoint page the method and path bar is drawn from the method and endpoint frontmatter, so you don't add it yourself. On a guide page, use the <Endpoint> component to display a method and path:

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

Renders as a styled badge:

POST/v1/projects

Parameter Documentation

Request Parameters

Use <ParamField> to document parameters:

mdx
<ParamField body="name" type="string" required>
Project display name.
</ParamField>
<ParamField query="page" type="integer" default="1">
Page number for pagination.
</ParamField>
<ParamField path="projectId" type="string" required>
The project ID (e.g., `3f2a9c1e-8b4d-4e7a-9c21-5d6e7f8a9b0c`).
</ParamField>
<ParamField header="X-Request-Id" type="string">
Optional request tracking ID.
</ParamField>

ParamField Props

PropTypeDescription
bodystringBody parameter name
querystringQuery string parameter name
pathstringPath parameter name
headerstringHeader name
cookiestringCookie name (doc engine v2)
deprecatedboolean or stringMarks the parameter deprecated; a string says what to use instead (doc engine v2)
typestringData type (e.g., string, integer, boolean, object)
requiredbooleanWhether the parameter is required
defaultstringDefault value

The location spellings (body=, query=, …) work on API reference pages and on doc engine v2. On doc engine v1 guide pages, write name= instead.

Nested Objects

Use <Expandable> for nested object properties:

mdx
<ParamField body="settings" type="object">
Project settings.
<Expandable title="properties">
<ParamField body="settings.aiEnabled" type="boolean" default="true">
Enable AI assistant.
</ParamField>
<ParamField body="settings.searchEnabled" type="boolean" default="true">
Enable full-text search.
</ParamField>
</Expandable>
</ParamField>

Response Documentation

Use <ResponseField> for response properties:

mdx
<ResponseField name="data" type="object">
The response payload.
<Expandable title="properties">
<ResponseField name="id" type="string">
Unique identifier.
</ResponseField>
<ResponseField name="name" type="string">
Display name.
</ResponseField>
<ResponseField name="createdAt" type="string">
ISO 8601 timestamp.
</ResponseField>
</Expandable>
</ResponseField>

Code Examples

Include examples in multiple languages using <CodeGroup>:

mdx
<CodeGroup>
\`\`\`bash title="cURL"
curl -X POST https://api.example.com/v1/projects \\
-H "Authorization: Bearer stx_abc12345_..." \\
-H "Content-Type: application/json" \\
-d '{"name": "My Project"}'
\`\`\`
\`\`\`typescript title="SDK"
import { Client } from '@example/sdk'
const client = new Client('stx_abc12345_...')
const project = await client.projects.create({
name: 'My Project',
})
\`\`\`
\`\`\`python title="Python"
from example import Client
client = Client("stx_abc12345_...")
project = client.projects.create(name="My Project")
\`\`\`
</CodeGroup>

Error Documentation

Document error responses with HTTP status codes and response body examples:

mdx
## Error Responses
### 400 Bad Request
Returned when required fields are missing or have invalid values.
\`\`\`json
{
"error": {
"code": "invalid_request",
"message": "Required field missing or invalid value",
"details": {
"field": "name",
"issue": "Name is required"
}
}
}
\`\`\`
### 404 Not Found
Returned when the resource does not exist.
\`\`\`json
{
"error": {
"code": "not_found",
"message": "Resource does not exist"
}
}
\`\`\`
### 409 Conflict
Returned when a resource with this identifier already exists.
\`\`\`json
{
"error": {
"code": "conflict",
"message": "Resource with this identifier already exists"
}
}
\`\`\`
### 429 Too Many Requests
Returned when the rate limit has been exceeded.
\`\`\`json
{
"error": {
"code": "rate_limited",
"message": "Too many requests. Try again later.",
"retryAfter": 60
}
}
\`\`\`

OpenAPI Import

If you have an OpenAPI spec, the fastest path is build-time generation — list the spec in syntext.json and every deploy regenerates the endpoint pages:

json
{
"openapi": [
{ "path": "./openapi/users.yaml", "prefix": "api-reference/users" }
]
}

Hand-written MDX files at the same paths always take precedence over generated pages. See the OpenAPI sync recipe for details.

Complete Example

Here's a full endpoint page:

mdx
---
title: Create Project
protocol: rest
method: POST
endpoint: /v1/projects
description: "Create a new documentation project"
---
# Create Project
Create a new documentation project in your organization.
## Request Body
<ParamField body="name" type="string" required>
Project display name.
</ParamField>
<ParamField body="slug" type="string">
URL-friendly identifier. Auto-generated if not provided.
</ParamField>
<ParamField body="settings" type="object">
Project settings.
<Expandable title="properties">
<ParamField body="settings.aiEnabled" type="boolean" default="true">
Enable AI assistant.
</ParamField>
</Expandable>
</ParamField>
## Response
<ResponseField name="data" type="object">
The created project.
<Expandable title="properties">
<ResponseField name="id" type="string">
Project identifier.
</ResponseField>
<ResponseField name="name" type="string">
Project name.
</ResponseField>
</Expandable>
</ResponseField>
## Example
<CodeGroup>
\`\`\`bash title="cURL"
curl -X POST https://api.example.com/v1/projects \\
-H "Authorization: Bearer stx_abc12345_..." \\
-d '{"name": "My Docs"}'
\`\`\`
</CodeGroup>
## Error Responses
### 400 Bad Request
\`\`\`json
{
"error": {
"code": "invalid_request",
"message": "Missing required field: name"
}
}
\`\`\`
### 409 Conflict
\`\`\`json
{
"error": {
"code": "conflict",
"message": "A project with this slug already exists"
}
}
\`\`\`
Was this page helpful? Yes No
Product
Resources
Company
© 2026 SyntextBuilt with Syntext