RESTful API v1 Documentation

Developer API Reference

Inspect your website meta tags programmatically or generate dynamic 1200x630 pixel OpenGraph cover images for your pages.

Base URL: https://opengraph.click/api/v1 Public API (Keyless) < 5ms Cache Response JSON & Image/PNG

Table of Contents

v1.0

Developer Tip

of your HTML pages <head> block directly /api/v1/og/image endpoint, you can automatically serve cover images with no additional server load.

Introduction & Quick Start

Architecture

opengraph.click, offers a comprehensive social media infrastructure for modern web projects consisting of two main branches:

Service 1

Meta Tag Inspection Engine

Instantly scans any URL, parses OpenGraph and Twitter Card tags, and provides a 0-100 health score along with an improvement guide.

Service 2

Dynamic Image Generation Engine

Generates dynamic social cover images in 1200x630 pixel size using 6 different professional templates; delivers directly via PNG stream or JSON output.

Base URL and Protocol

REST API Base Endpoint

https://opengraph.click/api/v1

Authentication & Request Headers

In the current version, all public GET and POST endpoints can be used directly without requiring an API key. For standard JSON requests, please include the following HTTP headers:

HTTP Header	Value	Description
Accept	`application/json` or `image/png`	Preferred MIME type for JSON data or binary image output.
Content-Type	`application/json`	Required when sending a JSON body in POST requests.

GET /api/v1/inspect

Service 1

Scans the specified web page in the background and parses its HTML <head> structure. It presents standard meta tags, OpenGraph parameters, Twitter Card information, and a 0-100 health score (health) in JSON format.

Cache Policy: Successful analysis results are cached using the URL hash for 5 minutes (300 seconds) . The cached: true value in the response indicates that the data was returned from the cache.

Query Parameters

Parameter	Type	Required	Description
url	string	Required	The full URL address of the target web page to inspect (e.g. `https://cekirdekod.com`).

Code Examples (Request)

Bash / Terminal

curl -X GET "https://opengraph.click/api/v1/inspect?url=https://cekirdekod.com" \
  -H "Accept: application/json"

JavaScript (ES6+)

const targetUrl = 'https://cekirdekod.com';
const response = await fetch(`https://opengraph.click/api/v1/inspect?url=${encodeURIComponent(targetUrl)}`, {
  headers: {
    'Accept': 'application/json'
  }
});

const result = await response.json();
console.log('Health Score:', result.health.score);
console.log('OpenGraph Title:', result.data.open_graph.title);

PHP 8.2+ (Laravel Http Client)

use Illuminate\Support\Facades\Http;

$response = Http::acceptJson()->get('https://opengraph.click/api/v1/inspect', [
    'url' => 'https://cekirdekod.com',
]);

if ($response->successful()) {
    $audit = $response->json();
    $score = $audit['health']['score'];
    $ogData = $audit['data']['open_graph'];
}

Python 3.10+ (requests)

import requests

url = "https://opengraph.click/api/v1/inspect"
params = {"url": "https://cekirdekod.com"}
headers = {"Accept": "application/json"}

res = requests.get(url, params=params, headers=headers)
data = res.json()

print(f"Health Score: {data['health']['score']}/100")
print(f"OG Title: {data['data']['open_graph']['title']}")

Successful Response Schema (200 OK)

200 OK application/json

