Notion: Create a page
Notion pages.postPage: arguments, response, policy and SDK examples.
← Pages operations · Get started
Operation notion.post_page
Provider route: POST /v1/pages. Alter supplies the connection’s credentials and routing.
Call through Alter
Section titled “Call through Alter”Install @alter-ai/sdk @alter-ai/notion with npm, or alter-sdk-notion with pip. Supply your connected customer’s grant ID and the arguments described below.
import { App } from "@alter-ai/sdk";import { NotionIntegration } from "@alter-ai/notion";
async function execute(input: Parameters<NotionIntegration["pages"]["postPage"]>[0]) { const app = new App({ apiKey: process.env.ALTER_API_KEY! }); try { const provider = new NotionIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! }); const call = await provider.pages.postPage(input); const result = await call.wait(); return result.bodyJson(); } finally { await app.close(); }}import osfrom alter_sdk import Appfrom alter_sdk_notion import NotionIntegration
async def execute(arguments): async with App(api_key=os.environ["ALTER_API_KEY"]) as app: provider = NotionIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]}) call = await provider.pages.post_page(arguments) result = await call.wait() return result.body_json()| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Additional keys: not allowed |
query | object | Optional | Additional keys: not allowed |
query.filter_properties | array | Optional | Property names or IDs to include in each page’s `properties` object. Other properties are left out. Repeat the parameter to pass more than one value, for example `filter_properties=title&filter_properties=Status`. Pages that aren’t in a data source always return only `title`. |
query.filter_properties[] | string | Each item | |
body | object | Required within parent | Additional keys: not allowed |
body.allow_async | boolean | Optional | Set to true to receive an async_task response for markdown page creation. Only supported when markdown is provided. |
body.children | array | Optional | Maximum items: 100 |
body.children[] | Model | Each item | Expand Create a page — request body — body content item |
body.content | array | Optional | Maximum items: 100 |
body.content[] | Model | Each item | Expand Create a page — request body — body content item |
body.cover | JSON | Optional | |
body.cover (anyOf 1) | Model | Alternative | Expand Create a database — request body — body cover |
body.cover (anyOf 2) | null | Alternative | |
body.icon | JSON | Optional | |
body.icon (anyOf 1) | Model | Alternative | Expand Create a database — request body — body icon |
body.icon (anyOf 2) | null | Alternative | |
body.markdown | string | Optional | Page content as Markdown, in the syntax set by `markdown_version`: Notion-flavored Markdown (`v2`, recommended) or enhanced markdown (`v1`, deprecated, the default on current Notion-Versions). Mutually exclusive with content/children. |
body.markdown_version | string | Optional | The Markdown syntax to use. `v2` is [Notion-flavored Markdown](/guides/data-apis/notion-flavored-markdown) and is recommended. `v1` is enhanced markdown. It’s deprecated. It’s the default on current Notion-Versions. The next Notion-Version rejects `v1` with a `400` `validation_error`. One of: v1, v2 |
body.notifications | Model | Optional | Expand Update page — request body — body notifications |
body.parent | JSON | Optional | |
body.parent (anyOf 1) | object | Alternative | Additional keys: not allowed |
body.parent (anyOf 1).page_id | string | Required within parent | |
body.parent (anyOf 1).type | string | Optional | Must equal: page_id |
body.parent (anyOf 2) | object | Alternative | Additional keys: not allowed |
body.parent (anyOf 2).database_id | string | Required within parent | |
body.parent (anyOf 2).type | string | Optional | Must equal: database_id |
body.parent (anyOf 3) | object | Alternative | Additional keys: not allowed |
body.parent (anyOf 3).data_source_id | string | Required within parent | |
body.parent (anyOf 3).type | string | Optional | Must equal: data_source_id |
body.parent (anyOf 4) | object | Alternative | Additional keys: not allowed |
body.parent (anyOf 4).type | string | Optional | Must equal: workspace |
body.parent (anyOf 4).workspace | boolean | Required within parent | Must equal: true |
body.position | Model | Optional | Expand Create a page — request body — body position |
body.properties | Model | Optional | Expand Update page — request body — body properties |
body.template | JSON | Optional | |
body.template (anyOf 1) | object | Alternative | |
body.template (anyOf 1).type | string | Required within parent | Must equal: none |
body.template (anyOf 2) | object | Alternative | |
body.template (anyOf 2).timezone | string | Optional | IANA timezone to use when resolving template variables like @now and @today (e.g. ‘America/New_York’). Defaults to the authorizing user’s timezone for public integrations, or UTC for internal integrations. |
body.template (anyOf 2).type | string | Required within parent | Must equal: default |
body.template (anyOf 3) | object | Alternative | |
body.template (anyOf 3).template_id | string | Required within parent | |
body.template (anyOf 3).timezone | string | Optional | IANA timezone to use when resolving template variables like @now and @today (e.g. ‘America/New_York’). Defaults to the authorizing user’s timezone for public integrations, or UTC for internal integrations. |
body.template (anyOf 3).type | string | Required within parent | Must equal: template_id |
Referenced models: Create a page — request body — body content item, Create a database — request body — body cover, Create a database — request body — body icon, Create a page — request body — body position, Update page — request body — body properties, Update page — request body — body notifications
Response
Section titled “Response”Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | JSON | Root | |
$ (anyOf 1) | JSON | Alternative | |
$ (anyOf 1) (anyOf 1) | Model | Alternative | Expand Update page — response body — object page — page Object Response |
$ (anyOf 1) (anyOf 2) | Model | Alternative | Expand Update page — response body — object page — partial Page Object Response |
$ (anyOf 2) | object | Alternative | Additional keys: allowed |
$ (anyOf 2).created_time | string | Required within parent | Format: date-time |
$ (anyOf 2).id | string | Required within parent | Minimum length: 1 |
$ (anyOf 2).object | string | Required within parent | Must equal: async_task |
$ (anyOf 2).operation | JSON | Required within parent | |
$ (anyOf 2).operation (anyOf 1) | object | Alternative | Additional keys: allowed |
$ (anyOf 2).operation (anyOf 1).name | string | Required within parent | Known values: POST /v1/pages, PATCH /v1/pages/:page_id/markdown |
$ (anyOf 2).operation (anyOf 1).surface | string | Required within parent | Must equal: rest |
$ (anyOf 2).operation (anyOf 2) | object | Alternative | Additional keys: allowed |
$ (anyOf 2).operation (anyOf 2).name | string | Required within parent | Known values: create_pages, update_page |
$ (anyOf 2).operation (anyOf 2).surface | string | Required within parent | Must equal: mcp |
$ (anyOf 2).poll_after_seconds | JSON | Required within parent | |
$ (anyOf 2).poll_after_seconds (anyOf 1) | integer | Alternative | Minimum: 0 |
$ (anyOf 2).poll_after_seconds (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
$ (anyOf 2).status | string | Required within parent | Known values: queued, running, retrying |
$ (anyOf 2).status_url | string | Required within parent | Minimum length: 1 |
Referenced models: Update page — response body — object page — page Object Response, Update page — response body — object page — partial Page Object Response
Schemas
Section titled “Schemas”141 more schemas are linked from the tables above, on the schema pages.
Update page — response body — object page — page Object Response
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Additional keys: allowed |
cover | JSON | Required within parent | Page cover image. |
cover (anyOf 1) | Model | Alternative | Expand Update page — response body — object page cover value |
cover (anyOf 2) | null | Alternative | |
created_by | Model | Required within parent | Expand Update page — response body — object page created by User who created the page. |
created_time | string | Required within parent | Date and time when this page was created. Format: date-time |
icon | JSON | Required within parent | Page icon. |
icon (anyOf 1) | Model | Alternative | Expand Get agent — response body — icon value |
icon (anyOf 2) | null | Alternative | |
id | string | Required within parent | The ID of the page. Format: uuid |
in_trash | boolean | Required within parent | Whether the page is in trash. |
is_archived | boolean | Required within parent | Whether the page has been archived. |
is_locked | boolean | Required within parent | Whether the page is locked from editing in the Notion app UI. |
last_edited_by | Model | Required within parent | Expand Update page — response body — object page created by User who last edited the page. |
last_edited_time | string | Required within parent | Date and time when this page was last edited. Format: date-time |
object | string | Required within parent | The page object type name. Must equal: page |
parent | Model | Required within parent | Expand Update page — response body — object page parent Information about the page's parent. |
properties | object | Required within parent | Property values of this page. Additional keys: see wildcard field |
properties.* | Model | Additional keys | Expand Update page — response body — object page properties value |
public_url | JSON | Required within parent | The public URL of the Notion page, if it has been published to the web. |
public_url (anyOf 1) | string | Alternative | |
public_url (anyOf 2) | null | Alternative | |
url | string | Required within parent | The URL of the Notion page. |
Referenced models: Update page — response body — object page cover value, Get agent — response body — icon value, Update page — response body — object page properties value, Update page — response body — object page parent, Update page — response body — object page created by
Update page — response body — object page — partial Page Object Response
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Additional keys: allowed |
id | string | Required within parent | The ID of the page. Format: uuid |
object | string | Required within parent | The page object type name. Must equal: page |
Create a database — request body — body cover
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | JSON | Root | |
$ (oneOf 1) | Model | Alternative | Expand Create a database — request body — body cover File Upload |
$ (oneOf 2) | Model | Alternative | Expand Create a database — request body — body cover External |
Referenced models: Create a database — request body — body cover External, Create a database — request body — body cover File Upload
Create a database — request body — body icon
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | JSON | Root | |
$ (oneOf 1) | Model | Alternative | Expand Create a database — request body — body icon File Upload |
$ (oneOf 2) | Model | Alternative | Expand Create a database — request body — body icon Emoji |
$ (oneOf 3) | Model | Alternative | Expand Create a database — request body — body icon External |
$ (oneOf 4) | Model | Alternative | Expand Create a database — request body — body icon Custom Emoji |
$ (oneOf 5) | Model | Alternative | Expand Create a database — request body — body icon Icon |
Referenced models: Create a database — request body — body icon Custom Emoji, Create a database — request body — body icon Emoji, Create a database — request body — body icon External, Create a database — request body — body icon File Upload, Create a database — request body — body icon Icon
Create a page — request body — body position
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | JSON | Root | |
$ (anyOf 1) | object | Alternative | |
$ (anyOf 1).after_block | object | Required within parent | |
$ (anyOf 1).after_block.id | string | Required within parent | |
$ (anyOf 1).type | string | Required within parent | Must equal: after_block |
$ (anyOf 2) | object | Alternative | |
$ (anyOf 2).type | string | Required within parent | Must equal: page_start |
$ (anyOf 3) | object | Alternative | |
$ (anyOf 3).type | string | Required within parent | Must equal: page_end |
Update page — request body — body notifications
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Controls the notifications Notion sends people about this change. Set mode to "silent" to skip page update notifications, @mention notifications, and notifications to people added to a Person property, or "default" to use the standard behavior. Database automations, reminders, and connection webhooks still work as usual. Page history, page activity, and workspace audit logs still record the change. |
mode | string | Required within parent | One of: default, silent |
Update page — response body — object page cover value
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | JSON | Root | |
$ (anyOf 1) | Model | Alternative | Expand Update page — response body — object page cover value File |
$ (anyOf 2) | Model | Alternative | Expand Update page — response body — object page cover value External |
Referenced models: Update page — response body — object page cover value External, Update page — response body — object page cover value File
Get agent — response body — icon value
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | JSON | Root | |
$ (anyOf 1) | Model | Alternative | Expand Get agent — response body — icon value Emoji |
$ (anyOf 2) | Model | Alternative | Expand Get agent — response body — icon value File |
$ (anyOf 3) | Model | Alternative | Expand Get agent — response body — icon value External |
$ (anyOf 4) | Model | Alternative | Expand Get agent — response body — icon value Custom Emoji |
$ (anyOf 5) | Model | Alternative | Expand Get agent — response body — icon value Icon |
Referenced models: Get agent — response body — icon value Custom Emoji, Get agent — response body — icon value Emoji, Get agent — response body — icon value External, Get agent — response body — icon value File, Get agent — response body — icon value Icon
Update page — response body — object page created by
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Additional keys: allowed |
id | string | Required within parent | Format: uuid |
object | string | Required within parent | Always `user` Must equal: user |
Update a block — request body — body value type tab tab
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Additional keys: not allowed |
Policy, approvals and errors
Section titled “Policy, approvals and errors”SDK function policy ID: notion.post_page. Catalog operation: post_page. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.
Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.
Pinned headers: {"Notion-Version": "2026-03-11"}