Notion

Description

Integration with the Notion REST API (base URL https://api.notion.com/v1). Six nodes cover the day-to-day work of a workspace: create a page (as a database row or as a subpage), read a page by its id, update its properties or archive it, query a database with filters and sorting, append content blocks, and add a comment.

Authentication is handled through the credentials module (service type notion): a Bearer token plus the mandatory Notion-Version header, which every request sends automatically (default 2022-06-28).

Operations

Create Page Create a database row or a subpage.

Get Page Read a page by its id.

Update Page Update properties, archive or restore.

Query Database Filter and sort a database, get the rows.

Append Content Add blocks or a paragraph to a page.

Add Comment Post a comment on a page.

Configuration

Each node exposes only the fields it needs. This is the combined list across the six nodes:

Parameter	Type	Required	Description
credentials_id	credentials	Yes	Notion credential (provider `notion`)
database_id	text	Conditional	Database id — parent on Create Page, target on Query Database
parent_page_id	text	Conditional	Parent page id on Create Page, when the parent is not a database
page_id	text	Conditional	Page id — Get Page, Update Page and Add Comment
block_id	text	Conditional	Parent page or block id — Append Content
properties	json	Conditional	Typed page properties in Notion format
children	json	No	Array of content blocks (Notion format)
filter	json	No	Query filter (Notion format)
sorts	json	No	Sort array (Notion format)
page_size	number	No	Maximum results per query (1-100)
text	textarea	Conditional	Plain text — comment body, or paragraph to append
archived	text	No	`true` archives the page, `false` restores it

Credentials

Service type: notion. Stored in the servicecredentials table.

token: the Internal Integration Secret from notion.so/my-integrations. Required.
notion_version: value sent in the Notion-Version header (default: 2022-06-28). Optional.
timeout: request timeout in milliseconds (default: 20000). Optional.

The Test button calls GET /users/me and returns the name of the integration.

Typed properties

In Notion, the properties of a page are typed objects that depend on the column type (title, rich_text, select, date, number, relation, and so on). That is why properties, filter and sorts are JSON fields in Notion’s own format. A title looks like this:

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

Output

{
  "nextModule": null,
  "data": {
    "object": "page",
    "id": "8b9c0d1e-2f3a-4b5c-6d7e-8f9a0b1c2d3e",
    "url": "https://www.notion.so/8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e",
    "properties": {
      "Name": { "title": [ { "text": { "content": "New lead" } } ] }
    }
  },
  "_meta": {
    "moduleVersion": "1.0.0",
    "success": true,
    "id": "8b9c0d1e-2f3a-4b5c-6d7e-8f9a0b1c2d3e",
    "url": "https://www.notion.so/8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e",
    "totalMs": 340
  }
}

Query Database is the exception: its data is the array of pages (results), and _meta carries count, has_more and next_cursor.

API Used

Notion REST API — https://developers.notion.com/reference/intro
Base URL: https://api.notion.com/v1
Endpoints: POST /pages, GET /pages/{id}, PATCH /pages/{id}, POST /databases/{id}/query, PATCH /blocks/{id}/children, POST /comments

Notes

The Notion-Version header is mandatory on every call. The nodes send 2022-06-28 unless the credential sets another value.
Text and id fields accept dynamic variables such as {{data.email}}, including inside the JSON fields.
Transient failures (timeout, 429 rate limit, 409 conflict, 5xx and network errors) are retried automatically up to 3 times with exponential backoff, honouring the Retry-After header.
Validation errors (400), authentication errors (401/403) and not found (404) are not retried: fix the JSON, the credential or the sharing settings.
Notion caps page_size at 100. Use next_cursor from _meta to walk long databases.
Default request timeout is 20 seconds.
For endpoints not covered by these six nodes (search, users, retrieve blocks…), use the HTTP node with the same credential values.

Jira, Asana, Trello and ClickUp — other work-management integrations.
Retry queue (DLQ) — how failed executions are retried.