Developer Tools

SchemaReports API

Integrate website audits into your existing tools. REST API with full documentation, code examples, and webhook support. Build custom integrations, automate workflows, and embed audits anywhere.

Why Integrate with the SchemaReports API?

Manual audits are useful for one-off analysis. But when you need to incorporate website audits into automated workflows, the API becomes essential. Trigger audits when leads enter your CRM. Build real-time dashboards for client portfolios. Create custom reporting pipelines. The API unlocks use cases that the dashboard alone cannot serve.

Every audit you run through the dashboard can also be triggered via API. You get the same 457 data points, the same AI-powered insights, and the same export formats. The difference is automation. You control when audits run, where results go, and how they integrate with your existing systems.

The API follows REST conventions with JSON responses. If you've worked with any modern API, you'll feel at home. We provide code examples in cURL, Python, and Node.js to get you started quickly.

What You Can Do

🔍

Trigger Audits

POST /v1/audit

Start audits programmatically. Queue multiple URLs, set priorities, and configure audit depth. Results available via polling or webhook.

📈

Get Results

GET /v1/audit/:id

Retrieve all 457 data points including AI insights, performance metrics, and prioritized recommendations in structured JSON.

🔔

Webhooks

POST /v1/webhooks

Get notified when audits complete. Push results to your CRM, Slack, or custom endpoints. No polling required.

📄

Generate PDFs

GET /v1/audit/:id/pdf

Generate white-label PDF reports with your branding. Download directly or get a signed URL for client delivery.

📋

List Audits

GET /v1/audits

Paginated list of all audits with filtering by date, domain, score, and status. Build custom dashboards and reports.

🏢

Manage Clients

POST /v1/clients

Create and manage client workspaces programmatically. Organize audits by client with separate branding configurations.

API Examples
# Start an audit
curl -X POST https://api.schemareports.com/v1/audit \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "depth": 10}'

# Response
{
  "id": "audit_abc123xyz",
  "status": "processing",
  "url": "https://example.com",
  "created_at": "2025-01-15T10:30:00Z"
}

# Get audit results
curl https://api.schemareports.com/v1/audit/audit_abc123xyz \
  -H "Authorization: Bearer YOUR_API_KEY"

# Generate white-label PDF
curl https://api.schemareports.com/v1/audit/audit_abc123xyz/pdf \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o report.pdf

# List all audits (paginated)
curl "https://api.schemareports.com/v1/audits?page=1&limit=20&status=completed" \
  -H "Authorization: Bearer YOUR_API_KEY"
import requests
import time

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.schemareports.com/v1"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

# Start an audit
response = requests.post(
    f"{BASE_URL}/audit",
    headers=headers,
    json={
        "url": "https://example.com",
        "depth": 10
    }
)
audit_id = response.json()["id"]
print(f"Audit started: {audit_id}")

# Poll for completion
while True:
    result = requests.get(
        f"{BASE_URL}/audit/{audit_id}",
        headers=headers
    ).json()

    if result["status"] == "completed":
        print(f"Score: {result['score']}")
        break

    time.sleep(5)

# Download PDF report
pdf_response = requests.get(
    f"{BASE_URL}/audit/{audit_id}/pdf",
    headers=headers
)
with open("report.pdf", "wb") as f:
    f.write(pdf_response.content)
const axios = require('axios');

const API_KEY = 'YOUR_API_KEY';
const BASE_URL = 'https://api.schemareports.com/v1';

const client = axios.create({
  baseURL: BASE_URL,
  headers: { 'Authorization': `Bearer ${API_KEY}` }
});

// Start an audit
async function runAudit(url) {
  const { data } = await client.post('/audit', {
    url,
    depth: 10
  });

  console.log(`Audit started: ${data.id}`);
  return data.id;
}

// Poll for results
async function waitForResults(auditId) {
  while (true) {
    const { data } = await client.get(`/audit/${auditId}`);

    if (data.status === 'completed') {
      console.log(`Score: ${data.score}`);
      return data;
    }

    await new Promise(r => setTimeout(r, 5000));
  }
}

// Usage
(async () => {
  const auditId = await runAudit('https://example.com');
  const results = await waitForResults(auditId);
  console.log(results);
})();

Authentication

