llms.txt
Compare with other sites' llms.txt files →# 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 29 tools: 7 web data tools, 4 AI image generation tools, and 18 Open Graph Audit, monitoring and Link Preview tools (sign in required) covering audits, recurring audits, change tracking against previous runs, and developer fix lists.
**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 Open Graph 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 Markdown, with optional chunking, question-matched passages and structure extraction. 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/3.0/query`. |
| **Get Brand Intelligence** | Builds a structured brand profile of a website from up to ten of its own pages: brand, identity (logos, icon, colors, fonts), products, audiences, positioning, messaging, voice, visual style and links. Maps to `/api/1.1/brand`. |
### Open Graph 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 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" }
}
```
### oEmbed API
Return oEmbed-formatted metadata for a URL — a simpler, standardized shape for embeds and link previews.
**Endpoint:** `GET https://opengraph.io/api/3.0/oembed/{encoded_url}` (v1.1 legacy also available at `/api/1.1/oembed/{encoded_url}`)
**Use Cases:**
- Rendering embeds in a CMS or editor that already speaks oEmbed
- Simpler link previews where full metadata is more than you need
- Drop-in support for tools expecting the oEmbed standard
**Key Features:**
- Standard oEmbed response shape
- Works against any URL, not only providers with an oEmbed endpoint
- v3 smart defaults — `auto_proxy`, `auto_render`, and `retry` are on automatically
### Markdown API
Convert any URL's HTML into clean, readable Markdown with navigation, ads, and boilerplate stripped by default. Optionally split the page into chunks for embedding, return only the passages matching a question, or extract its structure.
**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
- Preparing pages for a vector database without writing your own chunker
- Answering a question about a page without embedding it first
- Content migration and summarization
- Crawling and auditing page structure
- Feeding page content to AI agents
**Key Features:**
- Strips nav/sidebars/footers by default (`only_main_content`); `include_tags` / `exclude_tags` to fine-tune
- `format=json` returns an envelope; `include_*` parameters switch off any section you do not use
- Chunking (`chunking=true`) — each chunk carries its heading path, token/character counts and offsets
- Question matching (`query`) — returns only matching passages with a relevance score. Keyword-based, not embeddings; makes no model call. Distinct from the Query API
- Structure extraction (`include_headings` / `include_links` / `include_images`), plus table and code-block counts
- Character and token counts before and after cleanup; `max_chars` reports when it truncates
- Prompt-injection scanning (`ai_sanitize`) with a risk score
- v3 smart defaults — `auto_proxy`, `auto_render`, and `retry` are on automatically
- For JavaScript-heavy/SPA pages: `auto_render` can detect an app shell and re-fetch it rendered; `full_render: true` forces a render, and `wait_for_selector` / `scroll_to_bottom` / `load_more_selector` handle content that appears after load
- Optional steps fail soft — if chunking or structure extraction cannot complete, the document is still returned and `usage` says which step did not finish
**Response Format:**
```json
{
"markdown": "# Example Article\n\nThis is the main content...",
"metadata": { "title": "...", "language": "en", "canonical_url": "..." },
"usage": { "character_count": 4820, "estimated_token_count": 1205, "truncated": false },
"chunks": [
{ "index": 0, "text": "...", "heading_path": ["Getting Started"], "estimated_token_count": 460 }
],
"debug": { "full_render_used": false, "auto_render_triggered": false, "final_status_code": 200 },
"request_id": "3f1a9c2e-..."
}
```
### Embed API (oEmbed)
Turn any URL into embeddable HTML. Resolution walks three tiers: native oEmbed providers, then oEmbed discovery links published by the page, then a hosted fallback card generated from Open Graph metadata. Every public URL returns something renderable.
**Endpoint:** `GET https://opengraph.io/api/3.0/oembed?url={url}` (path-encoded form `/api/3.0/oembed/{encoded_url}` and v1.1 legacy also available)
**Use Cases:**
- Embedding user-submitted links in comments, posts, and messages
- CMS and publishing tools with a paste-a-URL embed flow
- Dashboards that render linked resources as visual cards
- AI agents citing sources as rich cards
**Key Features:**
- Both URL forms supported: `?url=` query parameter or path-encoded segment
- `source` field on every response: `native`, `discovery`, or `og_frame`
- `maxwidth` / `maxheight` sizing hints forwarded to all three tiers (`maxWidth` / `maxHeight` also accepted)
- `always_og_frame` to force the hosted card even when a native embed exists
- `theme` (light/dark/auto) and `template` (default/compact) for hosted card appearance
- Broken native providers degrade to the hosted card rather than failing the request
- Structured errors: `{ success: false, error: { code, message, stage, details } }`
**Parameters:**
- `url` (required): Target URL, as `?url=` or a path-encoded segment
- `maxwidth` / `maxheight` (optional): Sizing hints, positive integers
- `always_og_frame` (optional): Skip native resolution and return the hosted card
- `theme` (optional): `light`, `dark`, or `auto`
- `template` (optional): `default` or `compact`
**Response Format:**
```json
{
"type": "rich",
"source": "og_frame",
"provider_name": "Example",
"title": "How We Ship",
"width": 640,
"height": 360,
"html": "<iframe src=\"https://frames.opengraph.io/...\" />",
"embed_id": "a1b2c3d4"
}
```
**Product pages:** https://www.opengraph.io/products/embed-api (product overview), https://www.opengraph.io/products/oembed-api (oEmbed spec compatibility)
**Docs:** https://www.opengraph.io/docs/api/oembed
### Brand Intelligence API
Turn any website into structured brand context for your product or AI. The API analyzes the pages that describe the brand and returns one normalized response.
**Endpoint:** `GET/POST https://opengraph.io/api/1.1/brand/{encoded_url}`
**Parameters:**
- `format` (optional): `json` (default) or `markdown`
- `sections` (optional): object of boolean flags; set any of `brand`, `identity`, `products`, `audiences`, `positioning`, `messaging`, `voice`, `visual`, `links` to `false` to skip it
- `questions` (optional): up to 3 custom questions, each `{ key, question, type }`; answers return under `custom`
- `include_meta` (optional): adds `_meta` provenance (source pages, and a basis of observed, derived, or inferred per field)
- `cache_ok` (optional, query string only): `false` forces a fresh analysis; results are otherwise cached for 7 days
**Product page:** https://www.opengraph.io/products/brand-intelligence-api
**For AI context:** https://www.opengraph.io/products/brand-context-api (grounding LLMs and agents; turn off `identity`, `visual` and `links`, use `format=markdown`)
**For visual identity:** https://www.opengraph.io/products/brand-identity-api (logos, colors, fonts, visual style; keep only `identity` and `visual` on)
**For brand voice:** https://www.opengraph.io/products/brand-voice-api (tone, traits, formality, technicality and energy scores, do and avoid guidance; keep `voice` and `messaging` on, use `format=markdown` for prompts)
**For brand colors:** https://www.opengraph.io/products/brand-colors-api (`identity.colors`: up to six hex colors with primary, accent, background and text roles; keep only `identity` on)
**Try it free:** https://www.opengraph.io/brand-analyzer (Free Brand Analyzer: enter a website and see the full analysis as a readable report, no signup)
**For company logos:** https://www.opengraph.io/products/company-logo-api (logo files, inline SVG logo in `identity.logo_svg`, site icon; keep only `identity` on)
**Docs:** https://www.opengraph.io/docs/api/brand
### Query API (AI-Powered)
Ask natural-language questions about any webpage and receive structured responses.
**Endpoint:** `GET/POST https://opengraph.io/api/3.0/query/{encoded_url}` (v1.1 legacy also available at `/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/3.0/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/3.0/site/{url}?app_id=YOUR_APP_ID
```
Get your free API key at: https://dashboard.opengra