{
  "success": true,
  "url": "https://cekirdekod.com",
  "cached": false,
  "data": {
    "title": "Çekirdekod - Dijital Çözüm &amp; Yazılım Stüdyosu",
    "description": "Modern yazılım mimarileri, yüksek performanslı web çözümleri ve yapay zeka entegrasyonları.",
    "canonical_url": "https://cekirdekod.com",
    "favicon": "https://cekirdekod.com/favicon.ico",
    "open_graph": {
      "title": "Çekirdekod - Dijital Çözüm &amp; Yazılım Stüdyosu",
      "description": "Modern yazılım mimarileri, yüksek performanslı web çözümleri.",
      "image": "https://cekirdekod.com/og-cover.png",
      "type": "website",
      "site_name": "Çekirdekod",
      "url": "https://cekirdekod.com"
    },
    "twitter": {
      "card": "summary_large_image",
      "title": "Çekirdekod - Dijital Çözüm &amp; Yazılım Stüdyosu",
      "description": "Modern yazılım mimarileri, yüksek performanslı web çözümleri.",
      "image": "https://cekirdekod.com/og-cover.png",
      "site": "@cekirdekod"
    },
    "raw_tags": {
      "og:title": "Çekirdekod - Dijital Çözüm &amp; Yazılım Stüdyosu",
      "og:image": "https://cekirdekod.com/og-cover.png",
      "twitter:card": "summary_large_image"
    }
  },
  "health": {
    "score": 95,
    "passed": [
      "OpenGraph title (og:title) is defined and of ideal length",
      "Cover image (og:image) is defined and accessible over HTTPS",
      "Twitter large card format (summary_large_image) is enabled",
      "Canonical URL definition is present and consistent"
    ],
    "warnings": [
      "og:description text is slightly short (58 characters, recommended 80-160)"
    ],
    "recommendations": [
      "You can increase the click-through rate in social shares by enriching the Description field."
    ]
  }
}

GET /api/v1/og/image

Service 2

Directly in your HTML pages <meta property="og:image"> provides a dynamic binary PNG image stream that you can paste into the tag. When a browser or social media crawler calls this address, it instantly receives a high-quality 1200x630 pixel cover image.

Performance and CDN Caching Architecture

On the first generation request, the image is created in the background and written to local storage. All subsequent requests are served directly from the disk thanks to the deterministic MD5 key and under 3 milliseconds are delivered.

Cache-Control: public, max-age=31536000, immutable X-OG-Cached: true / false X-OG-Hash: [MD5 Hash]

Query Parameters

Parameter	Type	Default	Description
title	string	Required	The main title to be featured on the cover image (maximum 200 characters).
template	string	`nordic-zen`	Options: `pro-developer`, `saas-product`, `article-card`, `cyber-console`, `nordic-zen`, `minimal-card`.
theme	string	`dark`	Options: `dark` (Sumi), `light` (Washi), `night-blue`.
accent	string	`matcha`	Accent color: `matcha`, `blue`, `sapphire`, `amber`, `purple`.
subtitle	string	-	Subtitle, specialty role, or slogan (maximum 300 characters).
description	string	-	Description paragraph or extended summary text (maximum 400 characters).
badge	string	-	Status or version pill in the top corner of the card (e.g.: `v2.4.0`).
category	string	-	Category or product group label (e.g.: `SaaS Platform`).
cta_text	string	-	Call to action / Button label (e.g.: `Get Started →`).
metric_1_val, metric_1_lbl	string	-	1. SaaS metric value and label (e.g.: `99.9%` / `Uptime SLA`).
metric_2_val, metric_2_lbl	string	-	2. SaaS metric value and label (e.g.: `<15ms` / `Latency`).
metric_3_val, metric_3_lbl	string	-	3. SaaS metric value and label (e.g.: `100M+` / `Monthly Requests`).
mockup_title, mockup_path	string	-	SaaS mockup window tab title and URL path (e.g.: `app.opengraph.click` / `/dashboard`).
mockup_image	string (url/path)	-	Mockup image URL address or in-studio file path.
avatar	string (url)	-	Profile photo, brand icon, or author avatar URL address.
initials	string	-	2-letter monogram to display when avatar image is not found (e.g.: `TC`).
tags	string	-	Comma-separated technology or keyword pills (e.g.: `PHP, Laravel, Docker`).
author, author_title	string	-	Author name and title (especially for `article-card` ).
date, read_time	string	-	Publish date and estimated read time (e.g.: `October 12, 2026` / `5 min read`).
code_snippet	string	-	Console line or CLI command (e.g.: `> php artisan serve`).
code_filename, code_lang	string	-	Code tab file name and language badge (e.g.: `Server.php` / `PHP`).
telemetry_1, telemetry_2, telemetry_3	string	-	Console telemetry metrics (e.g.: `LATENCY: 12ms`, `REGION: eu-central-1`, `STATUS: 200 OK`).
github	string	-	GitHub profile username (e.g.: `github.com/tnhnclskn`).
email	string	-	Contact email address (e.g.: `info@cekirdekod.com`).
location	string	-	City/country location info (e.g.: `Bursa / Turkey`).
site_name	string	-	Domain name or brand name at the bottom corner of the card (e.g.: `opengraph.click`).
format	string	`png`	To get JSON meta information instead of a binary image `json` can be sent.

