GET /api/embed — Fetch Schemas as Renderable HTML

The embed endpoint delivers published schemas as a ready-to-render HTML string instead of JSON. The response contains one or more <script type="application/ld+json"> tags that you can insert directly into the <head> or <body> of any HTML page. This makes it the right choice for server-side rendering environments where you cannot run JavaScript to inject schemas at runtime.

This endpoint requires no authentication. It is a public CORS-enabled endpoint safe to call from any server environment.

When to use embed vs. inject

Use /api/embed when you are rendering pages on the server and want schemas included in the initial HTML response — for example, in a PHP template, a WordPress theme, a Shopify Liquid file, or an AMP page. Use /api/inject (or the SchemaGen JavaScript SDK) when you are rendering pages in the browser and can inject schemas dynamically after the page loads.

Scenario	Recommended endpoint
PHP or server-side templates	`/api/embed`
WordPress theme or plugin	`/api/embed`
Shopify Liquid templates	`/api/embed`
AMP pages	`/api/embed`
JavaScript SPAs or static sites with JS SDK	`/api/inject`

Endpoint

GET https://schemagen.io/api/embed

Query parameters

string

required

The UUID of your client site. You can find your Client ID in Settings → Client in the SchemaGen dashboard.

string

required

The absolute URL of the page you want to fetch schemas for. Must include the protocol (e.g., https://example.com/products/widget).

Response

A successful request returns 200 with a Content-Type of text/html; charset=utf-8. The body is an HTML string containing one <script type="application/ld+json"> tag per published schema. If no schemas are published for the given URL, the body is an empty string.

Example response body

<script type="application/ld+json">{"@context":"https://schema.org","@type":"Product","name":"Widget Pro","description":"A high-quality widget","offers":{"@type":"Offer","price":"49.99","priceCurrency":"USD"}}</script>

If multiple schemas are published for the URL, they are concatenated with no separator:

<script type="application/ld+json">{"@context":"https://schema.org","@type":"Product","name":"Widget Pro"}</script><script type="application/ld+json">{"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[]}</script>

Response headers

Header	Description
`X-Schemagen-Duration`	Server-side processing time in milliseconds.
`X-Schemagen-ID`	A unique UUID identifying this request.
`Content-Type`	Always `text/html; charset=utf-8`.
`Cache-Control`	Responses are cached. Unlike `/api/inject`, embed responses may be served from cache to improve server rendering performance.

Code examples

curl -G "https://schemagen.io/api/embed" \
  --data-urlencode "clientId=your-client-uuid" \
  --data-urlencode "url=https://example.com/products/widget"

const params = new URLSearchParams({
  clientId: 'your-client-uuid',
  url: 'https://example.com/products/widget',
});

const response = await fetch(`https://schemagen.io/api/embed?${params}`);
const html = await response.text();

// `html` is ready to insert into your server-rendered page

<?php
$clientId = 'your-client-uuid';
$url = 'https://example.com/products/widget';

$apiUrl = 'https://schemagen.io/api/embed?' . http_build_query([
    'clientId' => $clientId,
    'url'      => $url,
]);

$schemas = file_get_contents($apiUrl);

// Output directly in your template <head>
echo $schemas;

WordPress usage

Call the embed API in your theme’s functions.php and output the result in the <head> using the wp_head action:

add_action('wp_head', function () {
    $clientId = 'your-client-uuid';
    $url      = get_permalink() ?: home_url($_SERVER['REQUEST_URI']);

    $apiUrl = add_query_arg(
        ['clientId' => $clientId, 'url' => rawurlencode($url)],
        'https://schemagen.io/api/embed'
    );

    $response = wp_remote_get($apiUrl);

    if (!is_wp_error($response)) {
        echo wp_remote_retrieve_body($response);
    }
});

Error responses

When the request is invalid or an error occurs, the embed endpoint returns an empty body with the appropriate HTTP status code. It does not return a JSON error body.

Status	Cause
`400`	`clientId` or `url` is missing or invalid.
`500`	An unexpected server error occurred.

All error responses still include the X-Schemagen-ID header so you can trace the request.

Because the embed endpoint returns an empty string when no schemas match the URL (rather than an error), you can safely output its response in every page template without a null check. Pages with no published schemas will simply have no extra output.

Overview

Endpoints

GET /api/embed — Fetch Schemas as Renderable HTML

When to use embed vs. inject

Endpoint

Query parameters

Response

Example response body

Response headers

Code examples

WordPress usage

Error responses

​When to use embed vs. inject

​Endpoint

​Query parameters

​Response

​Example response body

​Response headers

​Code examples

​WordPress usage

​Error responses

When to use embed vs. inject

Endpoint

Query parameters

Response

Example response body

Response headers

Code examples

WordPress usage

Error responses