# OpenGraph.io

> OpenGraph.io provides APIs and an MCP server for extracting metadata, capturing screenshots, scraping web content, converting pages to Markdown, querying pages with AI, auditing site SEO/social tags, checking link previews, and generating images. Trusted by thousands of developers worldwide.

## About

OpenGraph.io is a comprehensive suite of web data extraction and AI-powered APIs. Our services help developers build rich link previews, capture website screenshots, scrape HTML content, convert pages to Markdown, extract structured data, query pages with natural language, audit a site's SEO/social metadata, check how a link will preview on social platforms, and generate dynamic images — all available via REST API and MCP server for AI agents.

Website: https://www.opengraph.io
Documentation: https://www.opengraph.io/docs
Pricing: https://www.opengraph.io/pricing
MCP Server: https://www.opengraph.io/docs/mcp

## MCP Server (Model Context Protocol)

The OpenGraph.io MCP server (`opengraph-io-mcp`) makes all OpenGraph.io capabilities available to AI agents through the standard MCP interface. It includes 16 tools: 6 web data tools, 6 Site Audit & Link Preview tools (sign-in required), and 4 AI image generation tools.

**Install (recommended — hosted, sign in with your account):**
```json
{
  "mcpServers": {
    "opengraph": {
      "url": "https://mcp.opengraph.io/mcp"
    }
  }
}
```
No App ID required — a browser tab opens the first time you connect so you can sign in with your OpenGraph.io account. Required for the Site Audit and Link Preview tools.

**Alternative — hosted with a static API key:**
```json
{
  "mcpServers": {
    "opengraph": {
      "url": "https://mcp.opengraph.io/mcp",
      "headers": { "x-app-id": "YOUR_OPENGRAPH_APP_ID" }
    }
  }
}
```

**Alternative — run locally (stdio, no network required):**
```
npx -y opengraph-io-mcp
```

See https://www.opengraph.io/docs/mcp/authentication for details on both connection methods.

**Compatible AI Clients:** Claude Desktop, Cursor, VS Code (Copilot Chat), Windsurf, JetBrains AI Assistant, Zed, Cline

**Transport:** Streamable HTTP (hosted, recommended) — stdio and HTTP/SSE also available for local/legacy use

### Web Data Tools

Web data tools default to the current **v3** API, which enables smarter rendering and proxy handling automatically.

| Tool | Description |
|------|-------------|
| **Get OG Data** | Fetches Open Graph metadata, Twitter Cards, and hybrid social preview data from a URL. Maps to `/api/3.0/site`. |
| **Get OG Scrape Data** | Scrapes raw HTML content from a URL with JavaScript rendering and proxy support. Maps to `/api/3.0/scrape`. |
| **Get OG Screenshot** | Captures a screenshot of a webpage with configurable viewport sizes, full-page capture, and dark mode. Maps to `/api/3.0/screenshot`. |
| **Get OG Markdown** | Converts a URL's HTML into clean, readable Markdown with boilerplate stripped. Maps to `/api/3.0/markdown`. |
| **Get OG Extract** | Extracts specific HTML elements (by tag name or CSS selector) into structured data. Maps to `POST /api/3.0/extract`. |
| **Get OG Query** | Asks a natural-language question about a page and returns a structured, AI-generated answer. Maps to `/api/1.1/query`. |

### Site Audit & Link Preview Tools

Requires signing in with your account (not available with an `x-app-id` API key alone) since these tools bill against your organization's Site Audit plan. See https://www.opengraph.io/docs/mcp/site-audit-link-preview.

| Tool | Description |
|------|-------------|
| **discoverSiteUrls** | Crawls a domain and lists every page found, grouped by depth, plus your remaining monthly audit quota. |
| **startSiteAudit** | Kicks off an async, multi-page SEO/social audit. Returns an audit ID immediately. |
| **getSiteAuditStatus** | Polls an in-progress audit until it completes. |
| **getSiteAuditReport** | Retrieves the full report: overall score, an AI-generated summary, and per-page scores and issues. |
| **previewPageAudit** | Instant, synchronous quality check of a single URL. Does not use audit quota. |
| **getLinkPreview** | Instant check of how a URL will preview on Facebook, X/Twitter, LinkedIn, and Google. Does not use audit quota. |

