Notion

Overview

The Notion nodes connect your workflows to Notion through its REST API. Use them to automate your workspace: create a page (row) in a database when a lead comes in, query a database with filters, append content to a page, or leave a comment.

There are six nodes:

Node	Operation	HTTP method
Notion: Create page (notionCreatePage)	Create a page (database row or subpage)	POST /pages
Notion: Get page (notionGetPage)	Read a page by its id	GET /pages/{id}
Notion: Update page (notionUpdatePage)	Update properties / archive	PATCH /pages/{id}
Notion: Query database (notionQueryDatabase)	Query with filters and sorting	POST /databases/{id}/query
Notion: Append content (notionAppendBlocks)	Append blocks to a page	PATCH /blocks/{id}/children
Notion: Add comment (notionAddComment)	Add a comment	POST /comments

Credential

The nodes use a Notion credential. Create it in Credentials → Add → Notion with this field:

Field	Description
Integration token	The Internal Integration Secret, from notion.so/my-integrations. Never shown in logs.

Authentication is Bearer with the integration token. You can verify the credential with the Test button, which calls GET /users/me.

Share the resource with the integration

In Notion, an internal integration only sees what you explicitly share with it. Open the database or page in Notion → ··· menu → Add connections → pick your integration. Otherwise the API returns 404 (as if it didn’t exist) even with a valid token.

Important: typed properties

In Notion, a page’s properties are typed objects that depend on the column type (title, text, select, date, number, relation…). That’s why the properties, filter and sorts fields are passed as JSON in Notion’s API format. For example, the title:

{ "Name": { "title": [ { "text": { "content": "New lead" } } ] } }

Nodes

Notion: Create page (notionCreatePage)

Parameter	Type	Required	Description
credentials_id	credential	Yes	Notion credential
database_id	text	No*	Parent database id (the page is a row)
parent_page_id	text	No*	Parent page id (if not a database)
properties	JSON	Yes	Page properties (Notion format)
children	JSON	No	Initial content blocks

*You need one of database_id or parent_page_id. Output: the created page, with its id and url.

Notion: Get page (notionGetPage)

Parameter	Type	Required	Description
credentials_id	credential	Yes	Notion credential
page_id	text	Yes	Page id

Notion: Update page (notionUpdatePage)

Parameter	Type	Required	Description
credentials_id	credential	Yes	Notion credential
page_id	text	Yes	Page id
properties	JSON	No	Properties to update (Notion format)
archived	text	No	true to archive, false to restore

Notion: Query database (notionQueryDatabase)

Parameter	Type	Required	Description
credentials_id	credential	Yes	Notion credential
database_id	text	Yes	Database id
filter	JSON	No	Filter (Notion format)
sorts	JSON	No	Sorts (array, Notion format)
page_size	number	No	Max results (1-100)

Output: the array of pages (results) matching the query.

Notion: Append content (notionAppendBlocks)

Parameter	Type	Required	Description
credentials_id	credential	Yes	Notion credential
block_id	text	Yes	Parent page or block id
text	text	No	Plain text (creates a paragraph)
children	JSON	No	Content blocks (Notion format)

Pass children (custom blocks) or text (simple paragraph). If you give both, blocks win.

Notion: Add comment (notionAddComment)

Parameter	Type	Required	Description
credentials_id	credential	Yes	Notion credential
page_id	text	Yes	Page id
text	text	Yes	Comment text

Example

Create a row in a leads database from a form:

• Node: Notion: Create page
• database_id: 1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d
• properties:

{
  "Name":   { "title":  [ { "text": { "content": "{{data.customer}}" } } ] },
  "Email":  { "email": "{{data.email}}" },
  "Status": { "select": { "name": "New" } }
}

Output:

{
  "id": "8b9c0d1e-2f3a-4b5c-6d7e-8f9a0b1c2d3e",
  "url": "https://www.notion.so/8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e",
  "object": "page"
}

Error handling

Each node classifies errors so the engine knows whether a retry makes sense:

Situation	Retryable	What to do
Validation (400)	No	Notion returns the reason (e.g. unknown property or wrong type). Fix the JSON.
Not found (404)	No	The page/database doesn’t exist or isn’t shared with the integration. Share it and check the id.
Authentication (401/403)	No	Invalid token or no permission. Check the credential.
Conflict (409)	Yes	Temporary Notion conflict; retried automatically.
Server (500)	Yes	Temporary Notion error; retried.
Rate limit (429)	Yes	Notion’s Retry-After (~3 req/s) is honored and retried.
Network / Timeout	Yes	Transient issue; retried automatically.

Validation errors are not retried

A malformed JSON is not retried: fix the properties/filter and run again. You can see automatic retries in the Retry queue (DLQ) panel.

See also

• Jira (Atlassian), Asana and Trello — other work-management integrations.
• Retry queue (DLQ) — how failed executions are retried.
• HTTP node — for Notion endpoints not covered by these nodes (search, users, blocks…).