refrakt.md

Docs

Runes

Themes

Extend

Project

Docs›API
note

This rune is part of @refrakt-md/docs. Install with npm install @refrakt-md/docs and add "@refrakt-md/docs" to the plugins 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" data-rune-fields="{&quot;method&quot;:&quot;GET&quot;,&quot;path&quot;:&quot;/api/users&quot;,&quot;auth&quot;:&quot;Bearer token&quot;}">
  <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-elevation="flat" data-rune="api" data-density="full">
  <div data-name="eyebrow" data-zone="eyebrow" data-zone-layout="bar" data-wrap="false" class="rf-api__eyebrow">
    <span class="rf-badge" data-meta-type="category" data-meta-sentiment="positive">GET</span>
    <span data-meta-type="code">/api/users</span>
    <span class="rf-badge" data-meta-type="status" data-align="end">Bearer token</span>
  </div>
  <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>
</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" data-rune-fields="{&quot;method&quot;:&quot;POST&quot;,&quot;path&quot;:&quot;/api/users&quot;,&quot;auth&quot;:&quot;Bearer token&quot;}">
  <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-elevation="flat" data-rune="api" data-density="full">
  <div data-name="eyebrow" data-zone="eyebrow" data-zone-layout="bar" data-wrap="false" class="rf-api__eyebrow">
    <span class="rf-badge" data-meta-type="category" data-meta-sentiment="neutral">POST</span>
    <span data-meta-type="code">/api/users</span>
    <span class="rf-badge" data-meta-type="status" data-align="end">Bearer token</span>
  </div>
  <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>
</article>

Attributes

AttributeTypeRequiredDescription
method"GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "HEAD" | "OPTIONS"—HTTP method for the endpoint (GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS).
pathstring✓URL path for the API endpoint (e.g. "/users/:id").
authstring—Authentication scheme required for this endpoint (e.g. "Bearer", "API Key").

Universal attributes

bg

The background layer (SPEC-088): image, video, gradient, flat overlay wash and legibility scrim, in a single injected layer behind the rune's content.

AttributeTypeRequiredDescription
bgstring—Background preset applied to this block
bg-fromstring—Gradient start colour — a semantic token name (→ var(--rf-color-*))
bg-gradient"to-t" | "to-b" | "to-l" | "to-r" | "to-tr" | "to-br" | "to-bl" | "to-tl"—Gradient direction (bounded named set)
bg-gradient-type"linear" | "radial" | "conic"—Gradient type
bg-tostring—Gradient end colour — a semantic token name
bg-viastring—Optional middle gradient stop — a semantic token name
scrim"top" | "bottom" | "left" | "right" | "none"—Scrim direction (heaviest edge); presence turns the scrim on, "none" opts out of the default cover scrim
scrim-blur"none" | "sm" | "md" | "lg"—Frost scrim blur amount
scrim-strength"sm" | "md" | "lg"—Gradient scrim strength
scrim-tone"dark" | "light"—Whether the scrim darkens (for light text) or lightens (for dark text)
scrim-type"gradient" | "frost"—Scrim treatment: gradient (default) or frost (backdrop blur)
elevation

The chrome/depth ladder (SPEC-107). The skin maps each rung to a chrome bundle by attribute, so there is no BEM class.

AttributeTypeRequiredDescription
elevation"sunken" | "flush" | "flat" | "raised" | "floating" | "overlay" | "none" | "sm" | "md" | "lg"—Surface depth on the SPEC-107 ladder (sunken→overlay); none/sm/md/lg are deprecated aliases
inset

Internal padding override.

AttributeTypeRequiredDescription
inset"flush" | "tight" | "default" | "loose" | "breathe"—Inner padding of this block
motion

Scroll-reveal entrance (SPEC-105). The author declares the character, the theme owns the choreography, a behaviour owns the timing.

AttributeTypeRequiredDescription
reveal"none" | "fade" | "slide" | "scale" | "blur"—Scroll-reveal entrance character (none|fade|slide|scale|blur); the theme owns the choreography
staggerboolean—Cascade this block's items in as it reveals (no-op on single-child runes)
spacing

Block-level rhythm override.

AttributeTypeRequiredDescription
spacing"flush" | "tight" | "default" | "loose" | "breathe"—Vertical spacing above and below this block
substrate

Generated pattern fills (SPEC-087). Markers only — the engine sets the attributes and cell/opacity custom properties, CSS draws the pattern.

AttributeTypeRequiredDescription
substrate"dots" | "grid" | "lines" | "cross" | "checker" | "none"—Generated surface pattern
substrate-fill"inherit" | "inset"—Surface fill the pattern sits on (full colour stays with tint)
substrate-opacity"sm" | "md" | "lg"—Pattern ink strength
substrate-size"sm" | "md" | "lg"—Pattern cell size
substrate-target"self" | "media"—Which surface the pattern fills (overrides the rune/theme default)
tint

Per-rune colour override (SPEC-053): a named tint from the theme registry, with inline per-token overrides layered on top.

AttributeTypeRequiredDescription
tintstring—Color tint preset applied to this block
tint-mode"auto" | "dark" | "light"—Whether the tint adapts to auto, dark, or light mode
width

The track a block rune occupies.

AttributeTypeRequiredDescription
width"compact" | "narrow" | "content" | "wide" | "full"—Maximum width constraint for this block
Not availableWhy
dropcap, readingthis rune declares no prose body
framethis rune declares neither a `frameTarget` nor a media section
prominencethis rune has no page-section header