> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/kapishdima/fonttrio/llms.txt
> Use this file to discover all available pages before exploring further.

# API Endpoints

> Complete reference for all Fonttrio Registry API endpoints

## GET /api/r/\[name]

Retrieve a font pairing or individual font configuration from the registry.

### Path Parameters

<ParamField path="name" type="string" required>
  The registry item name. Can be a pairing name (e.g., `minimal`, `brutalist`) or font name (e.g., `inter`, `roboto`).

  The `.json` extension is optional and will be automatically stripped if provided.
</ParamField>

### Resolution Logic

The API searches for registry items in the following order:

1. **Pairings directory** with exact name: `/registry/pairings/{name}.json`
2. **Pairings directory** without `pairing-` prefix: `/registry/pairings/{name-without-prefix}.json`
3. **Fonts directory**: `/registry/fonts/{name}.json`

This allows flexible naming:

* `/api/r/minimal` → finds `pairings/minimal.json`
* `/api/r/pairing-minimal` → finds `pairings/minimal.json`
* `/api/r/inter` → finds `fonts/inter.json`

### Query Parameters

Override CSS properties for specific HTML elements in font pairings. Query parameters are ignored for individual font requests.

#### Parameter Format

Parameters follow the pattern: `{selector}-{property}={value}`

**Supported Selectors:**

* `h1`, `h2`, `h3`, `h4`, `h5`, `h6` — Heading levels
* `body` — Body text
* `code` — Inline code
* `pre` — Code blocks

**Supported Properties:**

<ParamField query="{selector}-size" type="string">
  Font size (e.g., `2rem`, `18px`, `1.5em`)
</ParamField>

<ParamField query="{selector}-weight" type="string">
  Font weight (e.g., `400`, `700`, `bold`)
</ParamField>

<ParamField query="{selector}-family" type="string">
  Font family (e.g., `Inter`, `var(--font-custom)`)
</ParamField>

<ParamField query="{selector}-lh" type="string">
  Line height (e.g., `1.6`, `1.8`, `2`)

  Aliases: `line-height`
</ParamField>

<ParamField query="{selector}-ls" type="string">
  Letter spacing (e.g., `-0.02em`, `0.05em`)

  Aliases: `letter-spacing`
</ParamField>

#### Example Query Parameters

```
?h1-size=3rem&h1-weight=800&body-lh=1.8
```

This will:

* Set H1 font size to `3rem`
* Set H1 font weight to `800`
* Set body line height to `1.8`

### Response

<ResponseField name="Success" type="object">
  Returns either a [pairing schema](/api/pairing-schema) or [font schema](/api/font-schema) depending on the requested item.
</ResponseField>

<ResponseField name="Error" type="object">
  <ResponseField name="error" type="string">
    Error message describing why the request failed
  </ResponseField>
</ResponseField>

### Cache Headers

#### Without Query Parameters

```http theme={null}
Cache-Control: public, max-age=86400, s-maxage=86400
```

Responses are cached for 24 hours (86400 seconds) by browsers and CDNs.

#### With Query Parameters

```http theme={null}
Cache-Control: no-cache
```

Dynamic responses with overrides are not cached to ensure customizations are always applied.

## Examples

### Fetch Default Pairing

<CodeGroup>
  ```bash cURL theme={null}
  curl https://www.fonttrio.xyz/api/r/minimal
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://www.fonttrio.xyz/api/r/minimal');
  const pairing = await response.json();

  console.log(pairing.title); // "Minimal — Geist + Geist + Geist Mono"
  console.log(pairing.css.h1['font-size']); // "2.25rem"
  ```

  ```python Python theme={null}
  import requests

  response = requests.get('https://www.fonttrio.xyz/api/r/minimal')
  pairing = response.json()

  print(pairing['title'])  # "Minimal — Geist + Geist + Geist Mono"
  ```

  ```typescript TypeScript theme={null}
  interface Pairing {
    name: string;
    title: string;
    css: Record<string, Record<string, string>>;
  }

  const response = await fetch('https://www.fonttrio.xyz/api/r/minimal');
  const pairing: Pairing = await response.json();
  ```
