Skip to contents

Notion API client

Source: R/client.R
NotionClient.Rd

Main client for interacting with Notion API. This R6 class provides access to all Notion API endpoints through organised sub-objects.

Client Types

  • notion_client(): Create a synchronous client (blocks until requests complete)

  • async_notion_client(): Create an asynchronous client (non-blocking)

Both clients provide identical interfaces, with the async client inheriting all methods from synchronous client. The only difference is that async methods return promises instead of results directly.

Usage

notion_client(
  auth = NULL,
  base_url = getOption("notionapi.base_url"),
  version = getOption("notionapi.version"),
  timeout = 60000
)

async_notion_client(
  auth = NULL,
  base_url = getOption("notionapi.base_url"),
  version = getOption("notionapi.version"),
  timeout = 60000
)

Value

A Notion API client instance

Configuration fields

  • auth: Authentication token. Defaults to NOTION_TOKEN environment variable

  • base_url: Base URL for Notion API (defaults to getOption("notionapi.base_url"))

  • version: Notion API version (defaults to getOption("notionapi.version"))

  • timeout: Timeout for requests in milliseconds (defaults to 60000, or 60 seconds)

Endpoints

See also

Notion API documentation

Public fields

base_url

Base URL for Notion API

version

Notion API version

blocks

Blocks endpoint object

pages

Pages endpoint object

databases

Databases endpoint object

comments

Comments endpoint object

users

Users endpoint object

Methods

Public methods

Method new()

Initialise Notion Client

Usage

NotionClient$new(
  auth = NULL,
  base_url = "https://api.notion.com/v1/",
  version = getOption("notionapi.version"),
  timeout = 60000
)

Arguments

auth

Authentication token. Uses NOTION_TOKEN environment variable by default.

base_url

Character. Base URL for Notion API.

version

Character. Notion API version.

timeout

Numeric. Number of milliseconds to wait before timing out a request.

Method request()

Create a base httr2 request object for the Notion API.

This method is primarily for advanced users who want to make custom API calls or for debugging purposes. Most users should use the endpoint methods instead.

Usage

NotionClient$request()

Returns

httr2 request object

Method print()

Print basic details of Notion Client

Usage

NotionClient$print()

Method search()

Search all parent or child pages and databases shared with an integration

Usage

NotionClient$search(
  query = NULL,
  sort = NULL,
  filter = NULL,
  start_cursor = NULL,
  page_size = NULL
)

Arguments

query

Character. The search query string.

sort

Named list (JSON object). Sort condition to apply to the search results.

filter

List (JSON object). Filter condition to apply to the search results.

start_cursor

Character. For pagination. If provided, returns results starting from this cursor. If NULL, returns the first page of results.

page_size

Integer. Number of items to return per page (1-100). Defaults to 100.

Details

Endpoint documentation

Super class

notionapi::NotionClient -> AsyncNotionClient

Methods

Public methods

Inherited methods

Method new()

Initialise Async Notion Client

Usage

AsyncNotionClient$new(
  auth = NULL,
  base_url = "https://api.notion.com/v1/",
  version = getOption("notionapi.version"),
  timeout = 60000
)

Arguments

auth

Authentication token. Uses NOTION_TOKEN environment variable by default.

base_url

Character. Base URL for Notion API.

version

Character. Notion API version.

timeout

Numeric. Number of milliseconds to wait before timing out a request.

Method request()

Create a base httr2 request object for the Notion API.

This method is primarily for advanced users who want to make custom API calls or for debugging purposes. Most users should use the endpoint methods instead.

Usage

AsyncNotionClient$request()

Returns

httr2 request object

Method print()

Print basic details of Notion Client

Usage

AsyncNotionClient$print()

Examples

# ----- Create a Notion client with default configuration
notion <- notion_client()

# search for pages and databases
notion$search(
  "Test Page 2025-07-15",
  page_size = 1,
  filter = list(
    value = "page",
    property = "object"
  ),
  sort = list(
    direction = "descending",
    timestamp = "last_edited_time"
  )
)
#> {
#>   "object": "list",
#>   "results": [
#>     {
#>       "object": "page",
#>       "id": "22f33ea0-c1e4-80b9-9c77-d1ab72aedff9",
#>       "created_time": "2025-07-13T12:29:00.000Z",
#>       "last_edited_time": "2025-07-23T05:00:00.000Z",
#>       "created_by": {
#>         "object": "user",
#>         "id": "fda12729-108d-4eb5-bbfb-a8f0886794d1"
#>       },
#>       "last_edited_by": {
#>         "object": "user",
#>         "id": "6b786605-e456-4237-9c61-5efaff23c081"
#>       },
#>       "cover": {},
#>       "icon": {
#>         "type": "emoji",
#>         "emoji": "#️⃣"
#>       },
#>       "parent": {
#>         "type": "block_id",
#>         "block_id": "21e33ea0-c1e4-8014-963b-cc5ecf889b84"
#>       },
#>       "archived": false,
#>       "in_trash": false,
#>       "properties": {
#>         "title": {
#>           "id": "title",
#>           "type": "title",
#>           "title": [
#>             {
#>               "type": "text",
#>               "text": {
#>                 "content": "Test Page Parent",
#>                 "link": {}
#>               },
#>               "annotations": {
#>                 "bold": false,
#>                 "italic": false,
#>                 "strikethrough": false,
#>                 "underline": false,
#>                 "code": false,
#>                 "color": "default"
#>               },
#>               "plain_text": "Test Page Parent",
#>               "href": {}
#>             }
#>           ]
#>         }
#>       },
#>       "url": "https://www.notion.so/Test-Page-Parent-22f33ea0c1e480b99c77d1ab72aedff9",
#>       "public_url": {}
#>     }
#>   ],
#>   "next_cursor": "47d65dc1-baca-4120-a969-9678e7302f99",
#>   "has_more": true,
#>   "type": "page_or_database",
#>   "page_or_database": {},
#>   "request_id": "9f78f94e-8e09-4b47-b652-f25b8afc34b3"
#> } 

# ----- Async client
if (FALSE) { # \dontrun{
library(promises)
async_notion <- async_notion_client()

# Start multiple requests simultaneously (non-blocking)
p1 <- async_notion$search(
  query = "Testing",
  page_size = 1
)

p2 <- async_notion$users$me()

# Returns a promise object, not particularly useful on its own
p1
p2

# Use promise chaining functions to process results as they complete
p1 %...>%
  print()

p2 %...>%
  print()

# See the [promises package documentation](https://rstudio.github.io/promises/)
# for more information on working with promises
} # }