Integration Examples for Your Projects

HTML5 <head> block

&lt;!-- OpenGraph / Facebook / LinkedIn --&gt;
&lt;meta property="og:title" content="Page Title"&gt;
&lt;meta property="og:description" content="Page description and summary."&gt;
&lt;meta property="og:image" content="https://opengraph.click/api/v1/og/image?title=Page+Title&amp;template=pro-developer&amp;theme=dark&amp;accent=sapphire"&gt;
&lt;meta property="og:image:width" content="1200"&gt;
&lt;meta property="og:image:height" content="630"&gt;
&lt;meta property="og:type" content="website"&gt;

&lt;!-- Twitter Card --&gt;
&lt;meta name="twitter:card" content="summary_large_image"&gt;
&lt;meta name="twitter:image" content="https://opengraph.click/api/v1/og/image?title=Page+Title&amp;template=pro-developer&amp;theme=dark&amp;accent=sapphire"&gt;

resources/views/layouts/app.blade.php

{{ __('docs.codeIntBlade.lt_php_ogimageurl_route') }}{{ $ogImageUrl }}{{ __('docs.codeIntBlade.gt_lt_meta_property') }}{{ $ogImageUrl }}{{ __('docs.codeIntBlade.gt') }}

app/posts/[slug]/page.tsx

import type { Metadata } from 'next';

export async function generateMetadata({ params }: { params: { slug: string } }): Promise&lt;Metadata&gt; {
  const post = await getPost(params.slug);

  const ogUrl = new URL('https://opengraph.click/api/v1/og/image');
  ogUrl.searchParams.set('title', post.title);
  ogUrl.searchParams.set('template', 'saas-product');
  ogUrl.searchParams.set('theme', 'dark');
  ogUrl.searchParams.set('accent', 'sapphire');
  ogUrl.searchParams.set('badge', 'Launch');

  return {
    title: post.title,
    openGraph: {
      title: post.title,
      description: post.summary,
      images: [
        {
          url: ogUrl.toString(),
          width: 1200,
          height: 630,
          alt: post.title,
        },
      ],
    },
    twitter: {
      card: 'summary_large_image',
      images: [ogUrl.toString()],
    },
  };
}

pages/articles/[slug].vue

&lt;script setup lang="ts"&gt;
const { data: article } = await useFetch(`/api/articles/${route.params.slug}`);

const ogImageUrl = computed(() =&gt; {
  const params = new URLSearchParams({
    title: article.value?.title || '',
    template: 'article-card',
    theme: 'dark',
    accent: 'matcha',
    badge: article.value?.category || 'Blog',
  });
  return `https://opengraph.click/api/v1/og/image?${params.toString()}`;
});

useSeoMeta({
  title: () =&gt; article.value?.title,
  ogTitle: () =&gt; article.value?.title,
  ogDescription: () =&gt; article.value?.excerpt,
  ogImage: ogImageUrl,
  ogImageWidth: 1200,
  ogImageHeight: 630,
  twitterCard: 'summary_large_image',
  twitterImage: ogImageUrl,
});
&lt;/script&gt;

POST /api/v1/og/render

