Overview

Full programmatic access to every ValidGraph feature. The REST API enables automation, custom integrations, and embedding ValidGraph functionality into your own applications.

How It Works

1. Authenticate using API keys (see API Key Management)
2. All dashboard features are available via API endpoints
3. API conventions:
– JSON request/response format
– API versioning (v1)
– Rate limiting per plan tier
– Pagination for list endpoints
– Standard HTTP status codes
4. Comprehensive documentation with request/response examples

Tier Availability

| Tier | API Access |
|——|———–|
| Free | Limited (validate, usage, profile) |
| Pro | Extended (+ history, bulk, export, projects) |
| Agency | Full (+ monitoring, team, AI readiness) |
| Enterprise | Full + API key management + higher rate limits |

Related Features

– API Key Management: Authentication for API access
– Webhook Management: Event-driven alternative to polling

Mini-Tutorial

Step 1: Understand API Tiers

Free/Pro accounts get basic API access. Enterprise users get full unrestricted access plus higher rate limits.

Step 2: Generate an API Key

Navigate to Enterprise > API Keys and click “Create New Key.” Give it a descriptive name.

Step 3: Copy and Store Securely

Copy the key and store it in a secure location (e.g., environment variable, secrets manager). You won’t see it again.

Step 4: Make Your First Request

Use the key in the X-API-Key header:

GET /api/v1/projects
Headers: X-API-Key: sk_live_abc123...

Step 5: Explore Endpoints

Browse the full API documentation to discover endpoints for validation, projects, team, exports, webhooks, etc.

Step 6: Monitor Usage

Enterprise plans have unlimited rate limits, but you can monitor API usage in the dashboard.

Technical Details

Base URL

https://api.validgraph.io/api/v1

Authentication

All requests require API key in header:

X-API-Key: sk_live_abc123xyz789

Example: Validate a URL

POST /api/v1/validate
X-API-Key: sk_live_abc123xyz789
Content-Type: application/json

{
  "url": "https://example.com/page",
  "project_id": "proj_abc123"
}

Response:

{
  "id": "val_12345",
  "url": "https://example.com/page",
  "status": "valid",
  "score": 88,
  "schema_type": "Article",
  "errors": [],
  "warnings": [
    {
      "property": "author",
      "message": "Recommended property missing"
    }
  ]
}

Example: List Projects

GET /api/v1/projects?page=1&per_page=10
X-API-Key: sk_live_abc123xyz789

Example: Get Project Score

GET /api/v1/site-score?project_id=proj_abc123
X-API-Key: sk_live_abc123xyz789

Rate Limits (by Tier)

– Free: 5 requests/day
– Pro: 1,000 requests/month
– Agency: 10,000 requests/month
– Enterprise: Unlimited

Rate limit headers in response:

X-RateLimit-Limit: 10000
X-RateLimit-Used: 523
X-RateLimit-Remaining: 9477
X-RateLimit-Reset: 1645180800

Error Responses

Standard HTTP status codes:
– 200 OK: Successful request
– 400 Bad Request: Invalid parameters
– 401 Unauthorized: Missing or invalid API key
– 403 Forbidden: Insufficient permissions
– 404 Not Found: Resource not found
– 429 Too Many Requests: Rate limit exceeded
– 500 Internal Error: Server error

References

– REST API Design Best Practices
– OpenAPI 3.0 Specification
– HTTP Status Codes (RFC 7231)
– ValidGraph OpenAPI Spec