The OpenGraph.so API

Two endpoints. Scan reads any public page and tells you how its link preview looks and what to fix — free, no key needed. Generate designs a brand-new 1200×630 share image and a matching favicon with AI — one credit per call, refunded automatically if it fails.

Authentication

Create a key on your account page and send it as a bearer token. Keys start with ogso_ and are shown only once. You can also send it as X-API-Key.

Authorization: Bearer ogso_your_key_here

Scan works without a key at 10 requests per hour per IP. With a key you get 300 scans and 60 generations per hour.

Scan a page

GET or POST /api/public/v1/scan

curl "https://opengraph.so/api/public/v1/scan?url=https://stripe.com"

Response

{
  "report": {
    "url": "https://stripe.com/",
    "score": 92,
    "tags": {
      "title": "Stripe | Financial Infrastructure",
      "ogTitle": "Stripe | Financial Infrastructure",
      "ogDescription": "...",
      "ogImage": "https://images.stripeassets.com/og.png",
      "twitterCard": "summary_large_image"
    },
    "image": { "width": 1200, "height": 630, "bytes": 184320 },
    "checks": [{ "id": "og:image", "status": "pass", "label": "..." }],
    "summary": "..."
  },
  "cached": false
}

Results are cached for 15 minutes per URL; a cached hit returns "cached": true and does not count differently.

Generate images

POST /api/public/v1/generate · API key required · 1 credit

curl -X POST https://opengraph.so/api/public/v1/generate \
  -H "Authorization: Bearer ogso_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://yoursite.com" }'

Response

{
  "id": "f3c1…",
  "url": "https://yoursite.com/",
  "images": {
    "og":      { "url": "https://…signed…/og.png",   "width": 1200, "height": 630 },
    "favicon": { "url": "https://…signed…/icon.png", "width": 512,  "height": 512 }
  },
  "meta": {
    "title": "…",
    "description": "…",
    "tags": ["<meta property=\"og:title\" …>"]
  },
  "credits": { "charged": 1, "remaining": 17 },
  "expiresIn": 3600
}

Image links are signed and valid for one hour — download and host them on your own domain. Every call also lands in your account history.

Node example

const res = await fetch("https://opengraph.so/api/public/v1/generate", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.OPENGRAPH_SO_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ url: "https://yoursite.com", accent: "#ff5c00" }),
});

const data = await res.json();
console.log(data.images.og.url);

Errors & credits

Errors come back as { "error": { "code", "message" } } with a matching HTTP status.

MCP server

Connect OpenGraph.so to Claude, ChatGPT, Cursor or any MCP client and ask it to check or design your link previews in plain language. You sign in once with your OpenGraph.so account, so generated images spend your credits and land in your history.

Server URL

https://opengraph.so/mcp

Add it as a remote MCP server. Your client opens a sign-in page, you approve the connection once, and the tools appear.

Claude Desktop / Cursor config

{
  "mcpServers": {
    "opengraph-so": {
      "url": "https://opengraph.so/mcp"
    }
  }
}

Tools

Failed generations are refunded the same way as the API, and scans stay free.

Works with any AI agent

The connection follows the open standard AI agents use to reach outside tools, so there is no special build for any one app. Point the agent at a single address, approve the connection once with your OpenGraph.so account, and it can scan pages, suggest tags and create share images from then on — images spend your credits and show up in your history just as if you made them on the site.

• Claude — desktop and web
• ChatGPT
• Cursor
• OpenClaw and other open agent setups
• Windsurf, Cline and similar coding agents
• Anything else speaking the same standard

OpenClaw / open agent config

{
  "servers": {
    "opengraph-so": {
      "type": "http",
      "url": "https://opengraph.so/mcp",
      "auth": "oauth"
    }
  }
}

Remote server over HTTP with sign-in handled by the agent — no local install, no npx step, nothing to keep running on your machine.

Worked examples

What each tool receives and what it sends back. Shortened for readability — real responses carry a few more fields.

{ "url": "https://stripe.com" }

{
  "url": "https://stripe.com/",
  "score": 92,
  "title": "Stripe | Financial Infrastructure",
  "description": "Millions of companies use Stripe…",
  "image": { "url": "https://…/og.png", "width": 1200, "height": 630 },
  "twitterCard": "summary_large_image",
  "issues": [],
  "summary": "Everything needed for a large image preview is present."
}

{
  "url": "https://yoursite.com/pricing",
  "title": "Pricing — Yoursite",
  "description": "Plans that scale with your team."
}

{
  "tags": [
    "<meta property=\"og:title\" content=\"Pricing — Yoursite\">",
    "<meta property=\"og:description\" content=\"Plans that scale with your team.\">",
    "<meta property=\"og:url\" content=\"https://yoursite.com/pricing\">",
    "<meta property=\"og:image\" content=\"https://yoursite.com/og/pricing.png\">",
    "<meta name=\"twitter:card\" content=\"summary_large_image\">"
  ],
  "notes": ["Host the image on your own domain at 1200x630."]
}

{
  "url": "https://yoursite.com",
  "accent": "#ff5c00",
  "favicon": true
}

{
  "id": "f3c1…",
  "url": "https://yoursite.com/",
  "headline": "Ship faster",
  "subline": "The workflow your team already knows.",
  "images": {
    "og":      { "url": "https://…signed…/og.png",   "width": 1200, "height": 630 },
    "favicon": { "url": "https://…signed…/icon.png", "width": 512,  "height": 512 }
  },
  "credits": { "charged": 1 },
  "note": "Download links expire in one hour."
}

{}

{
  "plan": "pro",
  "planLabel": "Pro",
  "allowanceThisMonth": 20,
  "usedThisMonth": 3,
  "monthlyLeft": 17,
  "topUpCredits": 10,
  "totalLeft": 27
}