notionapi: Client for the 'Notion API'

Description

Enable programmatic interaction with 'Notion' pages, databases, blocks, comments, and users through the 'Notion API' https://developers.notion.com/. Provides both synchronous and asynchronous client interfaces for building workflows and automations that integrate with 'Notion' workspaces. Supports all 'Notion API' endpoints including content creation, data retrieval, and workspace management.

Author(s)

Maintainer: Brenwin Ang brenwinalj@gmail.com [copyright holder]

See Also

Useful links:

• https://brenwin1.github.io/notionapi/

• https://github.com/brenwin1/notionapi

• Report bugs at https://github.com/brenwin1/notionapi/issues

R6 Class for Blocks children endpoint

Description

Handle all block children operations in the Notion API

Note: Access this endpoint through the client instance, e.g., notion$blocks$children. Not to be instantiated directly.

Value

A list containing the parsed API response.

Methods

Public methods

• BlocksChildrenEndpoint$new()

• BlocksChildrenEndpoint$retrieve()

• BlocksChildrenEndpoint$append()

Method new()

Initialise block children endpoint. Not to be called directly, e.g., use notion$pages$children instead.

Usage

BlocksChildrenEndpoint$new(client)

Arguments

Method retrieve()

Retrieve a block's children

Usage

BlocksChildrenEndpoint$retrieve(block_id, start_cursor = NULL, page_size = 100)

Arguments

Details

Endpoint documentation

Method append()

Append block children

Usage

BlocksChildrenEndpoint$append(block_id, children, after = NULL)

Arguments

Details

Endpoint documentation

Examples

notion <- notion_client()

# ----- append children to a block

notion$blocks$children$append(
  block_id = "23933ea0-c1e4-81d6-a6f6-dd5b57ad4aba",
  children = list(
    # add a level 2 heading called "Test Heading"
    list(
      object = "block",
      heading_2 = list(
        rich_text = list(list(
          text = list(content = "Test Heading")
        ))
      )
    )
  )
)


# ----- retrieve children of a block

notion$blocks$children$retrieve("23933ea0-c1e4-81d6-a6f6-dd5b57ad4aba")


# ----- iterate through paginated results
## Not run: 
start_cursor <- NULL
has_more <- FALSE
resps <- list()
i <- 1

while (has_more) {
  resps[[i]] <- notion$blocks$children$retrieve(
    "2926b407e3c44b49a1830609abe6744f",
    start_cursor
  )
  has_more <- resps[[i]][["has_more"]]
  start_cursor <- resps[[i]][["next_cursor"]]
  i <- i + 1
}

## End(Not run)

R6 Class for Blocks Endpoint

Description

Handle all block operations in the Notion API

Note: Access this endpoint through the client instance, e.g., notion$blocks. Not to be instantiated directly.

Value

A list containing the parsed API response.

Public fields

Methods

Public methods

• BlocksEndpoint$new()

• BlocksEndpoint$retrieve()

• BlocksEndpoint$update()

• BlocksEndpoint$delete()

Method new()

Initialise block endpoint. Not to be called directly, e.g., use notion$blocks instead.

Usage

BlocksEndpoint$new(client)

Arguments

Method retrieve()

Retrieve a block

Usage

BlocksEndpoint$retrieve(block_id)

Arguments

Details

Endpoint documentation

Method update()

Update a block

Usage

BlocksEndpoint$update(block_id, archived = FALSE, ...)

Arguments

Details

Endpoint documentation

Method delete()

Delete a block

Usage

BlocksEndpoint$delete(block_id)

Arguments

Details

Endpoint documentation

Examples

notion <- notion_client()

# ----- retrieve a block
notion$blocks$retrieve("23933ea0-c1e4-81dc-9f56-f3fa251a757f")


# ----- update a block

notion$blocks$update(
  "23933ea0-c1e4-81dc-9f56-f3fa251a757f",
  heading_2 = list(
    rich_text = list(
      list(
        text = list(
          content = "Updated Test Heading"
        )
      )
    )
  )
)


# ----- delete a block

notion$blocks$delete(block_id = "23933ea0-c1e4-81d6-a6f6-dd5b57ad4aba")

R6 Class for Comments Endpoint

Description

Handle all comments operations in the Notion API

Note: Access this endpoint through the client instance, e.g., notion$comments. Not to be instantiated directly.

Value

A list containing the parsed API response.

Methods

Public methods

• CommentsEndpoint$new()

• CommentsEndpoint$create()

• CommentsEndpoint$retrieve()

Method new()

Initialise comments endpoint. Not to be called directly, e.g., use notion$comments instead.

Usage

CommentsEndpoint$new(client)

Arguments

Method create()

Create a comment

Usage

CommentsEndpoint$create(
  parent = NULL,
  discussion_id = NULL,
  rich_text,
  attachments = NULL,
  display_name = NULL
)

Arguments

Details

Endpoint documentation

Method retrieve()

Retrieve comments for a block

Usage

