The project is in a healthy, maintained state
Notion API client for Ruby.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
 Dependencies

Development

~> 10
>= 0
~> 0.82.0
~> 1.39.0
>= 0

Runtime

 Project Readme

Notion Ruby Client

A Ruby client for the Notion API.

Table of Contents

  • Installation
  • Usage
    • Create a New Bot Integration
    • Declare the API Token
    • API Client

Installation

Add to Gemfile.

gem 'notion-ruby-client'

Run bundle install.

Usage

Create a New Bot Integration

To integrate your bot with Notion, you must first create a new Notion Bot.

  1. Log into the workspace that you want your integration to be associated with.
  2. Confirm that you are an Admin in the workspace (see Settings & Members > Members).
  3. Go to Settings & Members, and click API

A screenshot of the Notion page to create a bot

Declare the API token

Notion.configure do |config|
  config.token = ENV['NOTION_API_TOKEN']
end

For Rails projects, the snippet above would go to config/application.rb.

API Client

Instanciating a new Notion API client

client = Notion::Client.new

You can specify the token or logger on a per-client basis:

client = Notion::Client.new(token: '<secret Notion API token>')

Users

Get a paginated list of User objects for the workspace:

client.users_list # retrieves the first page

client.users_list(start_cursor: 'fe2cc560-036c-44cd-90e8-294d5a74cebc')

client.users_list do |page|
  # paginate through all users
end

Get a single User:

client.user(id: 'd40e767c-d7af-4b18-a86d-55c61f1e39a4')

Databases

Gets a paginated array of Page objects contained in the requested database, filtered and ordered according to the filter and sort references provided in the request.

client.database_query(id: 'e383bcee-e0d8-4564-9c63-900d307abdb0')  # retrieves the first page

client.database_query(id: 'e383bcee-e0d8-4564-9c63-900d307abdb0', start_cursor: 'fe2cc560-036c-44cd-90e8-294d5a74cebc')

client.database_query((id: 'e383bcee-e0d8-4564-9c63-900d307abdb0') do |page|
  # paginate through all pages
end

# Filter and sort the database
sort = [
  {
    "property": "Last ordered",
    "direction": "ascending"
  }
]
filter = {
  "or": [
    {
      "property": "In stock",
      "checkbox": {
        "equals": true
      }
    },
    {
      "property": "Cost of next trip",
      "number": {
        "greater_than_or_equal_to": 2
      }
    }
  ]
}
client.database_query(id: 'e383bcee-e0d8-4564-9c63-900d307abdb0', sort: sort, filter: filter)

Get a single Database:

client.database(id: 'e383bcee-e0d8-4564-9c63-900d307abdb0')

Lists databases:

client.databases_list # retrieves the first page

client.databases_list(start_cursor: 'fe2cc560-036c-44cd-90e8-294d5a74cebc')

client.databases_list do |page|
  # paginate through all databases
end

Pages

Create a page:

properties = {
  "Name": [
    {
      "text": {
        "content": "Tuscan Kale"
      }
    }
  ],
  "Description": [
    {
      "text": {
        "content": "A dark green leafy vegetable"
      }
    }
  ],
  "Food group": {
    "name": "🥦 Vegetable"
  },
  "Price": 2.5
}
children = [
  {
    "object": "block",
    "type": "heading_2",
    "heading_2": {
      "text": [{ "type": "text", "text": { "content": "Lacinato kale" } }]
    }
  },
  {
    "object": "block",
    "type": "paragraph",
    "paragraph": {
      "text": [
        {
          "type": "text",
          "text": {
            "content": "Lacinato kale is a variety of kale with a long tradition in Italian cuisine, especially that of Tuscany. It is also known as Tuscan kale, Italian kale, dinosaur kale, kale, flat back kale, palm tree kale, or black Tuscan palm.",
            "link": { "url": "https://en.wikipedia.org/wiki/Lacinato_kale" }
          }
        }
      ]
    }
  }
]
client.create_page(
   parent: { database_id: 'e383bcee-e0d8-4564-9c63-900d307abdb0'},
   properties: properties,
   children: children
)

Retrieve a page:

client.page(id: 'b55c9c91-384d-452b-81db-d1ef79372b75')

Update page properties:

properties = {
  "In stock": true
}
client.update_page(id: 'b55c9c91-384d-452b-81db-d1ef79372b75', properties: properties)

Blocks

Retrieve children Block objects at the requested path:

client.block_children(id: 'b55c9c91-384d-452b-81db-d1ef79372b75')

client.block_children(start_cursor: 'fe2cc560-036c-44cd-90e8-294d5a74cebc')

client.block_children_list do |page|
  # paginate through all children
end

Creates and appends new children blocks to the parent block in the requested path:

children = [
  {
    "object": 'block',
    "type": 'heading_2',
    "heading_2": {
      "text": [{ "type": 'text', "text": { "content": 'A Second-level Heading' } }]
    }
  }
]
client.block_append_children(id: 'b55c9c91-384d-452b-81db-d1ef79372b75', children: children)