### Image Generation Tools

| Tool | Description |
|------|-------------|
| **generateImage** | Creates images from text prompts (illustrations, diagrams, icons, social cards, QR codes) |
| **iterateImage** | Refines and modifies existing generated images without regenerating from scratch |
| **exportImageAsset** | Saves generated images to the local filesystem |
| **inspectImageSession** | Reviews generation history and retrieves asset metadata |

**Image Types:** illustration, diagram (Mermaid/D2/Vega-Lite), icon, social-card, qr-code

**Aspect Ratio Presets:** og-image (1200x630), twitter-card, twitter-post, linkedin-post, facebook-post, instagram-square, instagram-portrait, instagram-story, youtube-thumbnail, wide (16:9), square (1:1), portrait, icon-small (256x256), icon-medium (512x512), icon-large (1024x1024)

**Style Presets:** github-dark, github-light, notion, vercel, linear, stripe, neon-cyber, pastel, minimal-mono, corporate, startup, documentation, technical

**Diagram Templates:** auth-flow, oauth2-flow, crud-api, microservices, ci-cd, gitflow, database-schema, state-machine, user-journey, cloud-architecture, system-context

**Configuration Example (Claude Desktop, Cursor, and most clients):**
```json
{
  "mcpServers": {
    "opengraph": {
      "url": "https://mcp.opengraph.io/mcp"
    }
  }
}
```
Full copy-paste configs for every supported client: https://www.opengraph.io/docs/mcp/install

## APIs

### Link Preview API (Site Unfurling)

Extract OpenGraph metadata, Twitter Cards, and HTML meta tags from any URL to create rich link previews.

**Endpoint:** `GET https://opengraph.io/api/3.0/site/{encoded_url}` (v1.1 legacy also available at `/api/1.1/site/{encoded_url}`)

**Use Cases:**
- Generate link previews for messaging apps and social platforms
- Content curation and aggregation tools
- SEO analysis and monitoring
- Social media management platforms

**Key Features:**
- OpenGraph tag extraction (og:title, og:description, og:image, etc.)
- Twitter Card metadata support
- Intelligent fallback extraction when metadata is missing
- JavaScript rendering for dynamic websites (full_render parameter)
- v3 smart defaults — `auto_proxy`, `auto_render`, and `retry` are on automatically
- Caching support for faster responses
- Proxy options for accessing restricted sites

**Response Format:**
```json
{
  "hybridGraph": {
    "title": "Page Title",
    "description": "Page description...",
    "image": "https://example.com/image.jpg",
    "url": "https://example.com",
    "site_name": "Example Site"
  },
  "openGraph": { ... },
  "htmlInferred": { ... }
}
```

### Screenshot API

Capture high-quality screenshots of any webpage programmatically.

**Endpoint:** `GET https://opengraph.io/api/3.0/screenshot/{encoded_url}` (v1.1 legacy also available at `/api/1.1/screenshot/{encoded_url}`)

**Use Cases:**
- Website monitoring and archiving
- Visual regression testing
- Thumbnail generation
- Social media previews
- Documentation and reporting

**Key Features:**
- Full-page or viewport capture
- Multiple device sizes (mobile, tablet, desktop)
- Custom viewport dimensions
- Quality and format options
- Fast CDN-cached delivery

**Parameters:**
- `full_page`: Capture entire scrollable page (true/false)
- `dimensions`: Predefined sizes (sm, md, lg, xl) or custom
- `quality`: Image quality (1-100)

### Web Scraper API

Fetch raw HTML from any website with full JavaScript rendering and proxy support.

**Endpoint:** `GET https://opengraph.io/api/3.0/scrape/{encoded_url}` (v1.1 legacy also available at `/api/1.1/scrape/{encoded_url}`)

