refrakt.md

Docs Runes Plan Blog Changelog

note

This rune is part of @refrakt-md/docs. Install with npm install @refrakt-md/docs and add "@refrakt-md/docs" to the packages array in your refrakt.config.json.

API

API endpoint documentation. Headings become the endpoint title, tables become parameter lists, code blocks become request/response examples, and blockquotes become notes.

GET endpoint

A basic GET endpoint with query parameters and a JSON response example.

{% api method="GET" path="/api/users" auth="Bearer token" %}
## List Users

Returns a paginated list of users. Requires authentication.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| page | number | no | Page number (default: 1) |
| limit | number | no | Items per page (default: 20) |
| sort | string | no | Sort field |

```json
{
  "users": [
    { "id": 1, "name": "Alice", "email": "[email protected]" }
  ],
  "total": 42,
  "page": 1
}
```

> Rate limited to 100 requests per minute per API key.
{% /api %}
<article data-rune="api">
  <meta content="GET" data-field="method">
  <meta content="/api/users" data-field="path">
  <meta content="Bearer token" data-field="auth">
  <div data-name="body">
    <h2 id="list-users">List Users</h2>
    <p>Returns a paginated list of users. Requires authentication.</p>
    <div class="rf-table-wrapper">
      <table>
        <thead>
          <tr>
            <th>Parameter</th>
            <th>Type</th>
            <th>Required</th>
            <th>Description</th>
          </tr>
        </thead>
        <tbody>
          <tr>
            <td>page</td>
            <td>number</td>
            <td>no</td>
            <td>Page number (default: 1)</td>
          </tr>
          <tr>
            <td>limit</td>
            <td>number</td>
            <td>no</td>
            <td>Items per page (default: 20)</td>
          </tr>
          <tr>
            <td>sort</td>
            <td>string</td>
            <td>no</td>
            <td>Sort field</td>
          </tr>
        </tbody>
      </table>
    </div>
    <div class="rf-codeblock">
      <pre data-language="json">
        <code data-language="json">{
  &quot;users&quot;: [
    { &quot;id&quot;: 1, &quot;name&quot;: &quot;Alice&quot;, &quot;email&quot;: &quot;[email protected]&quot; }
  ],
  &quot;total&quot;: 42,
  &quot;page&quot;: 1
}
</code>
      </pre>
    </div>
    <blockquote>
      <p>Rate limited to 100 requests per minute per API key.</p>
    </blockquote>
  </div>
</article>
GET/api/usersBearer token

List Users

Returns a paginated list of users. Requires authentication.

ParameterTypeRequiredDescription
pagenumbernoPage number (default: 1)
limitnumbernoItems per page (default: 20)
sortstringnoSort field
{
  "users": [
    { "id": 1, "name": "Alice", "email": "[email protected]" }
  ],
  "total": 42,
  "page": 1
}

Rate limited to 100 requests per minute per API key.

<article class="rf-api rf-api--GET rf-api--/api/users rf-api--Bearer token" data-method="GET" data-path="/api/users" data-auth="Bearer token" data-rune="api" data-density="full">
  <div data-name="header" class="rf-api__header" data-section="header">
    <span data-name="method" data-meta-type="category" data-meta-rank="primary" data-meta-sentiment="positive" class="rf-api__method">GET</span>
    <code data-name="path" class="rf-api__path">/api/users</code>
    <span data-name="auth" data-meta-type="status" data-meta-rank="secondary" class="rf-api__auth">Bearer token</span>
  </div>
  <div data-name="body" class="rf-api__body" data-section="body">
    <meta content="GET" data-field="method" />
    <meta content="/api/users" data-field="path" />
    <meta content="Bearer token" data-field="auth" />
    <div data-name="body" class="rf-api__body" data-section="body">
      <h2 id="list-users">List Users</h2>
      <p>Returns a paginated list of users. Requires authentication.</p>
      <div class="rf-table-wrapper">
        <table>
          <thead>
            <tr>
              <th>Parameter</th>
              <th>Type</th>
              <th>Required</th>
              <th>Description</th>
            </tr>
          </thead>
          <tbody>
            <tr>
              <td>page</td>
              <td>number</td>
              <td>no</td>
              <td>Page number (default: 1)</td>
            </tr>
            <tr>
              <td>limit</td>
              <td>number</td>
              <td>no</td>
              <td>Items per page (default: 20)</td>
            </tr>
            <tr>
              <td>sort</td>
              <td>string</td>
              <td>no</td>
              <td>Sort field</td>
            </tr>
          </tbody>
        </table>
      </div>
      <div class="rf-codeblock">
        <pre data-language="json"><code data-language="json">{
  &quot;users&quot;: [
    { &quot;id&quot;: 1, &quot;name&quot;: &quot;Alice&quot;, &quot;email&quot;: &quot;[email protected]&quot; }
  ],
  &quot;total&quot;: 42,
  &quot;page&quot;: 1
}
</code></pre>
      </div>
      <blockquote>
        <p>Rate limited to 100 requests per minute per API key.</p>
      </blockquote>
    </div>
  </div>