</CodeGroup>

### Fetch with Overrides

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://www.fonttrio.xyz/api/r/brutalist?h1-size=3.5rem&body-lh=1.7"
  ```

  ```javascript JavaScript theme={null}
  const params = new URLSearchParams({
    'h1-size': '3.5rem',
    'h1-weight': '900',
    'body-lh': '1.7',
    'body-ls': '0.01em'
  });

  const response = await fetch(
    `https://www.fonttrio.xyz/api/r/brutalist?${params}`
  );
  const pairing = await response.json();

  // CSS properties are now overridden
  console.log(pairing.css.h1['font-size']); // "3.5rem"
  console.log(pairing.css.h1['font-weight']); // "900"
  ```

  ```typescript TypeScript theme={null}
  interface TypographyOverrides {
    'h1-size'?: string;
    'h1-weight'?: string;
    'body-lh'?: string;
    'body-ls'?: string;
  }

  function buildPairingUrl(
    name: string,
    overrides?: TypographyOverrides
  ): string {
    const base = `https://www.fonttrio.xyz/api/r/${name}`;
    
    if (!overrides) return base;
    
    const params = new URLSearchParams(
      Object.entries(overrides).filter(([_, v]) => v !== undefined) as [string, string][]
    );
    
    return `${base}?${params}`;
  }

  const url = buildPairingUrl('brutalist', {
    'h1-size': '3.5rem',
    'body-lh': '1.7'
  });
  ```
</CodeGroup>

### Fetch Individual Font

<CodeGroup>
  ```bash cURL theme={null}
  curl https://www.fonttrio.xyz/api/r/inter
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://www.fonttrio.xyz/api/r/inter');
  const font = await response.json();

  console.log(font.font.family); // "Inter"
  console.log(font.font.provider); // "google"
  console.log(font.font.weight); // ["100", "200", ...]
  ```

  ```typescript TypeScript theme={null}
  interface FontConfig {
    name: string;
    type: 'registry:font';
    font: {
      family: string;
      provider: string;
      import: string;
      variable: string;
      weight: string[];
      subsets: string[];
    };
  }

  const response = await fetch('https://www.fonttrio.xyz/api/r/roboto');
  const font: FontConfig = await response.json();
  ```
</CodeGroup>

### Error Handling

<CodeGroup>
  ```javascript JavaScript theme={null}
  try {
    const response = await fetch('https://www.fonttrio.xyz/api/r/nonexistent');
    
    if (!response.ok) {
      const error = await response.json();
      console.error(error.error);
      // "Registry item \"nonexistent\" not found"
      return;
    }
    
    const data = await response.json();
    // Process data...
  } catch (err) {
    console.error('Network error:', err);
  }
  ```

  ```typescript TypeScript theme={null}
  interface ApiError {
    error: string;
  }

  async function fetchPairing(name: string) {
    const response = await fetch(
      `https://www.fonttrio.xyz/api/r/${name}`
    );
    
    if (!response.ok) {
      const error: ApiError = await response.json();
      throw new Error(error.error);
    }
    
    return response.json();
  }

  try {
    const pairing = await fetchPairing('minimal');
  } catch (error) {
    if (error instanceof Error) {
      console.error('Failed to fetch pairing:', error.message);
    }
  }
  ```
</CodeGroup>

## Implementation Details

The endpoint is implemented in Next.js as a dynamic route handler:

**Source**: `app/api/r/[name]/route.ts:8`

Key behaviors:

* Strips `.json` extension if provided in the URL
* Searches pairings directory first, then fonts directory
* Handles `pairing-` prefix automatically
* Applies CSS overrides from query parameters only to matching selectors
* Returns 404 if no matching registry item is found

## See Also

<CardGroup cols={2}>
  <Card title="Pairing Schema" icon="layer-group" href="/api/pairing-schema">
    Detailed schema for font pairing responses
  </Card>

  <Card title="Font Schema" icon="font" href="/api/font-schema">
    Schema for individual font configurations
  </Card>
</CardGroup>