CommentsEndpoint$retrieve(block_id, start_cursor = NULL, page_size = NULL)

Arguments

Details

Endpoint documentation

Examples

notion <- notion_client()

# ----- create comment

notion$comments$create(
  list(page_id = "23933ea0-c1e4-81d6-a6f6-dd5b57ad4aba"),
  rich_text = list(list(
    text = list(
      content = "Hello world"
    )
  ))
)


# ----- retrieve comments

notion$comments$retrieve(block_id = "23933ea0-c1e4-81d6-a6f6-dd5b57ad4aba")

R6 Class for Databases Endpoint

Description

Handle all databases operations in the Notion API

Note: Access this endpoint through the client instance, e.g., notion$databases. Not to be instantiated directly.

Value

A list containing the parsed API response.

Methods

Public methods

• DatabasesEndpoint$new()

• DatabasesEndpoint$create()

• DatabasesEndpoint$query()

• DatabasesEndpoint$retrieve()

• DatabasesEndpoint$update()

Method new()

Initialise databases endpoint. Not to be called directly, e.g., use notion$databases instead.

Usage

DatabasesEndpoint$new(client)

Arguments

Method create()

Create a database

Usage

DatabasesEndpoint$create(parent, title, properties, ...)

Arguments

Details

Endpoint documentation

Method query()

Query a database

Usage

DatabasesEndpoint$query(
  database_id,
  filter_properties = NULL,
  filter = NULL,
  sorts = NULL,
  start_cursor = NULL,
  page_size = 100,
  ...
)

Arguments

Details

Endpoint documentation

Method retrieve()

Retrieve a database

Usage

DatabasesEndpoint$retrieve(database_id)

Arguments

Details

Endpoint documentation

Method update()

Update a database

Usage

DatabasesEndpoint$update(
  database_id,
  title = NULL,
  description = NULL,
  properties = NULL
)

Arguments

Details

Endpoint documentation

Examples

notion <- notion_client()

# ----- create a database

notion$databases$create(
  parent = list(page_id = "23933ea0-c1e4-81d6-a6f6-dd5b57ad4aba"),
  title = list(
    list(
      type = "text",
      text = list(
        content = "Grocery list"
      )
    )
  ),
  properties = list(
    Name = list(
      title = no_config()
    ),
    `In stock` = list(
      checkbox = no_config()
    )
  )
)


# ----- retrieve a database

notion$databases$retrieve(
  "23933ea0-c1e4-8136-b37b-fa235c6f2a71"
)


# ----- update a database

notion$databases$update(
  "23933ea0-c1e4-8136-b37b-fa235c6f2a71",
  list(list(
    text = list(
      content = "Today's grocery list"
    )
  ))
)


# ----- query a database

notion$databases$query(
  database_id = "23933ea0-c1e4-8136-b37b-fa235c6f2a71",
  filter = list(
    or = list(
      list(
        property = "In stock",
        checkbox = list(equals = TRUE)
      ),
      list(
        property = "Name",
        title = list(contains = "kale")
      )
    )
  ),
  sorts = list(list(
    property = "Name",
    direction = "ascending"
  ))
)


# ----- iterate through paginated results
## Not run: 
i <- 1
resps <- list()
has_more <- FALSE
start_cursor <- NULL

while (has_more) {
  resps[[i]] <- notion$databases$query(
    "22833ea0c1e481178e9cf1dcba79dbca",
    start_cursor = start_cursor
  )

  has_more <- resps[[i]][["has_more"]]
  start_cursor <- resps[[i]][["next_cursor"]]
  i <- i + 1
}

## End(Not run)

R6 Class for Pages Endpoint

Description

Handle all pages operations in the Notion API

Note: Access this endpoint through the client instance, e.g., notion$pages. Not to be instantiated directly.

Value

A list containing the parsed API response.

Public fields

Methods

Public methods

• PagesEndpoint$new()

• PagesEndpoint$create()

• PagesEndpoint$retrieve()

Method new()

Initialise pages endpoint. Not to be called directly, e.g., use notion$pages instead.

Usage

PagesEndpoint$new(client)

Arguments

Method create()

Create a page

Usage

PagesEndpoint$create(
  parent,
  properties,
  children = NULL,
  icon = NULL,
  cover = NULL
)

Arguments

Details

Endpoint documentation

Method retrieve()

Retrieve page properties

Usage

PagesEndpoint$retrieve(page_id, filter_properties = NULL)

Arguments

Details

Endpoint documentation

Examples

notion <- notion_client()

# ----- create a page
notion$pages$create(
  list(page_id = "22f33ea0c1e480b99c77d1ab72aedff9"),
  list(
    title = list(list(
      text = list(
        content = "Test Page for notionapi"
      )
    ))
  )
)


# ----- retrieve a page

notion$pages$retrieve("23933ea0-c1e4-81d6-a6f6-dd5b57ad4aba")

R6 Class for Pages Properties Endpoint

Description

Handle all pages properties operations in the Notion API

