- The Roam Alpha API is provided in the browser allowing you to read and write data as well as manipulate the UI
- The methods available in the API are attached to the
windowobject in the browser underroamAlphaAPI - You can see a list of examples below, showcasing the amazing things that can be built using this API, especially when used in combination with roam/js
- To learn how to use the API, there are some awesome articles written by our community
- The methods available in the API are attached to the
- February 20th, 2026
- Added
roamAlphaAPI.ui.callout.addType/.removeType— register custom callout types for the picker menu, styled entirely via CSS - Added
roamAlphaAPI.data.block.addComment— programmatic block commenting withreply-stringorreply-markdown roamAlphaAPI.data.ai.getGraphGuidelinesnow includesuserDisplayPagefield with the requesting user's display page content
- Added
- September 16th, 2025
- Updates and additions to
roamAlphaAPI.componentsrenderfunctions- new parameters for
window.roamAlphaAPI.componentsrenderBlock:
1.open?optional
2.zoom-start-after-uidoptionalopen?optional- optional Boolean
- values
- If not passed = whatever the normal open state of that block is in the db/graph
true= force open the block (show the children if exist)false= force close the block (even if the block has children, they are not shown)
zoom-start-after-uidoptional- Optional boolean
- only valid when
zoom-path?is true- path compacts to clickable
...for everything until passed in uid
- path compacts to clickable
- block uid String
- Example which showcases all the new stuff: Example::
- ability to render arbitrary strings:
window.roamAlphaAPI.componentsrenderStringrenderString- Description::
- Mounts a React component that renders the passed-in string
- the string can contain existing page titles, block refs and all the elements of roam-flavored markdown
- in other words, it can contain anything you can keep in a block string
- Watch out for
- If you pass/show
[[Page Title]]like links for pages that do not exist, those links will not work. Please try not to do that
- If you pass/show
- the string can contain existing page titles, block refs and all the elements of roam-flavored markdown
- Mounts a React component that renders the passed-in string
- Parameters::
string- The string to be displayed
- the string can contain existing page titles, block refs and all the elements of roam-flavored markdown
- in other words, it can contain anything you can keep in a block string
- Watch out for
- If you pass/show
[[Page Title]]like links for pages that do not exist, those links will not work. Please try not to do that
- If you pass/show
- String
el- DOM node where React component should be mounted
- DOM Node
- Returns::
- Promise which resolves once operation has completed
- More details here
- Promise which resolves once operation has completed
- Example:: (shows up in right sidebar)
const newNode = document.createElement('div'); const wrap = document.getElementById('right-sidebar'); // insert our new node after the wrap element in the DOM tree wrap.insertBefore(newNode, wrap.firstChild) window.roamAlphaAPI.ui.components.renderString( { el: newNode, string: "Hello this is via [[Roam Alpha API]]'s `renderString` which ((-PAiIlJ14))"})- Screenshot (see top right)
- Screenshot (see top right)
- Description::
- new parameters for
- Updates and additions to
- March 6th, 2025
q,pull, and variant API functions now have a timeout of 20 seconds- Throws an error with message
Query and/or pull expression took too long to run.when you run into the timeout limit
- Throws an error with message
- June 14th, 2024
- Ability to pin a window to the top of the right sidebar programatically
- you can now pass a new optional
pin-to-top?parameter towindow.roamAlphaAPI.ui.rightSidebar**.pinWindow**pin-to-top?- optional parameter
- If
pin-to-top?is passed, it should be eithertrueorfalse- If explicit value is not passed, we do not change the state
- i.e. if a window is pinned to top and we call
.pinWindowon it again but without specifying an explicitpin-to-top?, nothing changes
- i.e. if a window is pinned to top and we call
- If explicit value is not passed, we do not change the state
- If value is
true, then we pin the specifiedwindowto the top of the sidebar. Visually this will make the pin look red. new sidebar windows will be added below it- If another window was already pinned to top, it will be unpinned
window.roamAlphaAPI.ui.rightSidebar**.getWindows**'s return value will containpinned-to-top?:trueif a window is pinned to the top
- you can now pass a new optional
- A change in behavior of what happens when you close pinned sidebar windows (both via UI and via roamAlphaAPI.ui.rightSidebar.removeWindow)
- Previously: If we close a window which was pinned, it would disappear for now but would later resurrect (when Roam is reloaded, for instance)
- we believe this behavior is confusing
- New behavior: If we close a window which is pinned, it will be unpinned & removed. i.e. it will not resurrect
- If the user initiates the closing, they will get a dialog to confirm if they want to close a pinned window
- For extensions closing the window via roamAlphaAPI.ui.rightSidebar.removeWindow , a warning will not be shown.
- If you have extensions, the main thing to watch out for is if you’re calling roamAlphaAPI.ui.rightSidebar.removeWindow and then depending on the fact that pinned windows come back
- We think we've already caught all usages like this from Roam Depot extensions & worked with the Extension devs to fix it
- If you were relying on this behavior please [let us know](mailto:[email protected]) so we can quickly merge updates to any extensions effected
- Previously: If we close a window which was pinned, it would disappear for now but would later resurrect (when Roam is reloaded, for instance)
- Ability to pin a window to the top of the right sidebar programatically
- April 23rd, 2024
- You can now create and modify search windows in
window.roamAlphaAPI.ui.rightSidebarfunctions- new
type: "search-query" - need to pass a
search-query-strparameter instead ofblock-uid- Example usage
// Add a window that searches for "API" window.roamAlphaAPI.ui.rightSidebar .addWindow({window: {type:'search-query' ,'search-query-str':'API'}})
- Example usage
- new
- You can now create and modify search windows in
- June 5th, 2023
- New file api
- May 9th, 2023
- Load remote developer extensions from URL or using "PR-shorthand" format
- One can now load developer extensions via URLs or via PR-shorthand format
- Read more about it here
- Loom video
- {{video: https://www.loom.com/share/d6ec8341b17e4959b9604957e7212556}}
- Load remote developer extensions from URL or using "PR-shorthand" format
- February 14th, 2023
- User configurable hotkeys for commands
- new behavior you get without any code change:
can specify hotkeys for any command in Settings > Hotkeys- if you want to disable that for a command, checkout the param
disable-hotkey
- if you want to disable that for a command, checkout the param
- changes to
.addCommand- new parameters
disable-hotkeydefault-hotkey
- Examples showing
default-hotkey
- new parameters
- Roam Depot/Extension API
- exposes new function extensionAPI.ui.commandPalette.addCommand which has params equivalent to roamAlphaAPI's
.addCommand+ the new parameters- only difference is: when you use this version from extensionAPI, the commands are associated with your extension and so you have convenient grouping (in for example the Hotkeys window)
- also has extensionAPI.ui.commandPalette.removeCommand, which has same params as
.removeCommand- in contrast to the roamAlphaAPI's version, you do not need to call this on
onunload- if you call via extensionAPI, will be cleaned automatically on unload
- in contrast to the roamAlphaAPI's version, you do not need to call this on
- exposes new function extensionAPI.ui.commandPalette.addCommand which has params equivalent to roamAlphaAPI's
- Loom video
- Migration Guide from roamAlphaAPI.ui.commandPalette.addCommand to extensionAPI's version
- Loom video:
{{video: https://www.loom.com/share/f51a889a8e444ceb8c8eab15654d2650}}
- Loom video:
- Video going into all the changes
- {{video: https://www.loom.com/share/a956af55230d4540806d31dc9ecf6870}}
- Migration Guide from roamAlphaAPI.ui.commandPalette.addCommand to extensionAPI's version
- new behavior you get without any code change:
- User configurable hotkeys for commands
- February 7th, 2023
- new & updated window.roamAlphaAPI.ui.components + data on block(/s) drag
- Changes to
window.roamAlphaAPI.ui.components- new param added to
renderBlock:zoom-path?optionalzoom-path?optional- Optional boolean
- when
zoom-path?is true, it shows the zoom path i.e. view which looks similar to how linked refs look
- Example::
const newNode = document.createElement('div'); const wrap = document.getElementById('right-sidebar'); // insert our new node after the wrap element in the DOM tree wrap.insertBefore(newNode, wrap.firstChild) window.roamAlphaAPI.ui.components.renderBlock( { "uid": '6-P4ZEbIY', "el": newNode, // optional args below // open? is for if you want to force open/close the block // if not passed, uses whatever the normal open state of that block is in the db/graph "open?": false, // zoom-path? : if you want to show the zoomable path of the block too "zoom-path?": true, // optional addition in zoom-path? mode: path compacts to ... for everything until passed in uid "zoom-start-after-uid": "ImSvJvm1_" })
- new functions (for rendering pages and search views)
renderPagerenderPage- Description::
- Mounts a React component that renders a given page with children (editable) in a given DOM node.
- unless you're using specific params (
zoom-path?for block orhide-mentions?for page), you can use this interchangeably withrenderBlock
- Parameters::
- (same as renderBlock except for the new "zoom-path?". has one additional optional param
hide-mentions?) uid- Block UID of block to display
- String
el- DOM node where React component should be mounted
- DOM Node
-
hide-mentions?- Optional boolean
- to show or not to show linked refs at bottom of page
- (same as renderBlock except for the new "zoom-path?". has one additional optional param
- Description::
renderSearchrenderSearch- Description::
- Mounts a React component that renders search results (first pages then blocks) for a given
search-query-strin a given DOM node.- the results are the same as the "Find or Create Page" or cmd+u search
- class is
rm-search-query. Also uses the existingrm-queryclass - this search view is also available as an xparser component
{{[[search]]}}or{{[[search]]: Bret Victor}}
- Mounts a React component that renders search results (first pages then blocks) for a given
- Screenshot::
- Parameters::
search-query-str- Required string
el- Required
- DOM node where React component should be mounted
- DOM Node
closed?- optional boolean
- default is false
- whether view is closed or no
- optional boolean
group-by-page?- optional boolean
- default is false
- optional boolean
hide-paths?- optional boolean
- default is fale
- optional boolean
config-changed-callback- optional function parameter
- is called when config is changed as a result of user interaction
- Example::
const newNode = document.createElement('div'); const wrap = document.getElementById('right-sidebar'); // insert our new node after the wrap element in the DOM tree wrap.insertBefore(newNode, wrap.firstChild) window.roamAlphaAPI.ui.components.renderSearch( {"search-query-str": 'Bret Victor', "closed?": false, "group-by-page?": false, "hide-paths?": false, "config-changed-callback": (config) => {console.log("new-config", config);}, el: newNode})
- Description::
- new param added to
- adds data to
e.dataTransfer.getData()for drag events- works for blocks dragged and also for pages in the sidebar (the only cases I could remember which had drag)
- types
- "text/uri-list"
- "roam/roam-uri-list"
- "roam/block-uid-list"
- "roam/block-uid-list-only-parents"
- context for this and comparison with "roam/block-uid-list":
- In the Example Screenshot
- "roam/block-uid-list" will contain all the selected blocks that are visible. In this case, it will have 5 blocks
- however, in many cases, we’d probably only want the top level blocks, so for that we have "roam/block-uid-list-only-parents" , which will only have two blocks
- In the Example Screenshot
- context for this and comparison with "roam/block-uid-list":
- Example Screenshot
- In this case, I'd selected and tried to move all the blocks on the page
- Changes to
- new & updated window.roamAlphaAPI.ui.components + data on block(/s) drag
- October 1st, 2022
- For the Roam Backend API (Beta) write API release, we made the error reporting better. It made sense to reuse this code in the frontend (aka in Roam Alpha API) so as to make it easier for extension devs to reuse their code too
- Here are some of the main changes you'd want to check
- Create page (
roamAlphaAPI.data.page.createor the olderroamAlphaAPI.createPage) now throws errors (in the promise) if a page with the providedtitlealready exists or if a page with the provideduidalready exists - Update page (
roamAlphaAPI.data.page.updateor the olderroamAlphaAPI.updatePage) now throws errors (in the promise) if we're trying to change to a title that already exists in the db - Moving blocks (
roamAlphaAPI.data.block.moveor the olderroamAlphaAPI.moveBlock) now throws errors (in the promise) if blocks corresponding toparent-uidoruiddo not exist - The error messages for many asserts has been made clearer. You do not need to worry about this unless you've written error handling code which depends upon the
error.messagebeing a certain string
- Create page (
- One thing to note is that although there may be a few extra throws, the behavior as a whole has not changed. Previously, for the ones above, although they would not throw errors, they would just fail silently. So, I'm pretty sure that as long as you have proper error checks, no behavior in your extensions would've changed
- Here are some of the main changes you'd want to check
- For the Roam Backend API (Beta) write API release, we made the error reporting better. It made sense to reuse this code in the frontend (aka in Roam Alpha API) so as to make it easier for extension devs to reuse their code too
- April 5th, 2022
- Adds new functions for adding/modifying filters on a page, on linked refs to a page, on sidebar windows (previously could only handle global filters from the api)
- roam/js
window.roamAlphaAPI.ui.filters->.getPageFilters.getPageLinkedRefsFilters.getSidebarWindowFilters.setPageFilters.setPageLinkedRefsFilters.setSidebarWindowFilters
- roam/cljs
roam.ui.filtersget-page-filtersget-page-linked-refs-filterget-sidebar-window-filtersset-page-filtersset-page-linked-refs-filtersset-sidebar-window-filters
- roam/js
- Exposes new libraries to roam/cljs
- Promesa
applied-science.js-interop
- Fixes an issue where sometimes promise returned by roamAlphaAPI would always be pending
- Adds new functions for adding/modifying filters on a page, on linked refs to a page, on sidebar windows (previously could only handle global filters from the api)
- March 8th, 2022
.pull_many.fast
- January 28th, 2022
- Adds "main-window" as acceptable param for
.setBlockFocusAndSelection/Parameters::/location/window-id - Adds a new function: window.roamAlphaAPI.ui.mainWindow.focusFirstBlock
- Adds "main-window" as acceptable param for
- January 3rd, 2022
- Promisifying the roamAlphaAPI (well, partly)
- Write functions in roamAlphaAPI now utilize promises.
- This means no
setTimeouthacks will be necessary to ensure that a write took place before doing another related write.. you can just await for it. - Promises are resolved after the operation has been handled by Roam
- Important Note if you're directly manipulating the DOM:
- note that promises are resolved after Roam handles the operation, not after React updates/re-renders the DOM.
- So, if you're directly manipulating the relevant DOM element right after doing a write operation, you might need a (very small) timeout even after awaiting promise
- note that promises are resolved after Roam handles the operation, not after React updates/re-renders the DOM.
- Important Note if you're directly manipulating the DOM:
- Currently, the promise value once resolved is always
nilornullorundefined. - Obviously, you can
.catch()for errors (or the just use try catch blocks in case you are usingawait)
- This means no
- To not break existing stuff that leverage the API, read functions are the same as before (i.e. they do NOT return promises, they return their output values synchronously)
- Note about existing code: Since read API is not changing, existing code should not break
- One possible reason it could break is if it depended on the return value of write functions being true (previously, it was always
true)
- One possible reason it could break is if it depended on the return value of write functions being true (previously, it was always
- Write functions in roamAlphaAPI now utilize promises.
- Some small additions to the API
window.roamAlphaAPI.ui.setBlockFocusAndSelection.mainWindow.openDailyNotes.getOpenPageOrBlockUid
.leftSidebar.open.close
- Promisifying the roamAlphaAPI (well, partly)
