Notion Ruby Client

A Ruby client for the Notion API.

Installation
Usage

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.

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

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)

Blaked84/notion-ruby-client