# OpenGraph.io — Full Reference for AI Agents

> This is the full, flattened reference for OpenGraph.io. For a shorter index, see /llms.txt. For machine-readable manifests, see /.well-known/agents.json and /.well-known/mcp.json.

## About

OpenGraph.io is a comprehensive suite of web data extraction and AI-powered APIs. Its services help developers and AI agents 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 a hosted MCP server.

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

## Discovery surface for agents

- `/llms.txt` — short index (this file's companion)
- `/llms-full.txt` — this file
- `/.well-known/agents.json` — REST API metadata: servers, auth, capability list, MCP pointer
- `/.well-known/mcp.json` — MCP server metadata: endpoints, auth, full tool catalog, per-client configs
- `/robots.txt` — points crawlers and agent orchestrators at all of the above

## 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.

### Connecting

**Recommended — hosted, sign in with your account (no App ID required):**
```json
{
  "mcpServers": {
    "opengraph": {
      "url": "https://mcp.opengraph.io/mcp"
    }
  }
}
```
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 — an `x-app-id` header alone is not sufficient for those six tools, since they bill against your organization's Site Audit plan rather than a single API key.

**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 dependency on the hosted endpoint):**
```json
{
  "mcpServers": {
    "opengraph": {
      "command": "npx",
      "args": ["-y", "opengraph-io-mcp"],
      "env": { "OPENGRAPH_APP_ID": "YOUR_OPENGRAPH_APP_ID" }
    }
  }
}
```

**Claude Code (CLI):**
```bash
claude mcp add --transport http opengraph https://mcp.opengraph.io/mcp
```

**Claude Desktop:** does not support adding remote MCP servers via its config file — add it through **Settings -> Connectors -> Add custom connector**, pasting `https://mcp.opengraph.io/mcp` as the URL.

**VS Code (`.vscode/mcp.json`):**
```json
{
  "servers": {
    "opengraph": { "type": "http", "url": "https://mcp.opengraph.io/mcp" }
  }
}
```

**Zed (`~/.config/zed/settings.json`)** uses `context_servers` instead of `mcpServers`:
```json
{
  "context_servers": {
    "opengraph": { "transport": "http", "url": "https://mcp.opengraph.io/mcp" }
  }
}
```

Full copy-paste configs for every supported client: https://www.opengraph.io/docs/mcp/install
Auth details: https://www.opengraph.io/docs/mcp/authentication

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

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

### Web Data Tools (6) — require `app_id` or OAuth sign-in

Default to the current **v3** API, which enables smarter rendering and proxy handling automatically.

| Tool | Maps to | Description |
|------|---------|-------------|
| `getOgData` | `GET /api/3.0/site` | Fetches Open Graph metadata, Twitter Cards, and hybrid social preview data from a URL. |
| `getOgScrapeData` | `GET /api/3.0/scrape` | Scrapes raw HTML content from a URL with JavaScript rendering and proxy support. |
| `getOgScreenshot` | `GET /api/3.0/screenshot` | Captures a screenshot of a webpage with configurable viewport sizes, full-page capture, and dark mode. |
| `getOgMarkdown` | `GET /api/3.0/markdown` | Converts a URL's HTML into clean, readable Markdown with boilerplate stripped. Note: `auto_render` does NOT apply to this pipeline — pass `full_render: true` explicitly for JS-heavy/SPA pages. |
| `getOgExtract` | `POST /api/3.0/extract` | Extracts specific HTML elements, by tag name (`html_elements`) or named CSS selectors (`selectors`), into structured data. |
| `getOgQuery` | `GET/POST /api/1.1/query` | Asks a natural-language question about a page and returns a structured, AI-generated answer. Costs 100 credits (nano model) or 200 credits (mini model). |

### Site Audit & Link Preview Tools (6) — OAuth sign-in required

These six tools bill against your organization's Site Audit plan and are **not** available with an `x-app-id` API key alone.

| Tool | Description |
|------|-------------|
| `discoverSiteUrls` | Crawls a domain and its sitemap, returning every page found grouped by depth, plus your remaining monthly audit quota. |
| `startSiteAudit` | Kicks off an async, multi-page SEO/social audit for the pages you choose (or crawls the domain itself if discovery is skipped). 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 with top priorities, 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. |

A full site audit is a 4-step flow: `discoverSiteUrls` -> `startSiteAudit` -> poll `getSiteAuditStatus` -> `getSiteAuditReport`. If you already know which pages you want audited, you can skip discovery and pass URLs directly to `startSiteAudit`.

More detail: https://www.opengraph.io/docs/mcp/site-audit-link-preview

### Image Generation Tools (4) — `app_id`/OAuth optional but recommended for billing attribution

