> ## Documentation Index
> Fetch the complete documentation index at: https://docs.instantschema.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom API

> Call the InstantSchema REST endpoint directly from your server

# 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

| Parameter  | Required | Description                          |
| ---------- | -------- | ------------------------------------ |
| `project`  | Yes      | Your InstantSchema project UUID      |
| `pathname` | Yes      | The page path (e.g. `/blog/my-post`) |

### Example

```bash theme={null}
curl "https://app.instantschema.com/api/v1/structured-data?project=YOUR_PROJECT_ID&pathname=/blog/my-post"
```

### Response

```json theme={null}
{
  "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:

```html theme={null}
<!-- 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

| Status | Meaning                                                   |
| ------ | --------------------------------------------------------- |
| `400`  | Missing `project` or `pathname` parameter                 |
| `402`  | Monthly scan budget exhausted                             |
| `404`  | Project not found, or page not found (on-demand disabled) |
| `429`  | On-demand rate limit reached (50/org/hr)                  |
| `500`  | Internal 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.