API Documentation

Programmatic access to AI-Schema

Getting Started

The AI-Schema API allows you to programmatically manage your projects, pages, and schemas for Search Engines and AI Answer Engines. All API endpoints require authentication using an API key.

Authentication

All API requests must include your API key in the Authorization header using the Bearer scheme:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://schemagenai.com/api/v2/projects

Security Note: Keep your API keys secret. Never commit them to version control or expose them in client-side code.

Base URL

https://schemagenai.com/api/v2

API Endpoints

Complete REST API reference - All endpoints use API key authentication

Pages

GET/pages

List all pages for the workspace (automatically determined from API key)

Query params: page, limit, activeOnly

POST/pages

Create a new page manually.

{
  "urlPath": "/new-page"
}

PATCH/pages

Toggle page selection for schema generation

{
  "urlPath": "/about",
  "isSelectedForSchema": true
}

Schemas

GET/schema?urlPath=/about

Get latest schema for a page by URL path. Requests are tracked in CDN analytics.

POST/schema/process

All-in-one endpoint: Creates page if needed, crawls if no HTML content, generates/regenerates schema, and activates the page for serving. Pages with custom schemas are protected by default.

{
  "urlPath": "/about",
  "forceRegenerate": false // Set true to override custom schemas
}

Analytics

GET/analytics

Get CDN analytics data including total requests, top paths, and weekly data

Jobs

POST/jobs/stop

Stop all pending and processing jobs (crawl and schema generation) for the workspace. Returns the count and details of stopped jobs. Useful when you need to cancel long-running operations or when jobs appear to be stuck.

Response: stoppedCount, jobs[] (id, type, previousStatus)

Response Format

All API responses follow this format:

Success Response:

{
  "success": true,
  "data": { ... }
}

Error Response:

{
  "error": "Error message here"
}

Rate Limiting

API requests are subject to rate limiting based on your plan. Contact support for current rate limits.

Rate limit information is included in response headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640000000

Example Requests

Complete examples using cURL

# List all pages for the workspace (determined by API key)
curl -X GET https://schemagenai.com/api/v2/pages \
  -H "Authorization: Bearer YOUR_API_KEY"

# List only active pages (with schema enabled)
curl -X GET "https://schemagenai.com/api/v2/pages?activeOnly=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Create a new page manually
curl -X POST https://schemagenai.com/api/v2/pages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "urlPath": "/new-page"
  }'

# Toggle page selection for schema (cache is auto-invalidated)
curl -X PATCH https://schemagenai.com/api/v2/pages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "urlPath": "/about",
    "isSelectedForSchema": true
  }'

# Get schema for a page by URL path
curl -X GET "https://schemagenai.com/api/v2/schema?urlPath=/about" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Process schema (all-in-one: create page + crawl + generate + activate)
# Pages with custom schemas are protected - use forceRegenerate to override
curl -X POST https://schemagenai.com/api/v2/schema/process \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "urlPath": "/about",
    "forceRegenerate": false
  }'

# Get CDN analytics
curl -X GET https://schemagenai.com/api/v2/analytics \
  -H "Authorization: Bearer YOUR_API_KEY"

# Stop all pending and processing jobs
curl -X POST https://schemagenai.com/api/v2/jobs/stop \
  -H "Authorization: Bearer YOUR_API_KEY"

Best Practices

Store API keys securely in environment variables
Implement exponential backoff for rate limit errors (429)
Use urlPath parameter to identify pages (not internal IDs)
Rotate API keys regularly for security
Project context is automatically determined from your API key

HTTP Status Codes

200Success

400Bad Request - Invalid parameters or URL validation failed (page doesn't exist, bot protection detected, etc.)

401Unauthorized - Invalid or missing API key

403Forbidden - API access not available in plan

404Not Found - Resource doesn't exist

429Too Many Requests - Rate limit exceeded or token limit exceeded

500Internal Server Error