**Use Cases:**
- Content aggregation
- Market research and competitive analysis
- Data validation
- SEO auditing
- Price monitoring

**Key Features:**
- Raw HTML retrieval
- Full JavaScript rendering
- Advanced proxy rotation (standard, premium, superior)
- Bot detection bypass
- Smart caching

**Parameters:**
- `full_render`: Enable JavaScript rendering (true/false)
- `use_proxy`: Use standard proxy (true/false)
- `use_premium`: Use residential proxy (true/false)
- `use_superior`: Use mobile proxy (true/false)
- `cache_ok`: Allow cached results (true/false)

### Content Extraction API

Extract specific HTML elements (titles, headers, paragraphs) or named CSS selectors in a structured format.

**Endpoint:** `POST https://opengraph.io/api/3.0/extract` (JSON body; v1.1 legacy `GET /api/1.1/extract/{encoded_url}` still available)

**Use Cases:**
- Content analysis and summarization
- AI/LLM data pipelines
- SEO content auditing
- Research and data collection
- Automated reporting

**Key Features:**
- Tag-based extraction (`html_elements`) or named CSS-selector extraction (`selectors`)
- Structured `data` object keyed by your selector labels, plus a `concatenatedText` string
- JavaScript rendering support
- v3 smart defaults — `auto_proxy`, `auto_render`, and `retry` are on automatically
- Multi-proxy architecture

**Parameters (v3, JSON body):**
- `site` (required): Target URL
- `html_elements`: Array of tag names (e.g., `["title","h1","h2","h3","p"]`)
- `selectors`: CSS selector map (e.g., `{ "price": ".price-box .price" }`)
- `full_render`: Enable JavaScript rendering
- `accept_lang`: Specify language preference

**Response Format:**
```json
{
  "concatenatedText": "Main Heading Paragraph content...",
  "data": { "price": "$19.99" }
}
```

### Markdown API

Convert any URL's HTML into clean, readable Markdown with navigation, ads, and boilerplate stripped by default.

**Endpoint:** `GET https://opengraph.io/api/3.0/markdown/{encoded_url}` (v1.1 legacy also available at `/api/1.1/markdown/{encoded_url}`)

**Use Cases:**
- RAG pipelines and LLM ingestion
- Content migration and summarization
- Documentation aggregation
- Feeding page content to AI agents

**Key Features:**
- Strips nav/sidebars/footers by default (`only_main_content`)
- `include_tags` / `exclude_tags` to fine-tune which sections are kept
- v3 smart defaults — `auto_proxy`, `auto_render`, and `retry` are on automatically
- Note: for JavaScript-heavy/SPA pages, pass `full_render: true` explicitly — `auto_render` does not apply to this endpoint

**Response Format:**
```json
{
  "markdown": "# Example Article\n\nThis is the main content..."
}
```

### Query API (AI-Powered)

Ask natural-language questions about any webpage and receive structured responses.

**Endpoint:** `GET/POST https://opengraph.io/api/1.1/query/{encoded_url}`

**Use Cases:**
- Extract specific data points from any page without parsing HTML
- Build structured datasets from unstructured web content
- Answer questions about page content programmatically
- Validate page content against expected schemas

**Key Features:**
- Natural-language query input
- Custom response structure via JSON schema
- Two model tiers: nano (100 credits) and mini (200 credits)
- Works with JavaScript-rendered pages

**Parameters:**
- `query` (required): The question to ask about the page
- `responseStructure` (optional): JSON object describing desired response format

**Example Request (POST):**
```json
POST /api/1.1/query/https://example.com
{
  "query": "Extract all product names on the page.",
  "responseStructure": { "products": ["name"] }
}
```

### Dynamic OG Image API

Generate Open Graph images dynamically using templates and URL parameters.

**Endpoint:** `GET https://cdn.opengraph.io/thumbnail/{designId}/{imageUrl}/{title}/{siteText}/{ctaText}/image.png`

**Use Cases:**
- Blog post social images
- E-commerce product previews
- Documentation pages
- Event and webinar promotions
- Landing page A/B testing