| Tool | Description |
|------|-------------|
| `generateImage` | Creates images from text prompts: illustrations, diagrams (Mermaid/D2/Vega-Lite), icons, social cards, QR codes. |
| `iterateImage` | Refines and modifies an existing generated image without regenerating from scratch. |
| `exportImageAsset` | Saves a generated image to the local filesystem (stdio mode) or returns it as base64. |
| `inspectImageSession` | Reviews generation history and retrieves asset metadata for a session. |

**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

More detail: https://www.opengraph.io/docs/mcp/image-generation

## REST API Reference

### Link Preview API (Site Unfurling)

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

Extract OpenGraph metadata, Twitter Cards, and HTML meta tags from any URL to create rich link previews. v3 smart defaults (`auto_proxy`, `auto_render`, `retry`) are on automatically.

Response shape:
```json
{
  "hybridGraph": { "title": "...", "description": "...", "image": "...", "url": "...", "site_name": "..." },
  "openGraph": { "...": "raw OG tags" },
  "htmlInferred": { "...": "HTML fallback extraction" }
}
```
Always read `hybridGraph` as the best-of-all-sources merge.

### Screenshot API

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

Parameters: `full_page` (capture entire scrollable page), `dimensions` (sm/md/lg/xl or custom), `quality` (1-100).

### Web Scraper API

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

Parameters: `full_render`, `use_proxy`, `use_premium`, `use_superior`, `cache_ok`.

### Content Extraction API

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

Body parameters: `site` (required), `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`, `accept_lang`.

Response shape:
```json
{ "concatenatedText": "Main Heading Paragraph content...", "data": { "price": "$19.99" } }
```
`concatenatedText` is always returned; `data` is only present when `selectors` was used.

### Markdown API

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

Strips nav/sidebars/footers by default (`only_main_content`); use `include_tags`/`exclude_tags` to fine-tune. For JS-heavy/SPA pages, pass `full_render: true` explicitly — `auto_render` does not apply here.

### Query API (AI-powered)

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

Parameters: `query` (required, the natural-language question), `responseStructure` (optional JSON schema for the response shape). Two model tiers: nano (100 credits) and mini (200 credits).

### Dynamic OG Image API

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

Template-based, no API call needed — just construct the URL.

## Fetch parameters available on most REST/MCP data tools

| Parameter | Description |
|-----------|-------------|
| `app_id` | Your API key, required on every REST call (query param) |
| `cache_ok` | Allow cached results (default: true) |
| `max_cache_age` | Maximum cache age in seconds |
| `auto_render` | v3 default: automatically detects JS-heavy pages and re-renders with a browser. Does not apply to the Markdown pipeline. |
| `full_render` | Force browser rendering on every request; use when `auto_render` isn't sufficient, or always for `getOgMarkdown`/the Markdown API on SPAs |
| `use_proxy` | Use standard proxy tier |
| `use_premium` | Use residential proxy tier |
| `use_superior` | Use mobile proxy tier |
| `retry` | Automatically retry failed requests with escalating proxy tiers; on by default on v3 |
| `max_retries` | Maximum retry attempts, 1-4 (default 4) |
| `retry_escalate` | Escalate proxy tier on each retry attempt (default true) |
| `accept_lang` | Preferred language for the target page |

## Authentication

All REST requests require an `app_id` query parameter:
```
https://opengraph.io/api/3.0/site/{url}?app_id=YOUR_APP_ID
```
Get a free API key: https://dashboard.opengraph.io/register

MCP has two options: sign in with your OpenGraph.io account (OAuth, required for Site Audit & Link Preview tools), or pass a static `app_id`/`x-app-id` (works for web-data and image-generation tools only). See https://www.opengraph.io/docs/mcp/authentication.

## 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: Developer $1.00/1,000 credits, Production $0.80/1,000 credits, Enterprise $0.50/1,000 credits.

## SDKs

Node.js, PHP, Ruby, C#, jQuery. Documentation: https://www.opengraph.io/languages

## Rate limits

Free: 1 concurrent request. Developer: 5. Production: 25. Enterprise: 100.

## Troubleshooting (MCP)

- Tools not appearing: fully restart the client (quit and reopen, not just reload); verify the config key is `mcpServers` (`context_servers` for Zed); validate JSON syntax.
- Browser doesn't open to sign in: remove and re-add the server entry, restart the client, and confirm `https://mcp.opengraph.io/mcp` is reachable (no VPN/firewall blocking it).
- "Invalid App ID": verify the App ID (not the API key or account email) at https://dashboard.opengraph.io, and confirm the header is spelled `x-app-id`.
- Full guide: https://www.opengraph.io/docs/mcp/troubleshooting

## Support

- Documentation: https://www.opengraph.io/docs
- 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