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

# SchemaGen API overview: base URL, errors, and rate limits

> A reference overview of the SchemaGen API — base URL, available endpoints, error response format, rate limiting rules, and common HTTP status codes.

The SchemaGen API is a set of HTTP endpoints that power schema delivery, generation, and validation. You can call these endpoints directly to build custom integrations, server-side pipelines, or CMS plugins without relying on the SchemaGen JavaScript SDK.

## Base URL

All API requests use the following base URL:

```
https://schemagen.io
```

## Available endpoints

| Method | Path                     | Description                                                        | Auth required                         |
| ------ | ------------------------ | ------------------------------------------------------------------ | ------------------------------------- |
| `GET`  | `/api/inject`            | Fetch published schemas for a page as JSON                         | No                                    |
| `GET`  | `/api/embed`             | Fetch published schemas for a page as rendered HTML                | No                                    |
| `POST` | `/api/generate`          | Generate JSON-LD from a schema type and field data                 | No (higher limits when authenticated) |
| `POST` | `/api/validate`          | Validate existing JSON-LD against Schema.org and Google guidelines | No                                    |
| `POST` | `/api/generate-from-url` | Extract and generate JSON-LD from a live URL using AI              | Yes (Pro or Agency plan)              |

## Error format

All error responses return JSON with an `error` field and an optional `details` object.

```json theme={null}
{
  "error": "string describing the error",
  "details": {}
}
```

The `details` field appears on validation errors and contains a structured breakdown of what failed. It is omitted on rate limit, auth, and server errors.

## HTTP status codes

| Code  | Meaning                                                                                         |
| ----- | ----------------------------------------------------------------------------------------------- |
| `200` | Request succeeded.                                                                              |
| `400` | The request body or query parameters failed validation. Check the `details` field.              |
| `403` | Access denied. Either your plan limit has been reached or the requested resource is restricted. |
| `429` | Too many requests. You have exceeded the rate limit for this endpoint. Wait before retrying.    |
| `500` | An unexpected server error occurred.                                                            |
| `503` | A downstream service (such as the AI extraction engine) is temporarily unavailable.             |

## Rate limiting

SchemaGen applies rate limits at the endpoint level to ensure fair use.

* **Authenticated users** are rate-limited per user account and receive higher request allowances.
* **Unauthenticated users** are rate-limited per IP address and have lower allowances.

When you exceed the rate limit, the API returns a `429` response:

```json theme={null}
{
  "error": "Too many requests. Please wait a moment."
}
```

The `/api/validate` endpoint has its own independent rate limit separate from the generation endpoints.

<Note>
  Rate limits are applied on a fail-open basis: if the rate limit service is temporarily unavailable, requests are allowed through rather than blocked.
</Note>

## Usage limits

Authenticated users on paid plans have a monthly usage quota that applies to schema generation and AI extraction. When you reach your plan's limit, the API returns a `403` with error code `limit_reached`:

```json theme={null}
{
  "error": "limit_reached"
}
```

Guest (unauthenticated) users can call `/api/generate` without a usage limit, but are subject to IP-based rate limits.