Retrieve a page as markdown

Retrieve the content of a page rendered as enhanced markdown.

GET /v1/pages/{page_id}/markdown

TypeScript SDK

JavaScript

import { Client } from "@notionhq/client"

const notion = new Client({ auth: process.env.NOTION_API_KEY })

const response = await notion.pages.retrieveMarkdown({
  page_id: "b55c9c91-384d-452b-81db-d1ef79372b75"
})

console.log(response.markdown)

200

{
  "object": "<string>",
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "markdown": "<string>",
  "truncated": true,
  "unknown_block_ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ]
}

Use cases

Use this endpoint to retrieve the full content of a Notion page as enhanced markdown, instead of working with the block-based API. This is especially useful for agentic systems and developer tools that work natively with markdown.

The endpoint also accepts non-navigable block IDs returned in unknown_block_ids from a previous truncated response. Pass these IDs to fetch additional subtrees of a large page.

General behavior

Returns a page_markdown object containing the page content as an enhanced markdown string.

Requirements

Your connection must have read content capabilities on the target page in order to call this endpoint. To update your connection’s capabilities, navigate to the Developer portal, select your connection, open the Configuration tab, and scroll to the Capabilities section.

Attempting to call this endpoint without read content capabilities returns an HTTP response with a 403 status code.

Unknown blocks

Some blocks may appear as <unknown url="..." alt="..."/> tags in the markdown output. This happens when:

• Truncation: The page exceeds the record limit (approximately 20,000 blocks) and some blocks could not be loaded.
• Permissions: The page contains child pages or other content that is not shared with the connection.
• Unsupported block types: Certain block types (such as bookmarks, embeds, and link previews) are not yet supported in the markdown format.

When truncation or permissions cause unknown blocks, the truncated field is set to true and the unknown_block_ids array contains the affected block IDs.

You can attempt to fetch unloaded blocks by passing their IDs back to this same endpoint as the page_id path parameter. Blocks that are unknown due to permissions will return a 404 error since the connection does not have access.

The unknown_block_ids array does not distinguish between truncated and inaccessible blocks. Handle object_not_found errors gracefully when re-fetching unknown block IDs.

For unsupported block types, use the block-based API to retrieve the full structured data.

Errors

Returns a 404 HTTP response if the page doesn’t exist, or if the connection doesn’t have access to the page.

Returns a 400 or 429 HTTP response if the request exceeds the request limits.

Each Public API endpoint can return several possible error codes. See the Error codes section of the Status codes documentation for more information.

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

Notion-Version · enum<string> · required

The API version to use for this request. The latest version is 2026-03-11.

Available options: 2026-03-11

Path Parameters

page_id · string · required

The ID of the page (or block) to retrieve as markdown. Non-navigable block IDs from truncated responses can be passed here to fetch their subtrees.

Query Parameters

include_transcript · boolean

Whether to include meeting note transcripts. Defaults to false. When true, full transcripts are included; when false, a placeholder with the meeting note URL is shown instead.

Response

200

application/json

object · string · required

The type of object, always 'page_markdown'.

Allowed value: "page_markdown"

id · string<uuid> · required

The ID of the page or block.

markdown · string · required

The page content rendered as enhanced Markdown.

truncated · boolean · required

Whether the content was truncated due to exceeding the record count limit.

unknown_block_ids · string<uuid>[] · required

Block IDs that could not be loaded (appeared as tags in the markdown). Pass these IDs back to this endpoint to fetch their content separately.

Maximum array length: 100