Skip to main content

​
GET /api/v1/structured-data

Returns the JSON-LD schemas for a specific page in your project.

​
Endpoint

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

​
Parameters

ParameterTypeRequiredDescription
projectstring (UUID)YesYour InstantSchema project ID
pathnamestringYesThe page path (e.g. /, /blog/my-post)
Pathname is normalized automatically: leading / is added if missing, trailing / is stripped (except for root /).

​
Request

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

​
Response

200 OK 
{
  "schemas": [
    {
      "@context": "https://schema.org",
      "@type": "Article",
      "headline": "My Post Title",
      "author": { "@type": "Person", "name": "Jane Doe" }
    },
    {
      "@context": "https://schema.org",
      "@type": "BreadcrumbList",
      "itemListElement": []
    }
  ]
}
schemas is an array of JSON-LD objects. It may be empty ([]) if no schemas have been generated for this page yet. Global schemas (e.g. Organization, WebSite) are merged into every non-homepage response automatically.

​
Error responses

All errors return {"error": "description"}.
StatusCondition
400 Bad Requestproject or pathname parameter is missing
402 Payment RequiredMonthly scan budget exhausted
404 Not FoundProject UUID not found, or page not found and on-demand monitoring is disabled
429 Too Many RequestsOn-demand rate limit reached (50 scans/org/hour)
500 Internal Server ErrorUnexpected server error

​
402 — budget exhausted

{
  "error": "Monthly page-scan budget exhausted. Schemas unavailable until next period."
}

​
429 — rate limit

{
  "error": "On-demand rate limit reached. Try again later."
}

​
Caching

Cache-Control: public, s-maxage=86400
Cache-Tag: project-{projectId}, page-{projectId}-{pathnameHash}
Responses are cached at the CDN layer for 24 hours. Schemas are purged by tag when you update them in the dashboard.

​
CORS

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, OPTIONS
Access-Control-Allow-Headers: Content-Type
The endpoint is open to cross-origin requests. An OPTIONS preflight returns 204.

​
On-demand monitoring

When On-demand monitoring is enabled for a project and a requested page isn’t in the database yet, the API crawls and enriches that page synchronously before responding.
  • Budget check runs first (402 if exhausted)
  • Rate limit: 50 on-demand scans per org per hour (429 if exceeded)
  • Each on-demand request counts as a billable scan, including requests where the page fetch fails
  • If the page can’t be fetched (network error, 4xx/5xx from origin): returns 404 with a note that the scan attempt was recorded