Service 2 (JSON API)

It is a RESTful JSON endpoint designed for SaaS products, CMS systems, dynamic content platforms, or CI/CD pipelines. It accepts parameters in the request body (JSON Body); fetches the image from the cache or creates it instantly, and returns the persistent access URL, direct download URL, and pixel dimensions (1200x630) in JSON format.

Request Body Parameters (JSON Body)

Field	Type	Required	Description
title	string	Required	Title to be displayed on the cover image (maximum 200 characters).
template	string	Optional	`pro-developer`, `saas-product`, `article-card`, `cyber-console`, `nordic-zen`, `minimal-card`.
theme	string	Optional	`dark`, `light`, `night-blue`.
accent	string	Optional	`matcha`, `blue`, `sapphire`, `amber`, `purple`.
subtitle	string	Optional	Subtitle, slogan, or title (maximum 300 characters).
description	string	Optional	Broad description paragraph or product summary (maximum 400 characters).
badge	string	Optional	Version or status badge (e.g.: `v2.4.0`).
category	string	Optional	Category or product vertical label (e.g.: `SaaS Platform`).
cta_text	string	Optional	Call to action / Button label (e.g.: `Get Started →`).
metric_1_val, metric_1_lbl	string	Optional	1st SaaS metric value and label (e.g.: `99.9%` / `Uptime SLA`).
metric_2_val, metric_2_lbl	string	Optional	2nd SaaS metric value and label (e.g.: `<15ms` / `Latency`).
metric_3_val, metric_3_lbl	string	Optional	3. SaaS metric value and label (e.g.: `100M+` / `Monthly Requests`).
mockup_title, mockup_path	string	Optional	SaaS mockup window tab title and URL path (e.g.: `app.opengraph.click` / `/dashboard`).
mockup_image	string	Optional	Mockup image URL address or local file path.
avatar	string (url)	Optional	Profile photo or brand logo URL address.
initials	string	Optional	2-letter monogram to display when there is no avatar image (e.g.: `TC`).
tags	string / array	Optional	Array of tags or comma-separated string (e.g.: `["Laravel", "Docker"]`).
author, author_title	string	Optional	Author name and title (especially for `article-card` ).
date, read_time	string	Optional	Publish date and estimated read time (e.g.: `October 12, 2026` / `5 min read`).
code_snippet	string	Optional	Single-line console command (e.g.: `> php artisan serve`).
code_filename, code_lang	string	Optional	Cyber editor file name and language badge (e.g.: `Server.php` / `PHP`).
code_body	string	Optional	Multi-line rich code block (for terminal/editor, maximum 4000 characters).
telemetry_1, telemetry_2, telemetry_3	string	Optional	Console telemetry metrics (e.g.: `LATENCY: 12ms`, `STATUS: 200 OK`).
github, email, location	string	Optional	Developer credentials: GitHub profile, email, and location information.
site_name	string	Optional	Brand or website name (e.g.: `opengraph.click`).

Example Request (cURL)

POST cURL

curl -X POST "https://opengraph.click/api/v1/og/render" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "title": "Cloud-Focused Distributed Systems with Laravel 13",
    "template": "saas-product",
    "theme": "dark",
    "accent": "sapphire",
    "subtitle": "High Availability and Low Latency Infrastructure",
    "category": "SaaS Infrastructure",
    "badge": "v2.4.0 Launch",
    "cta_text": "Explore Now →",
    "metric_1_val": "99.9%",
    "metric_1_lbl": "Uptime SLA",
    "metric_2_val": "<15ms",
    "metric_2_lbl": "Gecikme",
    "metric_3_val": "100M+",
    "metric_3_lbl": "Aylık İstek",
    "mockup_title": "app.opengraph.click/telemetry",
    "mockup_path": "/dashboard/realtime",
    "tags": ["Laravel", "PHP 8.4", "Docker", "DevOps"],
    "site_name": "opengraph.click"
  }'

