API Documentation

Integration (Crawl-Back GET API)

OGCraft uses a secure Crawl-Back architecture. Instead of sending all your content and styling directly in the URL, you just provide the template ID and your page's url.

When a request is made, our API visits your page, extracts the title, description, and custom ogcraft:* meta tags, and applies the design settings you saved in your Dashboard.

Integration (Direct POST API)

If you prefer not to use the Crawl-Back architecture, you can generate images dynamically by sending a POST request directly to /api/v1/generate.

This endpoint requires your API Key to be passed in the Authorization: Bearer <API_KEY> header. You can find or regenerate your API Key in your Dashboard. You must provide a JSON body containing the template ID and any data fields you wish to populate.

Security & Domain Restriction

For the Crawl-Back API, you do not need to pass an API key in the URL. Instead, your template is protected by an allowedDomains list configured in your dashboard. Any call requesting a render for a URL originating from an unauthorized host will return an HTTP 403 Forbidden status code.

Alternatively, you can bypass the domain restriction by explicitly signing the url parameter with your API key and passing it as the sig parameter. The signature is a SHA256 HMAC of the target URL using your API key as the secret.

For the Direct POST API, authentication is strictly enforced using your API Key via the Authorization header. Keep your API key secure and never expose it in client-side code.

Rate Limits & Caching

To ensure service stability, all endpoints are protected by a basic IP rate limit of 60 requests per minute. If you exceed this, you will receive a 429 Too Many Requests response.

Additionally, generation quotas are applied based on your account tier:

• Free Tier: 100 requests per month (watermarked).
• Pro Tier: 10,000 requests per month (no watermark).
• Agency Tier: 50,000 requests per month (no watermark).

If you exceed your monthly quota, the API will return a 429 Usage limit exceeded status code.

All generated images are returned with immutable cache headers (public, max-age=31536000, immutable) for maximum performance on CDNs. If you update your page's meta tags, we recommend changing a query parameter in your og:image URL (like adding &v=2) to bypass social media caches.