> ## Documentation Index
> Fetch the complete documentation index at: https://docs.schemagen.io/llms.txt
> Use this file to discover all available pages before exploring further.

# CMS Embed API: Server-Side JSON-LD Schema Delivery

> Deliver JSON-LD schemas server-side using SchemaGen's Embed API—ideal for WordPress, Shopify Liquid, PHP templates, and performance-critical sites.

The SchemaGen Embed API is an alternative schema delivery method for environments where the JavaScript SDK is not suitable. Instead of loading a client-side script, your CMS template or server fetches a URL from SchemaGen at request time and injects the returned HTML — a `<script type="application/ld+json">` tag containing your deployed schema — directly into the page `<head>` before it reaches the browser.

This approach avoids any JavaScript dependency for schema delivery, which benefits server-rendered CMS platforms, AMP pages, and sites where minimizing JavaScript execution is a priority for Core Web Vitals.

## JS SDK vs Embed API

Use this table to decide which delivery method fits your setup:

|                     | JS SDK                                  | Embed API                                   |
| ------------------- | --------------------------------------- | ------------------------------------------- |
| **Setup**           | Add one `<script>` tag to `<head>`      | Fetch a URL from your template or server    |
| **Rendering**       | Client-side, after page load            | Server-side, in the initial HTML response   |
| **Best for**        | SPAs, headless frontends, any HTML site | WordPress, Shopify, PHP, AMP                |
| **Core Web Vitals** | No impact on LCP/CLS, async loaded      | Schema in initial HTML, zero JS overhead    |
| **Caching**         | CDN-cached SDK                          | Response cached with standard cache headers |

<Note>
  The Embed API response is cached by SchemaGen's edge infrastructure using standard HTTP cache headers. Fetching it server-side on every page request is fast and will not add meaningful latency to your page load times.
</Note>

## The embed endpoint

```
GET https://schemagen.io/api/embed?clientId={clientId}&url={pageUrl}
```

**Parameters:**

| Parameter  | Required | Description                                                             |
| ---------- | -------- | ----------------------------------------------------------------------- |
| `clientId` | Yes      | Your SchemaGen client ID, found in **Dashboard → Settings → Client ID** |
| `url`      | Yes      | The absolute URL of the page being rendered, URL-encoded                |

**Response:** Plain HTML containing one or more `<script type="application/ld+json">` tags for every schema you have published for that URL. If no schemas are deployed for that URL, the response is empty — your page renders normally with no errors.

## Code examples

<Tabs>
  <Tab title="WordPress PHP">
    Add this snippet to your theme's `functions.php` or directly in the `<head>` section of `header.php`. It uses WordPress's built-in HTTP API to fetch the schema and echoes the result into the page head.

    ```php header.php theme={null}
    <?php
    $client_id = 'YOUR_CLIENT_ID';
    $page_url = 'https://' . $_SERVER['HTTP_HOST'] . $_SERVER['REQUEST_URI'];
    $embed_url = 'https://schemagen.io/api/embed?clientId=' . urlencode($client_id) . '&url=' . urlencode($page_url);
    $response = wp_remote_get($embed_url);
    if (!is_wp_error($response)) {
        echo wp_remote_retrieve_body($response);
    }
    ?>
    ```

    Place this call inside `<head>...</head>` so the structured data is included in the initial HTML document.
  </Tab>

  <Tab title="Shopify Liquid">
    Add this snippet to your `theme.liquid` layout file inside the `<head>` block. Shopify Liquid's `fetch` filter makes the server-side request during render.

    ```liquid theme.liquid theme={null}
    {% assign schema_url = 'https://schemagen.io/api/embed?clientId=YOUR_CLIENT_ID&url=' | append: canonical_url %}
    {% assign schema_html = schema_url | fetch %}
    {{ schema_html }}
    ```

    Replace `YOUR_CLIENT_ID` with your actual client ID. The `canonical_url` variable is set automatically by Shopify for each page.
  </Tab>

  <Tab title="Generic PHP">
    For any PHP-based CMS or custom server, use `file_get_contents` or a cURL request:

    ```php theme={null}
    <?php
    $client_id = 'YOUR_CLIENT_ID';
    $page_url = (isset($_SERVER['HTTPS']) ? 'https' : 'http') . '://' . $_SERVER['HTTP_HOST'] . $_SERVER['REQUEST_URI'];
    $embed_url = 'https://schemagen.io/api/embed?clientId=' . rawurlencode($client_id) . '&url=' . rawurlencode($page_url);
    $schema_html = @file_get_contents($embed_url);
    if ($schema_html !== false) {
        echo $schema_html;
    }
    ?>
    ```
  </Tab>

  <Tab title="JavaScript fetch">
    If your environment renders server-side JavaScript (Next.js, Nuxt, SvelteKit) or you need a client-side fallback, use the fetch approach:

    ```javascript theme={null}
    fetch(
      'https://schemagen.io/api/embed?clientId=YOUR_CLIENT_ID&url=' +
      encodeURIComponent(window.location.href)
    )
      .then(r => r.text())
      .then(html => {
        const div = document.createElement('div');
        div.innerHTML = html;
        document.head.appendChild(div.firstChild);
      });
    ```

    <Warning>
      Fetching via client-side JavaScript defeats the server-rendering advantage of the Embed API. Use this approach only as a fallback. For true server-side delivery, use the PHP or Liquid examples above.
    </Warning>
  </Tab>
</Tabs>

## How to find your client ID

Your client ID is a UUID assigned to your SchemaGen account. Find it in **Dashboard → Settings → Client ID**. It is the same identifier used in the JS SDK's `data-client-id` attribute:

```html theme={null}
<script async
  src="https://schemagen.io/sdk.js"
  data-client-id="YOUR_CLIENT_ID">
</script>
```

Both the SDK and the Embed API use the same client ID — if you are migrating from one delivery method to the other, no changes are needed to your schema configurations in the dashboard.

## How schema matching works

When the Embed API receives a request, it looks up all schemas you have published for the exact URL provided in the `url` parameter. Make sure the URL you pass matches the canonical URL of the page as you have configured it in the SchemaGen dashboard. Including or excluding trailing slashes, query strings, or `www` inconsistently will result in no schemas being returned.

<Tip>
  Always pass the canonical URL of the page — the same URL you used when deploying the schema in the dashboard. For WordPress, this is `get_permalink()`. For Shopify, use the `canonical_url` variable as shown in the Liquid example.
</Tip>
