OpenGraph.io

OpenGraph.io - Extract, Screenshot, Scrape, Query, Generate

Extract web data, capture screenshots, and generate AI-powered images via OpenGraph.io APIs.

🤖 AI Agents: For complete parameter docs and patterns, also read references/for-ai-agents.md.

Quick Decision Guide

"I need data from a URL"

| Need | Endpoint | |------|----------| | Meta tags / link preview data | GET /site/{url} | | Raw HTML content | GET /scrape/{url} (add use_proxy=true if geo-blocked) | | Specific elements (h1, h2, p) | GET /extract/{url}?html_elements=h1,h2,p | | AI answer about the page | POST /query/{url} ⚠️ paid | | Visual screenshot | GET /screenshot/{url} |

"I need to generate an image"

| Need | Settings | |------|----------| | Technical diagram | kind: "diagram" — use diagramCode + diagramFormat for control | | App icon/logo | kind: "icon" — set transparent: true | | Social card (OG/Twitter) | kind: "social-card" — use aspectRatio: "og-image" | | Basic QR code | kind: "qr-code" | | Premium QR marketing card | kind: "illustration" — describe full design in prompt | | General illustration | kind: "illustration" |

QR Code: Basic vs Premium

Basic (kind: "qr-code"): Just the functional QR code.

Premium (kind: "illustration"): Full marketing asset with QR embedded in designed composition (gradients, 3D elements, CTAs, device mockups). Example prompt:

"Premium marketing card with QR code for https://myapp.com, cosmic purple gradient 
with floating 3D spheres, glowing accents, 'SCAN TO DOWNLOAD' call-to-action"

Diagram Tips

Use diagramCode + diagramFormat for reliable syntax (bypasses AI generation)
Use outputStyle: "standard" for structure-critical diagrams (premium may alter layout)
❌ Don't mix syntax with description: "graph LR A-->B make it pretty" will fail

Pricing & Requirements

| Feature | Free Tier | Paid Plans | |---------|-----------|------------| | Site/Unfurl | ✅ 100/month | Unlimited | | Screenshot | ✅ 100/month | Unlimited | | Scrape | ✅ 100/month | Unlimited | | Extract | ✅ 100/month | Unlimited | | Query (AI) | ❌ | ✅ | | Image Generation | ✅ 4/month | Unlimited |

💡 Try image generation free! Get 4 premium image generations per month on the free plan — no credit card required.

Quick Setup

Sign up at dashboard.opengraph.io — free trial available
Configure (choose one):

Option A: Clawdbot config (recommended)

// ~/.clawdbot/clawdbot.json
{
  skills: {
    entries: {
      "opengraph-io": {
        apiKey: "YOUR_APP_ID"
      }
    }
  }
}

Option B: Environment variable

export OPENGRAPH_APP_ID="YOUR_APP_ID"

Clawdbot Usage (REST API)

Use curl with the OPENGRAPH_APP_ID environment variable. Base URL: https://opengraph.io/api/1.1/

Extract OpenGraph Data (Site/Unfurl)

# Get OG tags from a URL
curl -s "https://opengraph.io/api/1.1/site/$(echo -n 'https://example.com' | jq -sRr @uri)?app_id=${OPENGRAPH_APP_ID}"

Response includes hybridGraph.title, hybridGraph.description, hybridGraph.image, etc.

Screenshot a Webpage

# Capture screenshot (dimensions: sm, md, lg, xl)
curl -s "https://opengraph.io/api/1.1/screenshot/$(echo -n 'https://example.com' | jq -sRr @uri)?app_id=${OPENGRAPH_APP_ID}&dimensions=lg"

Response: { "screenshotUrl": "https://..." }

Scrape HTML Content

# Fetch rendered HTML (with optional proxy)
curl -s "https://opengraph.io/api/1.1/scrape/$(echo -n 'https://example.com' | jq -sRr @uri)?app_id=${OPENGRAPH_APP_ID}&use_proxy=true"

Extract Specific Elements

# Pull h1, h2, p tags
curl -s "https://opengraph.io/api/1.1/extract/$(echo -n 'https://example.com' | jq -sRr @uri)?app_id=${OPENGRAPH_APP_ID}&html_elements=h1,h2,p"

Query (Ask AI About a Page)

