V2
Markdown Read and Write
Read page content as Markdown or replace page content with Markdown.
Markdown Read and Write
Use these endpoints when your integration works with full page content as Markdown instead of individual block objects.
GET /v2/pages/:page_id/content/markdown
| Item | Value |
|---|---|
| Method | GET |
| Path | /v2/pages/:page_id/content/markdown |
| Request body | None |
| Returns | Markdown payload |
| Scope | pages.read + blocks.read |
Permissions
Requires both pages.read and blocks.read.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
page_id |
string | Yes | Page ID. |
Response Example
{
"object": "markdown",
"page_id": "11111111-1111-4111-8111-111111111111",
"markdown": "# Launch Plan\n\nInitial release scope and schedule.",
"updated_time": "2026-04-09T09:30:00.000Z"
}
Behavior
- The endpoint serializes supported page content blocks into Markdown.
- Unsupported or non-textual blocks may be omitted or represented in a lossy Markdown form.
- Use block endpoints when you need exact block-level structure.
PUT /v2/pages/:page_id/content/markdown
| Item | Value |
|---|---|
| Method | PUT |
| Path | /v2/pages/:page_id/content/markdown |
| Request body | JSON |
| Returns | Updated page summary |
| Scope | pages.write + blocks.write |
Permissions
Requires both pages.write and blocks.write.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
page_id |
string | Yes | Page ID. |
markdown |
string | Yes | Markdown content that replaces the page content. |
Request Example
{
"markdown": "# Launch Plan\n\n- Confirm scope\n- Publish release notes"
}
Response Example
{
"object": "page",
"id": "11111111-1111-4111-8111-111111111111",
"updated_time": "2026-04-09T09:30:00.000Z"
}
Behavior
- This is a full content replacement for the page body.
- The endpoint parses supported Markdown into blocks.
- Unsupported Markdown constructs may be normalized to the closest supported block representation.
- Use this endpoint carefully when concurrent editors may be modifying the same page.
Errors
400 validation_error: missing or invalid Markdown payload.401 unauthorized: invalid or expired token.403 forbidden: missing required scopes or no access.404 not_found: page does not exist.