Doxbrix has purpose-built blocks for documenting REST APIs. Instead of hand-building tables and code blocks, you use ` ` with ` ` and ` ` children — semantic com...
Doxbrix has purpose-built blocks for documenting REST APIs. Instead of hand-building tables and code blocks, you use ` ` with ` ` and ` ` children — semantic com...
Doxbrix has purpose-built blocks for documenting REST APIs. Instead of hand-building tables and code blocks, you use <ApiEndpoint> with <Param> and <Response> children — semantic components that render a clean, structured endpoint reference with an HTTP-method badge.
Three ways to create one
In the content tree, hover a space or group, click +, choose Add page, and pick API reference in the Choose a template dialog. The new page starts with a complete <ApiEndpoint> — method, path, sample parameters, a request body, and 200/404 responses — ready to edit.
On any page, press <kbd>/</kbd> and choose API Endpoint (/api). Add standalone Parameter Table (/params) and Response Example (/response) blocks alongside narrative content.
Hover a space or group, click +, and choose Add API reference to import a spec and generate a page per operation.
The ApiEndpoint block
<ApiEndpoint> wraps a single endpoint. It renders the method badge, the path, and a summary, and holds the parameter and response blocks:
<ApiEndpoint method="POST" path="/users" baseUrl="https://api.example.com" summary="Create a user">
Creates a new user. The account starts inactive until verified.
</ApiEndpoint>| Attribute | Description |
|---|---|
| `method` | HTTP verb — `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, etc. (renders a colored badge) |
| `path` | The endpoint path; supports `{placeholders}` for path parameters |
| `baseUrl` | The API base URL shown with the path |
| `summary` | A short one-line description of the endpoint |
Parameters
Document each input with <Param>. Use the in attribute to say where the parameter goes, and mark required ones with required:
<ApiEndpoint method="GET" path="/users/{id}" baseUrl="https://api.example.com" summary="Get a user">
<Param name="id" in="path" type="string" required>The unique user ID.</Param>
<Param name="include" in="query" type="string">Comma-separated related resources to embed.</Param>
<Param name="Authorization" in="header" type="string" required>Bearer token.</Param>
</ApiEndpoint>| Attribute | Description |
|---|---|
| `name` | Parameter name |
| `in` | Location — `path`, `query`, `header`, or `body` |
| `type` | Data type — `string`, `number`, `boolean`, `object`, … |
| `required` | Mark the parameter as required |
For a standalone table of parameters outside an endpoint, use <ParameterTable title="Query Parameters">…</ParameterTable>.
Responses
Document each response with <Response> — its status, content type, description, and an example body:
<Response status="200" contentType="application/json" description="User created">
{ "id": "u_123", "status": "inactive" }
</Response>
<Response status="400" contentType="application/json" description="Validation error">
{ "error": "validation_error", "field": "email" }
</Response>| Attribute | Description |
|---|---|
| `status` | HTTP status code |
| `contentType` | Response media type, e.g. `application/json` |
| `description` | When this response occurs |
Document the common error responses too — a good reference covers 4xx cases, not just the happy path. For a standalone, tabbed set of response examples, use <ResponseExample>…</ResponseExample>.
A complete endpoint
Putting it together:
<ApiEndpoint method="POST" path="/pages" baseUrl="https://api.doxbrix.io/v1" summary="Create a page">
Creates a new draft page in a project.
<Param name="Authorization" in="header" type="string" required>Bearer token.</Param>
<Param name="title" in="body" type="string" required>The page title.</Param>
<Param name="spaceId" in="body" type="string" required>The space to create the page in.</Param>
<Response status="201" contentType="application/json" description="Created">
{ "id": "pg_123", "status": "draft" }
</Response>
<Response status="400" contentType="application/json" description="Validation error">
{ "error": "validation_error", "field": "title" }
</Response>
</ApiEndpoint>Generate from an OpenAPI spec
If you have an OpenAPI (Swagger) specification, you don't have to write endpoints by hand:
In the content tree, hover a space or group, click +, and choose Add API reference.
In the Import OpenAPI Spec dialog, either Upload file (an openapi.json) or switch to Paste JSON and paste the spec, then click Import.
Doxbrix parses the spec and creates an endpoint page per operation, pre-filled with the method, path, parameters, and responses. Add narrative, examples, and context.
Organizing an API reference
- Keep one endpoint per page so each has a clean deep link.
- Group endpoints by resource using groups (Users, Projects, Pages…).
- Put it all in a dedicated API Reference space.
See the API Reference space in these docs for a worked example.