Markdown API

Endpoint

GET https://opengraph.io/api/3.0/markdown/{encoded_url}?app_id=YOUR_APP_ID

Parameters

Path Parameters

Query Parameters

Grouped by what you are trying to do. If all you want is the page as Markdown, you only need app_id — everything else is optional.

Getting the page

Choosing what comes back

By default the response body is the Markdown. Ask for format=json and you get an envelope instead, where each section can be switched off if you do not use it.

Splitting the page for embedding

Set chunking=true and the page comes back already split into pieces sized for a vector database. Each piece carries the heading path it came from, so a chunk retrieved on its own still knows which section of the page it belongs to — which a naive character split cannot tell you.

Finding the part that answers a question

Send a question with the request and you get back only the passages that match it, each with a relevance score, instead of the whole page. This is keyword matching against the words on the page — it is fast and free, and it makes no model call. It is not embedding-based semantic search, and it is a different feature from the Query API, which asks a model to answer in prose.

Getting the page's structure

Ask for the shape of the page rather than its prose — useful for crawling, auditing, or building a table of contents without parsing the HTML yourself.

Controlling the fetch

These behave the same way across our endpoints. On v3 the first three are on by default, so most callers never set them.

Checking the page for prompt injection

Web pages can contain text written to hijack a model that reads them. Turn this on and the response tells you what was found and how risky it looks.

Response Headers

Example Request

# Default: plain text/markdown body
curl "https://opengraph.io/api/3.0/markdown/https%3A%2F%2Fen.wikipedia.org%2Fwiki%2FWeb_scraping?app_id=YOUR_APP_ID"

# format=json: structured envelope with metadata, usage, and debug info
curl "https://opengraph.io/api/3.0/markdown/https%3A%2F%2Fen.wikipedia.org%2Fwiki%2FWeb_scraping?app_id=YOUR_APP_ID&format=json"

# Split into chunks ready to embed, each keeping its heading path
curl "https://opengraph.io/api/3.0/markdown/https%3A%2F%2Fen.wikipedia.org%2Fwiki%2FWeb_scraping?app_id=YOUR_APP_ID&format=json&chunking=true&chunk_size=1200&chunk_overlap=100"

# Return only the passages that answer a question
curl -G "https://opengraph.io/api/3.0/markdown/https%3A%2F%2Fen.wikipedia.org%2Fwiki%2FWeb_scraping?app_id=YOUR_APP_ID&format=json" \
  --data-urlencode "query=legal issues around scraping" \
  -d query_top_k=3

# Structure only — no document body
curl "https://opengraph.io/api/3.0/markdown/https%3A%2F%2Fen.wikipedia.org%2Fwiki%2FWeb_scraping?app_id=YOUR_APP_ID&format=json&include_markdown=false&include_headings=true&include_links=true"

Raw Markdown Response (default)

When format=markdown (default), the response body is unchanged from previous versions of this endpoint — plain text with Content-Type: text/markdown. The headers below are additive.

Content-Type: text/markdown
X-Request-Id: 3f1a9c2e-8b4d-4e7a-9c1a-2d6f8e0b5a7c
X-BILLING-REQUESTS: 1
X-Markdown-Character-Count: 4820
# Only present when max_chars was exceeded:
X-Markdown-Truncated: true
X-Markdown-Truncation-Reason: max_chars_exceeded
# Only present when ai_sanitize=true:
X-AI-Safety-Score: 0.12
X-AI-Safety-Level: low

JSON Response (format=json)

When format=json, the response is a structured envelope. ai_safety is only present when ai_sanitize=true was requested — it's omitted entirely otherwise, rather than being sent as null.

{
  "markdown": "# Example Article\n\nMain content here...",
  "metadata": {
    "title": "Example Article Title",
    "description": "A short description from the page's meta tags.",
    "canonical_url": "https://example.com/article",
    "site_name": "Example Site",
    "image": "https://example.com/og-image.jpg",
    "language": "en",
    "final_url": "https://example.com/article"
  },
  "usage": {
    "character_count": 4820,
    "estimated_token_count": 1205,
    "truncated": false,
    "truncation_reason": null,
    "max_chars": null
  },
  "debug": {
    "full_render_used": false,
    "auto_render_triggered": false,
    "proxy_used": null,
    "retry_used": false,
    "retry_attempts": 1,
    "final_status_code": 200
  },
  "request_id": "3f1a9c2e-8b4d-4e7a-9c1a-2d6f8e0b5a7c"
}

Adding ai_sanitize=true attaches an ai_safety object:

"ai_safety": {
  "risk_score": 0.12,
  "risk_level": "low",
  "action_taken": "sanitize",
  "signals": [],
  "recommendation": "No action needed."
}

Chunks (chunking=true)

Each chunk carries the heading path it came from, its own counts, and its position in the document — so a chunk retrieved later still knows where it sat on the page. usage.chunk_count is how many the page produced in total, which can be larger than the number returned.

"chunks": [
  {
    "index": 0,
    "text": "Install the client with your package manager...",
    "heading_path": ["Getting Started", "Installation"],
    "character_count": 1840,
    "estimated_token_count": 460,
    "start_offset": 0,
    "end_offset": 1840,
    "overlap_character_count": 0,
    "split_mid_block": false
  }
],
"usage": {
  "chunk_count": 12,
  "chunks_truncated": false
}

Matched passages (query=...)

Sending a query returns the same chunk shape with a relevance_score from 0 to 1 added, ordered best match first. The index stays the chunk's position in the page, not its rank — so passage 1 in the list may be chunk 7 of the document.

"chunks": [
  {
    "index": 7,
    "text": "Every plan includes a monthly credit allowance...",
    "heading_path": ["Pricing", "Usage limits"],
    "relevance_score": 0.87,
    "character_count": 920,
    "estimated_token_count": 230
  }
]

Structure (include_headings / include_links / include_images)

Returned from the same fetch that produced the Markdown — no second request, no parsing the HTML yourself. Long lists are capped, and the response says so.

"headings": [
  { "level": 1, "text": "Getting Started" },
  { "level": 2, "text": "Installation" }
],
"links": [
  {
    "url": "https://example.com/docs/install",
    "text": "installation guide",
    "rel": null,
    "internal": true
  }
],
"images": [
  { "url": "https://example.com/diagram.png", "alt": "Architecture diagram" }
],
"tables_detected": 2,
"code_blocks_detected": 5

When part of the response can't be produced

Splitting, ranking and structure extraction are optional steps. If one of them fails, the request does not fail — you still get the document, and usage tells you which step did not finish. Check these if a section you asked for is missing.

Structured Errors

Every error response — regardless of format — is JSON with an error object and the same request_id that was returned in X-Request-Id. Check error.code, not the HTTP status alone, since several distinct failure modes can share a status code.

{
  "error": {
    "code": -2201,
    "message": "Invalid max_chars value. Must be a positive integer."
  },
  "request_id": "3f1a9c2e-8b4d-4e7a-9c1a-2d6f8e0b5a7c"
}

Use Cases

• LLM and AI content ingestion pipelines
• RAG (Retrieval-Augmented Generation) data preparation
• Content migration between platforms
• Documentation scraping and archival
• Clean text extraction for NLP processing
• Safe ingestion of untrusted external pages with AI safety sanitization

Related