Documentation

Schema Forge API

A small JSON API that analyses a public URL, lists the structured data it has, and returns ready-to-paste JSON-LD or a link to the generator.

Start here

Short answer

Call GET /api/check?url=… to learn which schema types a page is missing and get a link that opens the generator for that page. Call GET /api/analyze?url=… for the full markup.

Request

curl "/api/check?url=https://example.com/help"

Request

const res = await fetch('/api/check?url=' + encodeURIComponent(pageUrl));
const { missing, forgeUrl } = await res.json();

Response (200)

{
  "url": "https://example.com/help",
  "hasSchema": false,
  "existing": [],
  "missing": [
    "FAQPage"
  ],
  "forgeUrl": "https://schemaforge.example/generator?url=https%3A%2F%2Fexample.com%2Fhelp"
}

Endpoints

GET/api/check?url=

Compact: url, hasSchema, existing (types found), missing (types Schema Forge could generate) and forgeUrl.

GET/api/analyze?url=

Everything above plus, for each of the nine types: confidence, present, jsonld, a ready-to-paste snippet, warnings and gaps. Also validation for markup already on the page, score (a 0 to 100 health score with its reasons), jsApp (true when the page looks built by JavaScript) and combined, one block holding every ready type. Each type also carries an eligibility note. Add &render=1 on hosts with JavaScript rendering enabled.

GET/api/scan?url=&limit=

Reads the sitemap at url (or /sitemap.xml on a site address) and streams newline-delimited JSON: a start row, one page row for each page on the same host, then a done row with a summary. Up to 10 pages.

POST/api/analyze

The same analysis for HTML you send, for pages that cannot be fetched (behind a login, or built by JavaScript). Send JSON: {"html": "…", "url": "https://example.com/page"}. Up to 2 MB. The address is only used to resolve relative links.

GET/api/badge?url=

An SVG badge showing the page’s schema health score, for embedding as an image. It is cached for an hour, and draws a grey badge if the page cannot be read.

GET/api/llms?url=&limit=

Builds an llms.txt file for a site from its sitemap (or the links on its home page) and returns { text, name, pages, partial, source }.

GET/api/config

What this host supports: render, paste, scan, scanMax and push.

Linking from another tool

An audit or link-building tool can call /api/check and, when missing is not empty, show the forgeUrl value as a "generate schema" link. Opening /generator?url=… runs the analysis straight away.

Use of the API is subject to the terms of use. The /api/push/* endpoints serve the alerts feature, accept only same-origin requests from this site, and are not part of the public API.

Errors

Status	Meaning
400	The URL is missing, invalid, not http or https, or points to a private address.
413 / 415	The page is over 2 MB, or is not HTML.
422	A scan found no pages on the same host in the sitemap.
429	More than 30 requests, or 3 scans, in a minute from the same IP address.
501 / 503	Rendering is not enabled on this host, or the renderer or scanner is busy.
502 / 504	The target site returned an error or took too long to respond.

Error responses are JSON in the form {"error": "message"}.

Questions

Do I need an API key?

No. The API needs no key, and CORS is enabled so it can be called from a browser or a server.

What are the limits?

Each IP address can make 30 requests and 3 scans a minute. Pages must be public, under 2 MB, and respond within a few seconds. A scan covers up to 10 pages on one host.