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

Parameter	Type	Required	Description
`project`	string (UUID)	Yes	Your InstantSchema project ID
`pathname`	string	Yes	The 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"}.

Status	Condition
`400 Bad Request`	`project` or `pathname` parameter is missing
`402 Payment Required`	Monthly scan budget exhausted
`404 Not Found`	Project UUID not found, or page not found and on-demand monitoring is disabled
`429 Too Many Requests`	On-demand rate limit reached (50 scans/org/hour)
`500 Internal Server Error`	Unexpected 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

Getting Started

Integrations

API Reference

Troubleshooting

GET /api/v1/structured-data

GET /api/v1/structured-data

Endpoint

Parameters

Request

Response

Error responses

402 — budget exhausted

429 — rate limit

Caching

CORS

On-demand monitoring

​GET /api/v1/structured-data

​Endpoint

​Parameters

​Request

​Response

​Error responses

​402 — budget exhausted

​429 — rate limit

​Caching

​CORS

​On-demand monitoring

GET /api/v1/structured-data

Endpoint

Parameters

Request

Response

Error responses

402 — budget exhausted

429 — rate limit

Caching

CORS

On-demand monitoring