Successful Response Schema (200 OK)

200 OK application/json

{
  "success": true,
  "image_url": "https://opengraph.click/storage/og-generated/7b9e6f8a2c1d.png",
  "download_url": "https://opengraph.click/generate/download?file=7b9e6f8a2c1d.png",
  "hash": "7b9e6f8a2c1d4e3f890123456789abcd",
  "cached": false,
  "dimensions": {
    "width": 1200,
    "height": 630
  }
}

GET /api/v1/generate

Backward Compatibility (Legacy GD)

It is a lightweight image generation endpoint based on the GD library that provides full backward compatibility with legacy systems. For rich templates and high resolution in new projects, /api/v1/og/image should be preferred.

Example Request (cURL)

curl -X GET "https://opengraph.click/api/v1/generate?title=H%C4%B1zl%C4%B1+G%C3%B6rsel&amp;theme=nordic-dark&amp;accent=blue"

6 Design Templates & Usage Guide

Design Studio

Each template is optimized with precise 1200x630 pixel dimensions for a different content type and use case:

pro-developer Reference Caliber

Pro Developer & Engineer Portfolio

Reference template designed for developer portfolios, GitHub profile cards, and technical leads.

Highlighted Features:

Profile image or monogram avatar (avatar, initials)
Status or version badge (badge)
Console terminal line (code_snippet)
Technology tag pills (tags)
Social credentials (github, email, location)

See Template Live

saas-product Launch & Product

SaaS Launch & Product Card

High-converting modern card for software products, start-up launches, and new feature announcements.

Highlighted Features:

SaaS performance metrics (metric_1/2/3_val & lbl)
Browser mockup window (mockup_title, mockup_path, mockup_image)
Category, version badge & CTA button (category, badge, cta_text)
Product logo & benefit points (avatar, tags)
Official brand / domain name credentials (site_name)

See Template Live

article-card Blog & Publishing

Editorial Article & Technical Blog

Editorial typography layout for software blogs, technical articles, newsletters, and media portals.

Highlighted Features:

Category and topic badges (category, badge)
Author credentials and avatar (author, author_title, avatar)
Publish date and read time (date, read_time)
Tags and topic titles (tags)

See Template Live

cyber-console Terminal & CLI

Cyber Terminal & CLI Console

Terminal window for open source libraries, CLI tools, DevOps command sets, and cybersecurity projects.

Highlighted Features:

Terminal command console (code_snippet)
Code editor tab & language tag (code_filename, code_lang)
Rich multi-line code body (code_body)
Real-time telemetry metrics (telemetry_1, telemetry_2, telemetry_3)
Package manager tags (tags)

See Template Live

nordic-zen Sumi & Washi

Nordic-Zen (Sumi / Washi Elegance)

Elegant corporate card with eye-resting spacious gaps, top accent line, and soothing typography.

Highlighted Features:

Top accent highlight strip (accent)
Wide description and biography area (description)
Balanced brand and domain credentials (site_name)
Sumi (Dark) and Washi (Light) dual theme support

See Template Live

minimal-card 1px Geometry

Minimalist Frame & Ambient Light

1 pixel accent border, light top ambient light distribution, and high-contrast minimalist typography.

Highlighted Features:

Elegant 1px frame and top edge accent
Light radial glow (Glow Aura)
High-legibility large title (title)
Compact category badge (badge)

See Template Live

Themes & Color Accents

Design Tokens

1. Supported Color Themes (`theme`)

3 main themes determining the background atmosphere of the card in image generation:

Nordic Dark (dark)

