Roam Research Docs · Developer documentation
Create Experimental Graph button on the Hosted Graphs section of https://roamresearch.com/#/app
x-api-key header.
x-api-token header.
Content-Type header.
application/edn
application/json
application/transit+json
window.roamDatomicAlphaAPI JS SDK as a convenient way to access the API from within roam/js or the browser console.
graph-name action parameter is automatically filled in to the current graph.
graph-name
selector
query
inputs
block
uid
string
open
location
parent-uid
order
page
uid
title
pull
graph-name required
selector required
uid required
yS-It9SFL.
roamDatomicAlphaAPI({
"action": "pull",
"selector": "[:block/string]",
"uid": "yS-It9SFL"
});
curl \
-X POST https://4c67k7zc26.execute-api.us-west-2.amazonaws.com/v1/alphaAPI \
-H "Content-Type: application/edn" \
-H "x-api-key: YOUR_API_KEY_HERE" \
-H "x-api-token: GRAPH_TOKEN_HERE" \
-d '{:action "pull"
:graph-name "an-experimental-graph"
:selector [:block/string]
:uid "yS-It9SFL"}'
q
graph-name required
query required
inputs optional
await roamDatomicAlphaAPI({
"action": "q",
"query": "[:find ?t \
:where [?e :node/title ?t]]"});
curl \
-X POST https://4c67k7zc26.execute-api.us-west-2.amazonaws.com/v1/alphaAPI \
-H "Content-Type: application/edn" \
-H "x-api-key: YOUR_API_KEY_HERE" \
-H "x-api-token: GRAPH_TOKEN_HERE" \
-d '{:action "q"
:graph-name "an-experimental-graph"
:query "[:find ?t
:where
[?e :node/title ?t]]"}'
await roamDatomicAlphaAPI({
"action": "q",
"query": "[:find (pull ?page [*]) \
:where \
[?page :node/title]]"});
curl \
-X POST https://4c67k7zc26.execute-api.us-west-2.amazonaws.com/v1/alphaAPI \
-H "Content-Type: application/edn" \
-H "x-api-key: YOUR_API_KEY_HERE" \
-H "x-api-token: GRAPH_TOKEN_HERE" \
-d '{:action "q"
:graph-name "an-experimental-graph"
:query "[:find (pull ?page [*])
:where
[?page :node/title]]"}'
await roamDatomicAlphaAPI({
"action": "q",
"query": "[:find (pull ?page [*]) \
:where \
[?page :page/sidebar]]"});
curl \
-X POST https://4c67k7zc26.execute-api.us-west-2.amazonaws.com/v1/alphaAPI \
-H "Content-Type: application/edn" \
-H "x-api-key: YOUR_API_KEY_HERE" \
-H "x-api-token: GRAPH_TOKEN_HERE" \
-d '{:action "q"
:graph-name "an-experimental-graph"
:query "[:find (pull ?page [*])
:where \
[?page :page/sidebar]]"}'
await roamDatomicAlphaAPI({
"action": "q",
"query": "[:find (pull ?block [:block/string :block/uid]) \
:where \
[?block :block/string]]"});
curl \
-X POST https://4c67k7zc26.execute-api.us-west-2.amazonaws.com/v1/alphaAPI \
-H "Content-Type: application/edn" \
-H "x-api-key: YOUR_API_KEY_HERE" \
-H "x-api-token: GRAPH_TOKEN_HERE" \
-d '{:action "q"
:graph-name "an-experimental-graph"
:query "[:find (pull ?block [:block/string :block/uid])
:where
[?block :block/string]]"}'
await roamDatomicAlphaAPI({
"action": "q",
"query": "[:find (pull ?page [:node/title :block/uid :block/string :block/order {:block/children ...}]) \
:where \
[?page :node/title] \
[?page :block/children]]"});
curl \
-X POST https://4c67k7zc26.execute-api.us-west-2.amazonaws.com/v1/alphaAPI \
-H "Content-Type: application/edn" \
-H "x-api-key: YOUR_API_KEY_HERE" \
-H "x-api-token: GRAPH_TOKEN_HERE" \
-d '{:action "q"
:graph-name "an-experimental-graph"
:query "[:find (pull ?page [:node/title :block/uid :block/string :block/order {:block/children ...}])
:where
[?page :node/title]
[?page :block/children]]"}'
"October 4th, 2020" and its blocks in a tree structure.
let title = "October 4th, 2020"
await roamDatomicAlphaAPI({
"action": "q",
"query": "[:find (pull ?page [:node/title :block/uid :block/string :block/order {:block/children ...}]) \
:in $ ?title \
:where \
[?page :node/title ?title] \
[?page :block/children]]",
"inputs": [title]});
curl \
-X POST https://4c67k7zc26.execute-api.us-west-2.amazonaws.com/v1/alphaAPI \
-H "Content-Type: application/edn" \
-H "x-api-key: YOUR_API_KEY_HERE" \
-H "x-api-token: GRAPH_TOKEN_HERE" \
-d '{:action "q"
:graph-name "an-experimental-graph"
:inputs ["October 4th, 2020"]
:query "[:find (pull ?page [:node/title :block/uid :block/string :block/order {:block/children ...}])
:in $ ?title
:where
[?page :node/title ?title]
[?page :block/children]]"}'
create-block
graph-name required
location
parent-uid required
order required
block
string required
uid optional
09-22-2020 with the text Mondays are cool!
roamDatomicAlphaAPI({
"action": "create-block",
"location": {
"parent-uid": "09-22-2020",
"order": 0
},
"block": {
"string": "Mondays are cool!"
}
});
curl \
-X POST https://4c67k7zc26.execute-api.us-west-2.amazonaws.com/v1/alphaAPI \
-H "Content-Type: application/edn" \
-H "x-api-key: YOUR_API_KEY_HERE" \
-H "x-api-token: GRAPH_TOKEN_HERE" \
-d '{:action "create-block"
:graph-name "an-experimental-graph"
:location {:parent-uid "09-22-2020"
:order 0}
:block {:string "Mondays are cool!"}}'
move-block
graph-name required
location
parent-uid required
order required
block
uid required
yS-It9SFL as the 6th child under 09-23-2020.
roamDatomicAlphaAPI({
"action": "move-block",
"location": {
"parent-uid": "09-23-2020",
"order": 5
},
"block": {
"uid": "yS-It9SFL"
}
});
curl \
-X POST https://4c67k7zc26.execute-api.us-west-2.amazonaws.com/v1/alphaAPI \
-H "Content-Type: application/edn" \
-H "x-api-key: YOUR_API_KEY_HERE" \
-H "x-api-token: GRAPH_TOKEN_HERE" \
-d '{:action "move-block"
:graph-name "an-experimental-graph"
:location {:parent-uid "09-23-2020"
:order 5}
:block {:uid "yS-It9SFL"}}'
update-block
graph-name required
block
uid required
string required
open optional
yS-It9SFL to be closed with the text Poof!.
roamDatomicAlphaAPI({
"action": "update-block",
"block": {
"uid": "yS-It9SFL",
"open": false,
"string": "Poof!"
}
});
curl \
-X POST https://4c67k7zc26.execute-api.us-west-2.amazonaws.com/v1/alphaAPI \
-H "Content-Type: application/edn" \
-H "x-api-key: YOUR_API_KEY_HERE" \
-H "x-api-token: GRAPH_TOKEN_HERE" \
-d '{:action "update-block"
:graph-name "an-experimental-graph"
:block {:uid "yS-It9SFL"
:open false
:string "Poof!"}}'
delete-block
graph-name required
block
uid required
yS-It9SFL.
roamDatomicAlphaAPI({
"action": "delete-block",
"block": {
"uid": "yS-It9SFL"
}
});
curl \
-X POST https://4c67k7zc26.execute-api.us-west-2.amazonaws.com/v1/alphaAPI \
-H "Content-Type: application/edn" \
-H "x-api-key: YOUR_API_KEY_HERE" \
-H "x-api-token: GRAPH_TOKEN_HERE" \
-d '{:action "delete-block"
:graph-name "an-experimental-graph"
:block {:uid "yS-It9SFL"}}'
create-page
September 22nd, 2020 will create a new daily note if it does not yet exist.
graph-name required
page
title required
uid optional
Reminder Inbox.
roamDatomicAlphaAPI({
"action": "create-page",
"page": {
"title": "Reminder Inbox"
}
});
curl \
-X POST https://4c67k7zc26.execute-api.us-west-2.amazonaws.com/v1/alphaAPI \
-H "Content-Type: application/edn" \
-H "x-api-key: YOUR_API_KEY_HERE" \
-H "x-api-token: GRAPH_TOKEN_HERE" \
-d '{:action "create-page"
:graph-name "an-experimental-graph"
:page {:title "Reminder Inbox"}}'
update-page
graph-name required
page
uid required
title required
aY-ItUT65 to Testing Alpha API.
roamDatomicAlphaAPI({
"action": "update-page",
"page": {
"uid": "aY-ItUT65"
"title": "Testing Alpha API"
}
});
curl \
-X POST https://4c67k7zc26.execute-api.us-west-2.amazonaws.com/v1/alphaAPI \
-H "Content-Type: application/edn" \
-H "x-api-key: YOUR_API_KEY_HERE" \
-H "x-api-token: GRAPH_TOKEN_HERE" \
-d '{:action "update-page"
:graph-name "an-experimental-graph"
:page {:uid "aY-ItUT65"
:title "Testing Alpha API"}}'
delete-page
graph-name required
page
uid required
09-22-2020.
roamDatomicAlphaAPI({
"action": "delete-page",
"page": {
"uid": "09-22-2020"
}
});
curl \
-X POST https://4c67k7zc26.execute-api.us-west-2.amazonaws.com/v1/alphaAPI \
-H "Content-Type: application/edn" \
-H "x-api-key: YOUR_API_KEY_HERE" \
-H "x-api-token: GRAPH_TOKEN_HERE" \
-d '{:action "delete-page"
:graph-name "an-experimental-graph"
:page {:uid "09-22-2020"}}'
markdown version · view in Roam Research · exported 2026-07-03