</article>

POST endpoint

A POST endpoint with a request body and response example.

{% api method="POST" path="/api/users" auth="Bearer token" %}
## Create User

Creates a new user account.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| name | string | yes | User's full name |
| email | string | yes | Email address |
| role | string | no | User role (default: "member") |

```json
{
  "id": 2,
  "name": "Bob",
  "email": "[email protected]",
  "role": "member"
}
```
{% /api %}
<article data-rune="api">
  <meta content="POST" data-field="method">
  <meta content="/api/users" data-field="path">
  <meta content="Bearer token" data-field="auth">
  <div data-name="body">
    <h2 id="create-user">Create User</h2>
    <p>Creates a new user account.</p>
    <div class="rf-table-wrapper">
      <table>
        <thead>
          <tr>
            <th>Parameter</th>
            <th>Type</th>
            <th>Required</th>
            <th>Description</th>
          </tr>
        </thead>
        <tbody>
          <tr>
            <td>name</td>
            <td>string</td>
            <td>yes</td>
            <td>User's full name</td>
          </tr>
          <tr>
            <td>email</td>
            <td>string</td>
            <td>yes</td>
            <td>Email address</td>
          </tr>
          <tr>
            <td>role</td>
            <td>string</td>
            <td>no</td>
            <td>User role (default: &quot;member&quot;)</td>
          </tr>
        </tbody>
      </table>
    </div>
    <div class="rf-codeblock">
      <pre data-language="json">
        <code data-language="json">{
  &quot;id&quot;: 2,
  &quot;name&quot;: &quot;Bob&quot;,
  &quot;email&quot;: &quot;[email protected]&quot;,
  &quot;role&quot;: &quot;member&quot;
}
</code>
      </pre>
    </div>
  </div>
</article>
POST/api/usersBearer token

Create User

Creates a new user account.

ParameterTypeRequiredDescription
namestringyesUser's full name
emailstringyesEmail address
rolestringnoUser role (default: "member")
{
  "id": 2,
  "name": "Bob",
  "email": "[email protected]",
  "role": "member"
}

<article class="rf-api rf-api--POST rf-api--/api/users rf-api--Bearer token" data-method="POST" data-path="/api/users" data-auth="Bearer token" data-rune="api" data-density="full">
  <div data-name="header" class="rf-api__header" data-section="header">
    <span data-name="method" data-meta-type="category" data-meta-rank="primary" data-meta-sentiment="neutral" class="rf-api__method">POST</span>
    <code data-name="path" class="rf-api__path">/api/users</code>
    <span data-name="auth" data-meta-type="status" data-meta-rank="secondary" class="rf-api__auth">Bearer token</span>
  </div>
  <div data-name="body" class="rf-api__body" data-section="body">
    <meta content="POST" data-field="method" />
    <meta content="/api/users" data-field="path" />
    <meta content="Bearer token" data-field="auth" />
    <div data-name="body" class="rf-api__body" data-section="body">
      <h2 id="create-user">Create User</h2>
      <p>Creates a new user account.</p>
      <div class="rf-table-wrapper">
        <table>
          <thead>
            <tr>
              <th>Parameter</th>
              <th>Type</th>
              <th>Required</th>
              <th>Description</th>
            </tr>
          </thead>
          <tbody>
            <tr>
              <td>name</td>
              <td>string</td>
              <td>yes</td>
              <td>User's full name</td>
            </tr>
            <tr>
              <td>email</td>
              <td>string</td>
              <td>yes</td>
              <td>Email address</td>
            </tr>
            <tr>
              <td>role</td>
              <td>string</td>
              <td>no</td>
              <td>User role (default: &quot;member&quot;)</td>
            </tr>
          </tbody>
        </table>
      </div>
      <div class="rf-codeblock">
        <pre data-language="json"><code data-language="json">{
  &quot;id&quot;: 2,
  &quot;name&quot;: &quot;Bob&quot;,
  &quot;email&quot;: &quot;[email protected]&quot;,
  &quot;role&quot;: &quot;member&quot;
}
</code></pre>
      </div>
    </div>
  </div>
</article>

Attributes

AttributeTypeDefaultDescription
methodstringGETHTTP method: GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS
pathstring—Endpoint path (required)
authstring—Authentication requirement

Common attributes

All block runes share these attributes for layout and theming.

AttributeTypeDefaultDescription
widthstringcontentPage grid width: content, wide, or full
spacingstring—Vertical spacing: flush, tight, default, loose, or breathe
insetstring—Horizontal padding: flush, tight, default, loose, or breathe
tintstring—Named colour tint from theme configuration
tint-modestringautoColour scheme override: auto, dark, or light
bgstring—Named background preset from theme configuration