Sumi stone color (#111315) deep and eye-resting dark background.

Nordic Light (light)

Washi paper texture (#f5f6f3) bright, spacious, and clean background.

Night Blue (night-blue)

Deep night navy blue (#0b1120) space tone and cyber atmosphere.

2. Supported Accent Colors (`accent`)

5 accent options used in title highlights, badges, buttons, and border glows:

Color Preview	Parameter Value	HEX Code	Character & Purpose of Use	Parameter Example
Matcha Green	`matcha`	#84cc16	Natural, vibrant, growth, and technology-focused primary accent.	`?accent=matcha`
Çekirdekod Blue	`blue`	#2176bd	Corporate, reliable, architectural, and analytical balanced blue.	`?accent=blue`
Electric Blue (Sapphire)	`sapphire`	#38bdf8	High contrast, for cyber, modern SaaS, and CLI projects.	`?accent=sapphire`
Oolong Amber	`amber`	#eab308	Warm, eye-catching, for editorial articles and announcements.	`?accent=amber`
Neon Purple (Violet)	`purple`	#8b5cf6	Creative, for AI tools and next-generation web products.	`?accent=purple`

HTTP Status Codes & Error Handling

Error Handling

All API endpoints return standard HTTP status codes. For failed requests, descriptive JSON responses are transmitted.

Status Code	Definition	Why Does It Occur?	Solution / Action
200 OK	Successful	Request successfully processed; PNG image or JSON analysis transmitted.	-
422 Unprocessable	Validation Error	Required parameter missing (`title` or `url`), character limit exceeded, or invalid template name entered.	Verify the request parameters and their types.
502 Bad Gateway	Remote Service Error	Target URL could not be reached (timeout) or the remote image generation service did not respond.	Confirm the accessibility of the target site and try again.

422 Validation Error Response Example

422 Unprocessable JSON Validation Response

{
  "message": "Image title (title) is required.",
  "errors": {
    "title": [
      "Image title (title) is required."
    ]
  }
}

502 Network / Connection Timeout Response Example

502 Bad Gateway Connection Error

{
  "success": false,
  "url": "https://example-invalid-domain.xyz",
  "message": "The specified URL could not be reached or the connection timed out: cURL error 28: Connection timed out"
}

Live Test Tool (Interactive Playground)

Live Sandbox

Before moving to your developer environment, test both services instantly with their parameters via the browser, copy the generated GET URL, or inspect the live result:

Dynamic Image API (GET /api/v1/og/image) Meta Inspection API (GET /api/v1/inspect)

Image Title (title) *

Subtitle / Role (subtitle)

Template (template)

Theme (theme)

Accent Color (accent)

Badge Text (badge)

Tags (tags)

Live Generated Request URL

Test It

Live Request Result

JSON Response

// Waiting for JSON result...

Developer API Reference

Introduction &amp; Quick Start

Meta Tag Inspection Engine

Dynamic Image Generation Engine

Base URL and Protocol

Authentication &amp; Request Headers

Query Parameters

Code Examples (Request)

Successful Response Schema (200 OK)

Performance and CDN Caching Architecture

Query Parameters

Integration Examples for Your Projects

Request Body Parameters (JSON Body)

Example Request (cURL)

Successful Response Schema (200 OK)

6 Design Templates &amp; Usage Guide

Pro Developer &amp; Engineer Portfolio

SaaS Launch &amp; Product Card

Editorial Article &amp; Technical Blog

Cyber Terminal &amp; CLI Console

Nordic-Zen (Sumi / Washi Elegance)

Minimalist Frame &amp; Ambient Light

Themes &amp; Color Accents

1. Supported Color Themes (theme)

2. Supported Accent Colors (accent)

HTTP Status Codes &amp; Error Handling

422 Validation Error Response Example

502 Network / Connection Timeout Response Example

Live Test Tool (Interactive Playground)

Live Request Result

Introduction & Quick Start

Authentication & Request Headers

6 Design Templates & Usage Guide

Pro Developer & Engineer Portfolio

SaaS Launch & Product Card

Editorial Article & Technical Blog

Cyber Terminal & CLI Console

Minimalist Frame & Ambient Light

Themes & Color Accents

1. Supported Color Themes (`theme`)

2. Supported Accent Colors (`accent`)

HTTP Status Codes & Error Handling