Skip to main content

​
Custom API

Call the REST endpoint directly from any server-side language or framework. Schemas are rendered into your HTML source — no JavaScript required on the client.

​
Endpoint

GET https://app.instantschema.com/api/v1/structured-data

​
Parameters

ParameterRequiredDescription
projectYesYour InstantSchema project UUID
pathnameYesThe page path (e.g. /blog/my-post)

​
Example

curl "https://app.instantschema.com/api/v1/structured-data?project=YOUR_PROJECT_ID&pathname=/blog/my-post"

​
Response

{
  "schemas": [
    {
      "@context": "https://schema.org",
      "@type": "Article",
      "headline": "My Post Title",
      ...
    }
  ]
}
schemas is an array of JSON-LD objects. Render each one as a <script type="application/ld+json"> tag.

​
Rendering schemas server-side

Add data-instantschema="1" to each tag so the dashboard can detect the integration automatically: 
<!-- Render one tag per schema object -->
<script type="application/ld+json" data-instantschema="1">
  {"@context":"https://schema.org","@type":"Article",...}
</script>
Without data-instantschema="1" the dashboard cannot distinguish your schemas from other JSON-LD and you’ll need to confirm manually.

​
Caching

The API sets Cache-Control: public, s-maxage=86400 (24 hours). Schemas are also tagged with Cache-Tag: project-{id}, page-{id}-{hash} for targeted CDN purging when you update them.

​
On-demand monitoring

If a page isn’t in InstantSchema yet (e.g. a new blog post), the API can scan and generate schemas on the fly — if On-demand monitoring is enabled for your project. When on-demand monitoring is enabled and a page isn’t found, the API:
  1. Checks your monthly scan budget (returns 402 if exhausted)
  2. Checks the rate limit (50 on-demand scans/org/hour; returns 429 if exceeded)
  3. Crawls the page, generates schemas, and returns them in the same request
Each on-demand request counts as a billable scan.

​
Error codes

StatusMeaning
400Missing project or pathname parameter
402Monthly scan budget exhausted
404Project not found, or page not found (on-demand disabled)
429On-demand rate limit reached (50/org/hr)
500Internal server error
All error responses have the shape {"error": "..."}.

​
CORS

The endpoint allows cross-origin requests from any origin (Access-Control-Allow-Origin: *). The CDN and inline script integrations rely on this.