curl -s -X POST "https://opengraph.io/api/1.1/query/$(echo -n 'https://example.com' | jq -sRr @uri)?app_id=${OPENGRAPH_APP_ID}" \
  -H "Content-Type: application/json" \
  -d '{"query": "What services does this company offer?"}'

Image Generation (REST API)

Base URL: https://opengraph.io/image-agent/

Step 1: Create a Session

SESSION=$(curl -s -X POST "https://opengraph.io/image-agent/sessions?app_id=${OPENGRAPH_APP_ID}" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-session"}')
SESSION_ID=$(echo $SESSION | jq -r '.sessionId')

Step 2: Generate an Image

curl -s -X POST "https://opengraph.io/image-agent/sessions/${SESSION_ID}/generate?app_id=${OPENGRAPH_APP_ID}" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A beautiful QR code linking to https://example.com with modern gradient design",
    "kind": "qr-code",
    "aspectRatio": "square",
    "quality": "high"
  }'

Image kinds: illustration, diagram, icon, social-card, qr-code

Style presets: github-dark, vercel, stripe, neon-cyber, pastel, minimal-mono

Aspect ratios: square, og-image (1200×630), twitter-card, instagram-story, etc.

Step 3: Download the Asset

ASSET_ID="<from-generate-response>"
curl -s "https://opengraph.io/image-agent/assets/${ASSET_ID}/file?app_id=${OPENGRAPH_APP_ID}" -o output.png

Step 4: Iterate (Refine an Image)

curl -s -X POST "https://opengraph.io/image-agent/sessions/${SESSION_ID}/iterate?app_id=${OPENGRAPH_APP_ID}" \
  -H "Content-Type: application/json" \
  -d '{
    "assetId": "<previous-asset-id>",
    "prompt": "Change the background to blue"
  }'

Natural Language Examples

When users ask in natural language, translate to the appropriate API call:

| User says | API to use | |-----------|------------| | "Get the OG tags from URL" | GET /site/{url} | | "Screenshot this page" | GET /screenshot/{url} | | "Scrape the HTML from URL" | GET /scrape/{url} | | "What does this page say about X?" | POST /query/{url} | | "Generate a QR code for URL" | POST /image-agent/sessions/{id}/generate with kind: "qr-code" | | "Create a premium QR marketing card" | POST /image-agent/sessions/{id}/generate with kind: "illustration" + design in prompt | | "Create a social card for my blog" | POST /image-agent/sessions/{id}/generate with kind: "social-card" | | "Make an architecture diagram" | POST /image-agent/sessions/{id}/generate with kind: "diagram" |

QR Code Options

Basic QR Code (kind: "qr-code"): Generates just the functional QR code with minimal styling.

Premium QR Marketing Card (kind: "illustration"): Generates a complete marketing asset with the QR code embedded in a professionally designed composition - gradients, 3D elements, CTAs, device mockups, etc.

# Premium QR marketing card example
curl -s -X POST "https://opengraph.io/image-agent/sessions/${SESSION_ID}/generate?app_id=${OPENGRAPH_APP_ID}" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Premium marketing card with QR code for https://myapp.com, cosmic purple gradient background with floating 3D spheres, glowing accents, SCAN TO DOWNLOAD call-to-action",
    "kind": "illustration",
    "aspectRatio": "square",
    "outputStyle": "premium",
    "brandColors": ["#6B4CE6", "#9B6DFF"],
    "stylePreferences": "modern, cosmic, premium marketing, 3D elements"
  }'

MCP Integration (for Claude Desktop, Cursor, etc.)

For AI clients that support MCP, use the MCP server:

# Interactive installer
npx opengraph-io-mcp --client cursor --app-id YOUR_APP_ID

# Or configure manually:
{
  "mcpServers": {
    "opengraph": {
      "command": "npx",
      "args": ["-y", "opengraph-io-mcp"],
      "env": {
        "OPENGRAPH_APP_ID": "YOUR_APP_ID"
      }
    }
  }
}

See references/mcp-clients.md for client-specific setup.

More Details

references/for-ai-agents.md — AI agent reference (tool schemas, decision trees, patterns)
references/api-reference.md — Complete API documentation (all endpoints, parameters, response schemas)
references/platform-support.md — Platform support guide (YouTube, Vimeo, TikTok, social media, e-commerce)
references/troubleshooting.md — Troubleshooting guide (common errors, debugging tips)
references/image-generation.md — Image presets, styles, templates
references/mcp-clients.md — MCP client configurations