OpenAPI Specification & Reference
Complete HTTP endpoint reference generated at build time directly from the OpenAPI 3.1 specification.
The Open Graph Image Generator exposes a clean, deterministic REST API
adhering to the OpenAPI 3.1 contract. The specification is published at
packages/api-contract/openapi.json.
GET
/v1/health
Liveness probe
Always returns 200 when the Worker is running.
Example Request
curl -s "https://api.generativeog.in/v1/health" Direct URL: https://api.generativeog.in/v1/health
Responses
| Status | Content-Type | Description |
|---|---|---|
| 200 | application/json | Service is live |
GET
/v1/ready
Readiness probe
Verifies external dependencies and storage availability.
Example Request
curl -s "https://api.generativeog.in/v1/ready" Direct URL: https://api.generativeog.in/v1/ready
Responses
| Status | Content-Type | Description |
|---|---|---|
| 200 | application/json | Service and dependencies are ready |
| 503 | application/json | One or more dependencies are unavailable |
GET
Test in Playground
/v1/images/{layout}.png
Render or serve a cached Open Graph PNG image
Generates a deterministic PNG social card for the specified layout and query parameters, backed by Cloudflare Cache API and R2.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
layout | path | string | Yes | Layout identifier (`minimal`, `article`, `docs`, `product`, `profile`, `announcement`).
Allowed: minimalarticledocsproductprofileannouncement |
title | query | string | Yes | Primary title text (1–120 characters, NFC-normalized, no control characters). |
subtitle | query | string | No | Optional subtitle or kicker (up to 80 characters). |
description | query | string | No | Optional body description (up to 240 characters). |
size | query | string | No | Canvas dimensions preset (`landscape` = 1200×630, `square` = 1200×1200).
Allowed: landscapesquare |
theme | query | string | No | Color theme preset (`light` or `dark`).
Allowed: lightdark |
bg | query | string | No | Background color as 3 or 6 hex digits without `#`. |
bg2 | query | string | No | Secondary background hex color enabling linear gradient `bg -> bg2`. |
angle | query | string | No | Gradient angle in degrees (integer 0–360, only valid with `bg2`). |
color | query | string | No | Primary text color as 3 or 6 hex digits without `#`. |
accent | query | string | No | Accent color as 3 or 6 hex digits without `#`. |
font | query | string | No | Bundled typography family.
Allowed: intersource-serif-4jetbrains-mono |
align | query | string | No | Horizontal text alignment (`left` or `center`).
Allowed: leftcenter |
logo | query | string | No | HTTPS URL to a PNG or JPEG logo image (≤ 2 MB). |
logo_fit | query | string | No | Scaling mode for logo (`cover` or `contain`, default: `contain`).
Allowed: covercontain |
logo_radius | query | string | No | Corner shape for logo (`rounded`, `circle`, `square`, default: `rounded`).
Allowed: roundedcirclesquare |
logo_border | query | string | No | Edge border for logo (`subtle` or `none`, default: `none`).
Allowed: subtlenone |
avatar | query | string | No | HTTPS URL to a PNG or JPEG avatar image (≤ 2 MB). |
avatar_fit | query | string | No | Scaling mode for avatar (`cover` or `contain`, default: `cover`).
Allowed: covercontain |
avatar_radius | query | string | No | Corner shape for avatar (`rounded`, `circle`, `square`, default: `circle`).
Allowed: roundedcirclesquare |
avatar_border | query | string | No | Edge border for avatar (`subtle` or `none`, default: `subtle`).
Allowed: subtlenone |
image | query | string | No | HTTPS URL to a PNG or JPEG content screenshot/mockup image (≤ 2 MB). |
image_fit | query | string | No | Scaling mode for content image (`cover` or `contain`, default: `cover`).
Allowed: covercontain |
image_radius | query | string | No | Corner shape for content image (`rounded`, `circle`, `square`, default: `rounded`).
Allowed: roundedcirclesquare |
image_border | query | string | No | Edge border for content image (`subtle` or `none`, default: `subtle`).
Allowed: subtlenone |
bg_image | query | string | No | HTTPS URL to a PNG or JPEG full-bleed background image (≤ 2 MB). |
bg_overlay | query | string | No | Contrast-protecting tint opacity percentage over bg_image (integer 0–100, default: 75). |
author | query | string | No | Author display name (up to 40 characters). |
v | query | string | No | Cache-bust token matching `[a-z0-9]{1,16}`. |
if-none-match | header | string | No | Optional ETag for conditional requests (`"<hash>"`). Returns 304 on match. |
Example Request
curl -i "https://api.generativeog.in/v1/images/minimal.png?title=Hello+World&theme=dark"Responses
| Status | Content-Type | Description |
|---|---|---|
| 200 | image/png | Rendered or cached PNG image |
| 304 | — | Not Modified (ETag matched `If-None-Match`) |
| 400 | application/json | Invalid, missing, duplicate, or unknown query parameter |
| 404 | application/json | Unknown layout identifier |
| 414 | application/json | Request URL exceeds 2048 characters |
| 422 | application/json | Remote asset blocked by SSRF policy or failed validation |
| 429 | application/json | Per-minute or daily per-IP rate limit exceeded |
| 500 | application/json | Internal rendering error |
| 501 | application/json | Generation category not enabled |
| 503 | application/json | Service capacity exceeded or dependency unavailable |
| 504 | application/json | Remote asset fetch exceeded timeout deadline |
HEAD
/v1/images/{layout}.png
Fetch headers for a rendered or cached Open Graph PNG image
Executes the same validation, cache lookup, and render pipeline as GET, returning all image headers (`ETag`, `Content-Length`, `X-Cache`) without a response body.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
layout | path | string | Yes | Layout identifier (`minimal`, `article`, `docs`, `product`, `profile`, `announcement`).
Allowed: minimalarticledocsproductprofileannouncement |
title | query | string | Yes | Primary title text (1–120 characters, NFC-normalized, no control characters). |
subtitle | query | string | No | Optional subtitle or kicker (up to 80 characters). |
description | query | string | No | Optional body description (up to 240 characters). |
size | query | string | No | Canvas dimensions preset (`landscape` = 1200×630, `square` = 1200×1200).
Allowed: landscapesquare |
theme | query | string | No | Color theme preset (`light` or `dark`).
Allowed: lightdark |
bg | query | string | No | Background color as 3 or 6 hex digits without `#`. |
bg2 | query | string | No | Secondary background hex color enabling linear gradient `bg -> bg2`. |
angle | query | string | No | Gradient angle in degrees (integer 0–360, only valid with `bg2`). |
color | query | string | No | Primary text color as 3 or 6 hex digits without `#`. |
accent | query | string | No | Accent color as 3 or 6 hex digits without `#`. |
font | query | string | No | Bundled typography family.
Allowed: intersource-serif-4jetbrains-mono |
align | query | string | No | Horizontal text alignment (`left` or `center`).
Allowed: leftcenter |
logo | query | string | No | HTTPS URL to a PNG or JPEG logo image (≤ 2 MB). |
logo_fit | query | string | No | Scaling mode for logo (`cover` or `contain`, default: `contain`).
Allowed: covercontain |
logo_radius | query | string | No | Corner shape for logo (`rounded`, `circle`, `square`, default: `rounded`).
Allowed: roundedcirclesquare |
logo_border | query | string | No | Edge border for logo (`subtle` or `none`, default: `none`).
Allowed: subtlenone |
avatar | query | string | No | HTTPS URL to a PNG or JPEG avatar image (≤ 2 MB). |
avatar_fit | query | string | No | Scaling mode for avatar (`cover` or `contain`, default: `cover`).
Allowed: covercontain |
avatar_radius | query | string | No | Corner shape for avatar (`rounded`, `circle`, `square`, default: `circle`).
Allowed: roundedcirclesquare |
avatar_border | query | string | No | Edge border for avatar (`subtle` or `none`, default: `subtle`).
Allowed: subtlenone |
image | query | string | No | HTTPS URL to a PNG or JPEG content screenshot/mockup image (≤ 2 MB). |
image_fit | query | string | No | Scaling mode for content image (`cover` or `contain`, default: `cover`).
Allowed: covercontain |
image_radius | query | string | No | Corner shape for content image (`rounded`, `circle`, `square`, default: `rounded`).
Allowed: roundedcirclesquare |
image_border | query | string | No | Edge border for content image (`subtle` or `none`, default: `subtle`).
Allowed: subtlenone |
bg_image | query | string | No | HTTPS URL to a PNG or JPEG full-bleed background image (≤ 2 MB). |
bg_overlay | query | string | No | Contrast-protecting tint opacity percentage over bg_image (integer 0–100, default: 75). |
author | query | string | No | Author display name (up to 40 characters). |
v | query | string | No | Cache-bust token matching `[a-z0-9]{1,16}`. |
if-none-match | header | string | No | Optional ETag for conditional requests (`"<hash>"`). Returns 304 on match. |
Example Request
curl -I "https://api.generativeog.in/v1/images/minimal.png?title=Hello+World&theme=dark"Responses
| Status | Content-Type | Description |
|---|---|---|
| 200 | — | Headers for rendered or cached PNG image |
| 304 | — | Not Modified (ETag matched `If-None-Match`) |
| 400 | application/json | Invalid, missing, duplicate, or unknown query parameter |
| 404 | application/json | Unknown layout identifier |
| 414 | application/json | Request URL exceeds 2048 characters |
| 429 | application/json | Per-minute or daily per-IP rate limit exceeded |
| 501 | application/json | Generation category not enabled |
| 503 | application/json | Service capacity exceeded or dependency unavailable |
GET
/v1/images/screenshot.png
Reserved website screenshot generation route (planned)
Reserved route for live website screenshot generation. Returns 501 category_not_enabled until screenshot infrastructure is enabled.
Example Request
curl -X GET "https://api.generativeog.in/v1/images/screenshot.png"Responses
| Status | Content-Type | Description |
|---|---|---|
| 501 | application/json | Screenshot generation category is not enabled |
GET
/v1/images/ai.png
Reserved AI image generation route (planned)
Reserved route for AI-generated Open Graph images. Returns 501 category_not_enabled until AI generation is enabled.
Example Request
curl -X GET "https://api.generativeog.in/v1/images/ai.png"Responses
| Status | Content-Type | Description |
|---|---|---|
| 501 | application/json | AI image generation category is not enabled |
GET
/v1/layouts
List available Open Graph image layouts
Returns bounded metadata, supported query parameters, defaults, and example queries for all 6 built-in layouts.
Example Request
curl -s "https://api.generativeog.in/v1/layouts" Direct URL: https://api.generativeog.in/v1/layouts
Responses
| Status | Content-Type | Description |
|---|---|---|
| 200 | application/json | List of layouts |
GET
/v1/layouts/{id}
Get metadata for a single Open Graph image layout
Returns metadata, supported query parameters, defaults, and example query for a specific layout identifier.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Layout identifier |
Example Request
curl -s "https://api.generativeog.in/v1/layouts/minimal" Direct URL: https://api.generativeog.in/v1/layouts/minimal
Responses
| Status | Content-Type | Description |
|---|---|---|
| 200 | application/json | Layout metadata |
| 404 | application/json | Unknown layout identifier |
GET
/v1/capabilities
Get API capabilities, enabled categories, and anonymous limits
Returns API and render versions, generation categories with enabled/planned status, active anonymous rate limits and quotas, supported image sizes, bundled fonts, supported Unicode scripts, and remote asset constraints.
Example Request
curl -s "https://api.generativeog.in/v1/capabilities" Direct URL: https://api.generativeog.in/v1/capabilities
Responses
| Status | Content-Type | Description |
|---|---|---|
| 200 | application/json | API capabilities and limits |
POST
/v1/tools/inspect-page
Inspect Open Graph, Twitter Card, and SEO metadata on a public URL
Fetches up to 1 MB of HTML using the chosen social crawler User-Agent profile, parses metadata via HTMLRewriter, and returns actionable diagnostics.
Example Request
curl -X POST "https://api.generativeog.in/v1/tools/inspect-page" \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com","crawler":"generic"}'Responses
| Status | Content-Type | Description |
|---|---|---|
| 200 | application/json | Page metadata inspection report and diagnostics |
| 400 | application/json | Invalid request payload |
| 403 | application/json | Turnstile challenge verification failed |
| 422 | application/json | Target URL blocked by SSRF policy or unreachable |
| 429 | application/json | Per-minute rate limit exceeded |
| 504 | application/json | Target URL fetch exceeded deadline |
POST
/v1/tools/inspect-image
Inspect an Open Graph image URL for dimensions, format, and crawler compatibility
Fetches image headers and up to 8 MB of image bytes, parses format and dimensions without returning file contents, and produces actionable diagnostics.
Example Request
curl -X POST "https://api.generativeog.in/v1/tools/inspect-image" \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com/og.png"}'Responses
| Status | Content-Type | Description |
|---|---|---|
| 200 | application/json | Image metadata inspection report and diagnostics |
| 400 | application/json | Invalid request payload |
| 403 | application/json | Turnstile challenge verification failed |
| 422 | application/json | Target image URL blocked by SSRF policy or unreachable |
| 429 | application/json | Per-minute rate limit exceeded |
| 504 | application/json | Target image URL fetch exceeded deadline |
POST
/v1/events
Record an anonymous aggregate usage event
Increments a daily aggregate counter in D1 for product analytics. Collects no personal data, cookies, or identifiers.
Example Request
curl -X POST "https://api.generativeog.in/v1/events" \
-H "Content-Type: application/json" \
-d '{"event":"preview_rendered","properties":{"template":"minimal"}}'Responses
| Status | Content-Type | Description |
|---|---|---|
| 204 | — | Event count incremented |
| 400 | application/json | Invalid event name, dimension, or unknown field |
| 429 | application/json | Per-minute write rate limit exceeded |
| 503 | application/json | Database storage is unavailable |
POST
/v1/interest
Record anonymous demand interest for a planned capability
Increments a daily aggregate counter in D1 for a planned feature category after Turnstile verification. Collects no email, name, IP, or free text.
Example Request
curl -X POST "https://api.generativeog.in/v1/interest" \
-H "Content-Type: application/json" \
-d '{"category":"ai","contact":"user@example.com"}'Responses
| Status | Content-Type | Description |
|---|---|---|
| 204 | — | Interest count incremented |
| 400 | application/json | Invalid category or unknown field |
| 403 | application/json | Turnstile challenge verification failed |
| 429 | application/json | Per-minute interest rate limit exceeded |
| 503 | application/json | Database storage is unavailable |