Roam Research Private API

There is no REST API for Roam released yet. I have reverse-engineered an “API” to use in my projects, but it is by no means official. Read on about my Roam API implementation:

Roam Research is a powerful “note-taking tool for networked thought“. See more of my Roam writings, tools and scripts. The only annoyance of Roam is its lack of a public API. I love connecting things and have quite an extensive personal infrastructure, all connecting to Evernote. Having data flow through various APIs is crucial to my automation philosophy. I just had to get some kind of Roam API.

Instead of waiting, I wrote a project to expose Roam API to my personal infrastructure. Check out roam-research-private-api on npm.

Illustration of Roam Private API logo

I since switched to Firebase 2 Roam – another implementation using Firebase API from Roam. It is much leaner.

With Roam Research Private API, I used to sync my Roam Graph every 6 hours with other pieces of my personal infrastructure:

  • Import events for the day from Google Calendar
  • Import Google Photos from that day to show up in my daily notes
  • Import new notes from Evernote notebook which I use for quick capture.

Here are the other amazing things the roam-research-private-api can do:

Roam Private API

This project exposes command line tool (roam-api) and a node library to connect Roam Research to your other software. You can use it in bash scripts, Github actions, or as a dependency of your project.

How does it work?

It looks like Roam is not providing a REST API any time soon. If you want to bridge Roam with your other software, you can do so from within Roam (with JavaScript), but that has limited number of use cases. Without a REST API, this project launches an invisible browser and performs automated actions, just as you would manually. No need to install chrome, this library comes with one. It uses your login and password, so this won’t work if you are using Google login. It wraps around import/export functionality and actions exposed via roamAlphaApi.

Command line tool roam-api

This package exposes a roam-api tool in your system. You can use it to automate Roam and bridge other systems with your Roam graph.

Installation:

This entire library is build on node, so you need node v12 and npm v6 in your system. You can install the package the following way:

npm i -g roam-research-private-api

Now you can use a variety of commands. All command take the following arguments, which you can also set as environmental variables:

  • -g, --graph or env variable ROAM_API_GRAPH – this is your graph name
  • -e, --email or env variable ROAM_API_EMAIL – email to log into your Roam
  • -p, --password or env variable ROAM_API_PASSWORD – password to your Roam.

roam-api export will export your Roam graph to a directory of your choice.

This example will export the graph to your desktop. It will appear as “db.json”.

roam-api export ~/Desktop

It can also push the new version of the graph to an URL of your choosing. That way, you can upload the graph to some other system or use it with Zapier and similar tools.

roam-api export ~/Desktop http://secret.url?token=secret_token.

roam-api search will search your Roam graph for a phrase:

roam-api search "potatoes"

Result will be JSON array of objects { blockUid, pageTitle, string }

roam-api-query will let you do a full Datalog query.

This will find all block uids in your database which have the content “Import”.

roam-api query '[:find ?uid :where [?b :block/string "Import"] [?b :block/uid ?uid]]'

Check out this fantastic article to know more about the Roam data structure.

roam-api create create a block under specified uid. If no uid is provided, it will be inserted into your daily page:

roam-api create "This will be prepended to my daily page"

Library to use in your project.

As mentioned, this is also a library that you can use within your project. Here are examples on how to do so:

Pull requests welcome and I take no responsibility in case this messes up your Roam Graph :).

Of course, you can find the project on Github.

Other Roam Hacks and APIs

I also have the following projects connecting to Roam: