notion-ruby-client: an Open-Source Ruby Client for the Notion API

Tinkering with the Notion API

We’re big fans of Notion at Orbit, using it for things as varied as product roadmap, onboarding documentation, Architecture Decision Records, and user interview notes. Its versatility is its biggest strength: we love its ability to adapt gracefully from a place to jot down notes to one that houses complex, interwoven knowledge databases.

For a long time, though, Notion was missing a key ingredient to truly become the central tool to a lot of teams, including ours: an API. In late January 2021, I got access to their private beta and started playing around with the many possibilities that it opened.

I got excited about building all kinds of fun projects with the API docs, but I quickly realized that I kept copy-pasting code from one to the other: calling endpoints, error handling, pagination. Suddenly, I had an itch to scratch, and I started working on an open-source Ruby client for the Notion API, notion-ruby-client.

Releasing version 1.0

A year later, the API is out of beta, added tons of new features, and it’s finally time for notion-ruby-client to hit the anticipated 1.0 version!

notion-ruby-client abstracts away the Notion API intricacies so that you can focus on building your own integration:

• All Notion API endpoints are available and documented;
• First-party support for pagination, rate-limiting, and API errors;
• Super simple configuration—you only need a single line of code to start using the API client

Getting started is as simple as this:

{% c-block language="ruby" %}

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

{% c-block-end %}

You’re now ready to create a new page, update a database, or add blocks to a page!

{% c-block language="ruby" %}

# Retrieving the title of a page
#
page = client.page(page_id: "c2a078405abf45bcb11c09fef6dfc3af")
page.properties.Name.title.first.text.content
# "🥬 Tuscan Kale"

# Retrieving the contents of the first block of a page
#
blocks = client.block_children(block_id: "c2a078405abf45bcb11c09fef6dfc3af")
blocks.results.first.paragraph.rich_text.first.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."

{% c-block-end %}

⌨️ Try it on Repl.it

What can it be used for?

At Orbit, we’ve built a number of projects, big and small, using notion-ruby-client:

• community-ruby-notion-orbit is an Open Source Orbit integration, that synchronizes user interview notes taken in Notion to the community member’s profile in Orbit
• Station is our internal tool designed for sharing knowledge and building culture, which uses Notion as a CMS

Notion Ruby Client also powers amazing open-source projects:

• Notion Tracker Create, using Notion to create an Atomic Habit-style tracker (@jimgraham)
• Bookworm, to import Kindle highlights into a Notion database (@zorbash)
• jekyll-notion, to import Notion pages into a Jekyll-powered website (@emoriarty)

The Notion API enables endless possibilities, ranging from personal workflows to powerful integrations with other services—I hope that notion-ruby-client makes it easier to get started building your very own!

‍Special thanks to contributors @bengreenberg, @H0R15H0, and @hkob for fixing issues and adding new capabilities to the project—your contributions are highly appreciated!