**Key Features:**
- Template-based generation
- URL parameter customization
- Global CDN caching
- Works with any CMS
- No API calls needed - just construct a URL

### AI Image Generation

Generate AI-powered images via the MCP server or direct API.

**Image Types:**
- **Illustrations**: AI-generated artwork for hero images, marketing assets, blog covers
- **Diagrams**: Technical diagrams in Mermaid, D2, or Vega-Lite formats
- **Icons**: App icons with optional transparent backgrounds (256x256 to 1024x1024)
- **Social Cards**: OG images, Twitter cards, LinkedIn previews optimized for link unfurls
- **QR Codes**: Branded QR codes with AI-generated decorative backgrounds

**Key Features:**
- Platform-optimized sizes (Instagram, LinkedIn, YouTube, Twitter, Facebook, etc.)
- 13 style presets (github-dark, vercel, linear, stripe, etc.)
- 11 diagram templates (auth-flow, microservices, ci-cd, etc.)
- Brand color support via hex codes
- Iterative refinement without regenerating from scratch
- Export directly to local filesystem
- Three quality tiers: draft, standard, premium
- Transparent background support for icons

## Authentication

All API requests require an `app_id` parameter:

```
https://opengraph.io/api/1.1/site/{url}?app_id=YOUR_APP_ID
```

Get your free API key at: https://dashboard.opengraph.io/register

## Pricing

- **Free:** 100 requests/month, 1 concurrent request
- **Developer ($25/month):** 50,000 credits/month, 5 concurrent requests, 3 seats
- **Production ($100/month):** 250,000 credits/month, 25 concurrent requests, unlimited seats, 1 dedicated worker
- **Enterprise ($250/month):** 1,000,000 credits/month, 100 concurrent requests, unlimited seats, 2 dedicated workers
- **Pay as You Go ($25):** 40,000 credits, 5 concurrent requests

All plans include access to all API endpoints and MCP server tools.

**Credit Costs:**
| Service | Credits |
|---------|---------|
| Link Preview / Metadata | 1 |
| Web Scraper | 1 |
| Content Extraction | 1 |
| oEmbed | 10 |
| Screenshot | 20 (cached: 1) |
| AI Title/Description | 5 |
| AI Query (nano) | 100 |
| AI Query (mini) | 200 |
| AI Image Generation | varies |
| Dynamic OG Images | 5 |
| Full Render add-on | +10 |
| Basic Proxy add-on | +10 |
| Premium Proxy add-on | +20 |
| Superior Proxy add-on | +30 |
| Cached response (24hr) | 1 |

**Overage Rates:**
- Developer: $1.00 per 1,000 credits
- Production: $0.80 per 1,000 credits
- Enterprise: $0.50 per 1,000 credits

## SDKs and Libraries

Official and community libraries available for:
- Node.js
- PHP
- Ruby
- C#
- jQuery

Documentation: https://www.opengraph.io/languages

## Common Parameters

These parameters work across most endpoints:

| Parameter | Description |
|-----------|-------------|
| `app_id` | Your API key (required) |
| `cache_ok` | Allow cached results (default: true) |
| `max_cache_age` | Maximum cache age in seconds |
| `full_render` | Enable JavaScript rendering |
| `use_proxy` | Use standard proxy |
| `use_premium` | Use residential proxy |
| `use_superior` | Use mobile proxy |
| `accept_lang` | Preferred language |

## Rate Limits

Rate limits depend on your plan:
- Free: 1 concurrent request
- Developer: 5 concurrent requests
- Production: 25 concurrent requests
- Enterprise: 100 concurrent requests

## Support

- Documentation: https://www.opengraph.io/documentation
- Support: https://www.opengraph.io/support
- Email: support@opengraph.io

## Legal

- Terms of Service: https://www.opengraph.io/legal-terms-of-service
- Privacy Policy: https://www.opengraph.io/privacy
- Acceptable Use Policy: https://www.opengraph.io/legal-acceptable-use-policy