All API requests require a Bearer token. Get your API key from your dashboard settings. Keys can be scoped to specific permissions and revoked at any time.

  • Bearer token authentication on all endpoints
  • Keys never expire, but can be revoked anytime
  • Separate keys for test and production environments
  • Scoped permissions available (read-only, write, admin)
  • Rate limits applied per API key
  • All requests logged for security auditing
# Include in all requests
Authorization: Bearer sk_live_abc123...

# Response on auth failure (401)
{
  "error": "unauthorized",
  "message": "Invalid or expired API key",
  "status": 401
}

Rate Limits

Starter
100
requests / hour
Professional
1,000
requests / hour
Agency
10,000
requests / hour

Rate limit headers included in every response. Enterprise plans have custom limits. Contact sales for higher throughput requirements.

Endpoint Reference

POST /v1/audit

Start a new website audit. Returns an audit ID that can be used to poll for results or configure webhooks.

Request Body
url string Required. The URL to audit. Must be publicly accessible.
depth integer Optional. Number of pages to crawl. Default: 10. Max: 100.
client_id string Optional. Associate audit with a client workspace.
webhook_url string Optional. URL to POST results when audit completes.
GET /v1/audit/:id

Retrieve audit results. Returns full data when status is "completed", or current status if still processing.

Response Fields
status string "queued", "processing", "completed", or "failed"
score integer Overall audit score (0-100). Only when completed.
data object Full audit data with 457 data points. Only when completed.
GET /v1/audit/:id/pdf

Generate a PDF report for the audit. Returns the PDF file directly or a signed URL depending on parameters.

Query Parameters
format string "file" (default) returns binary, "url" returns signed download link.
branding string Client ID for white-label branding, or "default".

Full API reference with all endpoints, parameters, and response schemas available in our complete documentation.

Webhook Support

Instead of polling for results, configure webhooks to receive notifications when audits complete. We POST the full audit data to your endpoint.

🔔
audit.completed

Fired when an audit finishes successfully. Includes full audit data in the payload.

🚨
audit.failed

Fired when an audit fails. Includes error details and failure reason.

📊
batch.completed

Fired when a bulk audit batch finishes. Includes summary and individual audit IDs.

🔒
Signature Verification

All webhooks include a signature header for verification. Prevent replay attacks.

Integration Examples

🏢

CRM Integration

Trigger audits when new leads enter Salesforce or HubSpot. Attach audit scores to contact records for lead scoring.

💬

Slack Notifications

Post audit summaries to Slack channels. Alert teams when client scores drop below thresholds.

📈

Dashboard Embedding

Fetch audit data and display in custom dashboards. Build client portals with real-time audit scores.

📅

Scheduled Audits

Use cron jobs to trigger weekly audits of client portfolios. Automate monitoring workflows.

📋

Report Generation

Pull audit data into reporting tools like Tableau or Power BI for custom analytics and visualizations.

📧

Email Automation

Send automated audit reports to clients via email. Integrate with Mailchimp, SendGrid, or custom SMTP.

Developer FAQ

How do I get an API key?

+

API keys are available on Professional and Agency plans. Log into your dashboard, navigate to Settings > API Keys, and click "Generate New Key". You can create multiple keys with different permission scopes for different integrations.

What's the latency for audit results?

+

Audit completion time depends on site complexity. Simple sites (10-20 pages) typically complete in 30-60 seconds. Larger sites with more pages take proportionally longer. Average time for a 10-page depth audit is under 2 minutes. Use webhooks to avoid polling latency.

Can I run bulk audits via API?

+

Yes. You can either submit multiple audit requests in parallel (subject to rate limits), or use the /v1/batch endpoint to submit a list of URLs in a single request. Batch endpoints are available on Agency plans and return a batch ID for tracking.

Are there SDKs available?

+

We provide official SDKs for Python and Node.js, with community-maintained libraries for PHP, Ruby, and Go. SDKs handle authentication, rate limiting, and provide typed responses. Check our GitHub organization for the latest versions.

What happens if I exceed rate limits?

+

Requests exceeding rate limits receive a 429 response with a Retry-After header indicating when to retry. We recommend implementing exponential backoff. Rate limits reset hourly. Contact sales if you need higher limits for your use case.

Is there a sandbox environment?

+

Yes. Use API keys prefixed with "sk_test_" to access the sandbox. Sandbox audits run against mock data and don't count against your quota. Perfect for development and testing integrations before going live.

Ready to Build?

API access is included with Professional and Agency plans. Get your API key and start integrating SchemaReports into your workflow today.