Note: Access this endpoint through the client instance, e.g., notion$pages$properties. Not to be instantiated directly.

Value

A list containing the parsed API response.

Methods

Public methods

• PagesPropertiesEndpoint$new()

• PagesPropertiesEndpoint$retrieve()

• PagesPropertiesEndpoint$update()

Method new()

Initialise pages properties endpoint. Not to be called directly, e.g., use notion$pages$properties instead.

Usage

PagesPropertiesEndpoint$new(client)

Arguments

Method retrieve()

Retrieve a page property item

Usage

PagesPropertiesEndpoint$retrieve(
  page_id,
  property_id,
  page_size = 100,
  start_cursor = NULL
)

Arguments

Details

Endpoint documentation

Method update()

Update a page property

Usage

PagesPropertiesEndpoint$update(
  page_id,
  properties = NULL,
  in_trash = NULL,
  icon = NULL,
  cover = NULL
)

Arguments

Details

Endpoint documentation

Examples

notion <- notion_client()

# ----- retrieve a page property

notion$pages$properties$retrieve(
  "23933ea0-c1e4-8104-897b-f5a09269e561",
  property_id = "q;L^"
)


# ----- update a page property

notion$pages$properties$update(
  "23933ea0-c1e4-8104-897b-f5a09269e561",
  list(
    `In stock` = list(
      checkbox = TRUE
    )
  )
)

R6 Class for Users Endpoint

Description

Handle all users operations in the Notion API

Note: Access this endpoint through the client instance, e.g., notion$users. Not to be instantiated directly.

Value

A list containing the parsed API response.

Methods

Public methods

• UsersEndpoint$new()

• UsersEndpoint$list()

• UsersEndpoint$retrieve()

• UsersEndpoint$me()

Method new()

Initialise users endpoint. Not to be called directly, e.g., use notion$users instead.

Usage

UsersEndpoint$new(client)

Arguments

Method list()

List all users

Usage

UsersEndpoint$list(start_cursor = NULL, page_size = NULL)

Arguments

Details

Endpoint documentation

Method retrieve()

Retrieve a user

Usage

UsersEndpoint$retrieve(user_id)

Arguments

Details

Endpoint documentation

Method me()

Retrieve the bot User associated with the API token

Usage

UsersEndpoint$me()

Details

Endpoint documentation

Examples

notion <- notion_client()

# ----- list all users

notion$users$list()


# ----- retrieve a user

notion$users$retrieve(user_id = "fda12729-108d-4eb5-bbfb-a8f0886794d1")


# ----- retrieve the bot User associated with the API token

notion$users$me()

Create empty property configuration

Description

Helper function that creates an empty named list for property configurations that require no additional settings.

Many database properties like text, checkbox and date do not need configuration settings. This function returns the empty configuration ({} in JSON) that these properties expect.

Usage

no_config()

Value

An empty ⁠named list⁠ that serialises to {} in JSON

Examples

notion <- notion_client()

# ----- create a database

notion$databases$create(
  parent = list(page_id = "23933ea0-c1e4-81d6-a6f6-dd5b57ad4aba"),
  title = list(
    list(
      type = "text",
      text = list(
        content = "Grocery list"
      )
    )
  ),
  properties = list(
    Name = list(
      title = no_config()
    ),
    `In stock` = list(
      checkbox = no_config()
    )
  )
)

Notion API client

Description

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

• blocks: Blocks endpoint object (BlocksEndpoint)

  • blocks$children: Blocks children endpoint object (BlocksChildrenEndpoint)

• pages: Pages endpoint object (PagesEndpoint)

  • pages$properties: Pages properties endpoint object (PagesPropertiesEndpoint)

• databases: Databases endpoint object (DatabasesEndpoint)

• comments: Comments endpoint object (CommentsEndpoint)

• search: Search endpoint (see NotionClient$search() method below)

• users: Users endpoint object (UsersEndpoint)

Public fields

Methods

Public methods

• NotionClient$new()

• NotionClient$request()

• NotionClient$print()

• NotionClient$search()

Method new()

Initialise Notion Client

Usage

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

Arguments

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

Details

Endpoint documentation

Super class

notionapi::NotionClient -> AsyncNotionClient

Methods

Public methods

• AsyncNotionClient$new()

• AsyncNotionClient$request()

• AsyncNotionClient$print()

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

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()

See Also

Notion API documentation

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"
  )
)


# ----- Async client
## Not run: 
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

## End(Not run)

Check if Notion token is set

Description

Checks if the NOTION_TOKEN environment variable is set.

Usage

notion_token_exists()

Value

TRUE if the token exists, FALSE otherwise.

Examples

notion_token_exists()

Print the result of a Notion API call

Description

Print the result of a Notion API call

Usage

## S3 method for class 'notion_response'
print(x, ...)

Arguments

Value

The JSON result.

VCR Example Helpers

Description

Internal functions for managing VCR cassettes in package examples. These functions are not intended for direct use by package users.

Usage

vcr_example_start(name)

vcr_example_end()

Arguments