Roam Research Docs · Developer documentation

Roam Alpha API v2

markdown version · view in Roam Research

• Draft restructuring of Roam Alpha API, written for both humans and AI. Method content verified against the source (July 2026). Historical change log stays on the original page.
• Getting Started
  • The Roam Alpha API is provided in the browser, letting you read and write data and drive the UI. It lives on the window object as window.roamAlphaAPI and is available from roam/js code blocks, Roam Depot extensions, and the browser console.
  • For the ClojureScript version of this API, see the Reference section of roam/cljs.
• Conventions
  • Most functions take a single object argument. Keys are kebab-case strings, and boolean keys often end in ? — quote them in JS: {"parent-uid": "abc", "zoom-path?": true}. Exceptions: data.roamQuery uses camelCase keys, and a few functions take positional arguments (data.addPullWatch, data.page.addShortcut, ui.mainWindow.registerComponent, everything in util).
  • Write functions return a Promise that resolves to null once Roam has applied the operation — after the triggering event and all of its descendant events are handled. Chain dependent writes with await; no setTimeout hacks needed.
    • The promise resolves before React re-renders, so if you manipulate the DOM right after a write you may still need a very small timeout.
    • Failures reject the promise — use .catch(), or try/catch with await.
  • Read functions are synchronous unless a method's Returns:: says otherwise (data.roamQuery, ui.mainWindow.getOpenView, and ui.mainWindow.getOpenPageOrBlockUid return promises). Prefer the promise-returning data.async.* variants in new code — the synchronous reads will eventually be deprecated.
  • Rate limit: rate-limited functions (all writes, plus a number of UI functions) share a budget of 1500 calls per 60 seconds; exceeding it throws.
  • q, pull, pull_many and their variants time out after 20 seconds, throwing Query and/or pull expression took too long to run. — pull and pull_many accept an options argument to override the timeout.
  • uids
    • Block and page uids are random 9-character strings — see util.generateUID.
    • Daily note pages use the date as their uid, in MM-DD-YYYY format (e.g. 07-16-2026 for July 16th, 2026) — see util.dateToPageUid.
  • roamAlphaAPI.apiVersion is a string property (e.g. "1.1.3") — use it for feature detection.
  • sidebar window argument
    • The shared shape used by the ui.rightSidebar window functions and ui.filters.getSidebarWindowFilters/setSidebarWindowFilters:
    • type (string, required) — one of "block" | "outline" | "mentions" | "graph" | "search-query"
    • block-uid (string, required for every type except "search-query") — uid of the block or page the window shows
    • search-query-str (string, required when type is "search-query", in place of block-uid) — the search query
• Reference
  • roamAlphaAPI.data — queries and reads, plus the write API for blocks, pages, and users
    • roamAlphaAPI.data.q
      • Description::
        • Query the graph with Datomic-flavored datalog. Synchronous.
        • See the datomic docs for the query syntax, learndatalogtoday.org to learn it, and the datascript tests for good examples.
        • Legacy alias: roamAlphaAPI.q (older top-level name; prefer this namespaced path)
      • Parameters::
        • query (string, required) — the datalog query
        • ...args (optional) — additional inputs, bound to the query's :in clauses (the database itself is passed implicitly)
      • Returns::
        • Array of result tuples
      • Example::

        • // all block uids and strings in the graph
          window.roamAlphaAPI.data.q(
            `[:find ?b ?s
              :where
              [?e :block/uid ?b]
              [?e :block/string ?s]]`);
          // => [["y3LFc4rFd", "some block text"], ["09sbCUlgt", "another block"], ...]
          
          // with an :in argument
          window.roamAlphaAPI.data.q(
            `[:find ?s
              :in $ ?uid
              :where
              [?e :block/uid ?uid]
              [?e :block/string ?s]]`,
            "abc123xyz");
          // => [["the block's text"]]

    • roamAlphaAPI.data.pull
      • Description::
        • Declaratively fetch a (possibly nested) selection of attributes for one entity. Synchronous.
        • See the datomic pull docs — Roam uses datascript internally, which supports the majority of datomic syntax. In the JS API the pattern is a string rather than clojure data.
        • Legacy alias: roamAlphaAPI.pull (older top-level name; prefer this namespaced path)
      • Parameters::
        • pattern (string, required) — pull pattern, e.g. "[*]" or "[:block/string {:block/children ...}]"
        • eid (required) — one of:
          • a :db/id integer, e.g. 24
          • a lookup ref as a string, e.g. "[:node/title \"hello world\"]"
          • a lookup ref as a 2-element array, e.g. [":block/uid", "xyz"]
        • opts (object, optional) — {timeout: <ms>} overrides the default 20-second timeout
      • Returns::
        • Object of the pulled attributes
      • Example::

        • // all attributes of this block
          window.roamAlphaAPI.data.pull("[*]", [":block/uid", "xyz"])
          // =>
          {":block/uid": "xyz",
           ":block/string": "the block's text",
           ":block/order": 0,
           ":block/open": true,
           ":create/time": 1610031973159,
           ":edit/time": 1610031974560,
           ":block/children": [{":db/id": 1234}],
           ":db/id": 1041}
          
          // this block's string and all of its descendants
          window.roamAlphaAPI.data.pull("[:block/string {:block/children ...}]", "[:block/uid \"xyz\"]")
          // =>
          {":block/string": "the block's text",
           ":block/children": [{":block/string": "child text"}]}

    • roamAlphaAPI.data.pull_many
      • Description::
        • Same as data.pull, but for many entities at once — faster than pulling in a loop. Synchronous.
      • Parameters::
        • pattern (string, required) — same as data.pull's pattern
        • eids (array, required) — array of eids, each in any of the forms data.pull's eid accepts
        • opts (object, optional) — {timeout: <ms>} overrides the default 20-second timeout
      • Returns::
        • Array of pulled objects
      • Example::

        • roamAlphaAPI.data.pull_many("[*]",
            [[":block/uid", "_fM7pkQEa"], [":block/uid", "kZHsZniZs"]]);
          // =>
          [{":block/uid": "_fM7pkQEa",
            ":block/string": "first block",
            ...},
           {":block/uid": "kZHsZniZs",
            ":block/string": "second block",
            ...}]

    • roamAlphaAPI.data.fast.q
      • Description::
        • Same signature as data.q, using an experimental clojurescript→javascript conversion that makes read access roughly 33% faster.
      • Returns::
        • A cljs object wrapped in a JS Proxy. Treat it as read only; it may not print to the console correctly.
        • Key access includes the full namespaced key: obj[":block/string"]. If you rename a key in the pull ([:block/string :as "string"]), access it as obj.string.
        • For the internals and trade-offs, see https://blog.wsscode.com/alternative-to-clj-js/
      • Example::

        • window.roamAlphaAPI.data.fast.q(
            `[:find ?b ?s
              :where
              [?e :block/uid ?b]
              [?e :block/string ?s]]`);
          // => proxy-wrapped results — index like a regular array, treat as read only

    • roamAlphaAPI.data.backend.q
      • Description::
        • Same signature as data.q, but runs the query on the backend, off the main thread — useful for expensive queries.
        • Falls back to running locally when the graph's backend is unavailable (encrypted graphs, offline graphs).
        • Warning: the backend can be a few changes behind the frontend while local changes are still syncing.
      • Returns::
        • Promise resolving to the query results
      • Example::

        • await window.roamAlphaAPI.data.backend.q(
            `[:find ?b ?s
              :where
              [?e :block/uid ?b]
              [?e :block/string ?s]]`);
          // => [["y3LFc4rFd", "some block text"], ...]

    • roamAlphaAPI.data.async
      • Description::
        • Promise-returning versions of the read functions, with the same parameters as their synchronous peers: q, pull, pull_many, search, semanticSearch, fast.q.
        • Eventually Roam will migrate to the async API and deprecate the synchronous reads — prefer these when building new extensions.
        • async.search uses the indexed search worker when available, transparently falling back to the standard search — same parameters and return shape as data.search, wrapped in a promise.
        • async.semanticSearch is async-only and documented below.
      • Example::

        • await roamAlphaAPI.data.async.q(
            `[:find ?s
              :where [?e :block/string ?s]]`)
          // => [["some block text"], ...]
          
          await roamAlphaAPI.data.async.pull("[*]", [":block/uid", "xyz"])
          // => {":block/uid": "xyz", ":block/string": "the block's text", ...}

    • roamAlphaAPI.data.search
      • Description::
        • Search pages and blocks by text — the same algorithm as the "Find or Create Page" search in the UI. Synchronous.
        • Results are ranked by relevance: (0) page title exactly matches query, (1) page title contains query as substring, (2) page title contains all query words, (3) block contains query as substring, (4) block contains all query words. Ranks 2 and 4 apply to multi-word queries only.
      • Parameters::
        • search-str (string, required) — the search query
        • search-blocks (boolean, optional, default true) — include block results
        • search-pages (boolean, optional, default true) — include page results
        • hide-code-blocks (boolean, optional, default false) — exclude code blocks from results
        • limit (number, optional, default 300, max 1000) — maximum number of results
        • pull (string | array, optional, default [:block/string :node/title :block/uid]) — pull pattern for the returned fields
      • Returns::
        • Array of results matching the pull pattern
      • Example::

        • roamAlphaAPI.data.search({"search-str": "my query"})
          // =>
          [{":node/title": "My Query Notes",
            ":block/uid": "aBc123xYz"},
           {":block/string": "a block mentioning my query",
            ":block/uid": "dEf456uVw"},
           ...]

    • roamAlphaAPI.data.semanticSearchEnabled
      • Description::
        • Whether semantic search is currently usable for this graph — true when embeddings are enabled and a user is signed in. Synchronous.
        • Check this before calling data.async.semanticSearch, which throws when semantic search isn't available.
      • Parameters::
        • None
      • Returns::
        • boolean
      • Example::

        • roamAlphaAPI.data.semanticSearchEnabled()
          // => true

    • roamAlphaAPI.data.async.semanticSearch
      • Description::
        • Hybrid semantic + keyword search powered by "better search" (embeddings + keyword index), ranked by relevance.
        • Requires embeddings to be enabled and a signed-in user — throws when unavailable, so check data.semanticSearchEnabled() first. While embeddings are still indexing, it returns partial results rather than throwing.
      • Parameters::
        • search-str (string, required) — the search query
        • k (number, optional, default 25, max 200) — number of results (also the search pool size)
        • search-blocks (boolean, optional, default true) — include block results
        • search-pages (boolean, optional, default true) — include page results
        • hide-code-blocks (boolean, optional, default: the user's hide-code-blocks setting) — exclude code blocks
      • Returns::
        • Promise resolving to an array of hit records {type, uid, topUids}:
          • type — "chunk", "block", or "page"
          • uid — the hit's primary block uid (the first of topUids)
          • topUids — the hit's top-level block uids
        • Array order is the relevance ranking — there is no per-hit score, since results mix semantic and keyword matches.
      • Example::

        • await roamAlphaAPI.data.async.semanticSearch({"search-str": "my query"})
          // =>
          [{type: "chunk",
            uid: "aBc123xYz",
            topUids: ["aBc123xYz", "dEf456uVw"]},
           {type: "page",
            uid: "gHi789jKl",
            topUids: ["gHi789jKl"]},
           ...]

    • roamAlphaAPI.data.roamQuery
      • Description::
        • Execute a Roam query — the same syntax used in {{[[query]]: ...}} blocks — and return matching blocks/pages.
        • Two modes: pass the uid of an existing query block to use its stored settings, or pass a query string directly with optional display settings.
        • Note: unlike the rest of roamAlphaAPI, the parameters are camelCase.
      • Parameters::
        • uid (string) — block uid of an existing query block; uses that block's stored display settings
        • query (string, required if no uid) — a query string, e.g. "{and: project active}"
        • groupByPage (boolean, optional, default false) — group results by page (query mode only)
        • nestUnderParent (boolean, optional, default false) — collapse child matches under their parent (query mode only)
        • sort (string, optional; query mode only) — with groupByPage: "page-most-recent" (default) | "page-title" | "page-created-date" | "daily-note"; without: "created-date" (default) | "edited-date" | "daily-note-date"
        • sortOrder (string, optional, default "desc") — "asc" or "desc" (query mode only)
        • offset (integer, optional, default 0) — number of results to skip
        • limit (integer | null, optional, default 20) — maximum results; pass null for all
        • pull (string, optional, default "[:block/string :node/title :block/uid]") — pull pattern for the results
      • Returns::
        • Promise resolving to {total: <number>, results: <array of pulled results>}
      • Example::

        • await window.roamAlphaAPI.data.roamQuery({query: "{and: [[project]] [[active]]}"})
          // => {total: 42, results: [{":block/string": "...", ":block/uid": "aBc123xYz"}, ...]}
          
          // run an existing query block with its stored settings
          await window.roamAlphaAPI.data.roamQuery({uid: "abc123def"})
          // => {total: 7, results: [...]}

    • roamAlphaAPI.data.addPullWatch
      • Description::
        • Watch a pull pattern on an entity: the callback fires after changes are recorded, with the before and after state. Changes are debounced (~100ms). Takes positional arguments.
      • Parameters::
        • pattern (string, required) — the pull pattern to watch
        • entity-id (string, required) — the entity to watch, e.g. '[:block/uid "02-21-2021"]'
        • callback (function, required) — called with (before, after) pull results
      • Returns::
        • Promise resolving to null once the watch is registered
      • Example::

        • window.roamAlphaAPI.data.addPullWatch(
            "[:block/children :block/string {:block/children ...}]",
            '[:block/uid "02-21-2021"]',
            (before, after) => { console.log("before", before, "after", after); })
          // resolves to null; the callback later fires with the before/after pull results

    • roamAlphaAPI.data.removePullWatch
      • Description::
        • Remove pull watches. With all three arguments, removes only the watch with that callback; without callback, removes every watch for that pattern + entity; with no arguments at all, removes all pull watches. Takes positional arguments.
      • Parameters::
        • pattern (string, optional) — the same value passed to addPullWatch
        • entity-id (string, optional) — the same value passed to addPullWatch
        • callback (function, optional) — the callback to remove
      • Returns::
        • Promise resolving to null
      • Example::

        • window.roamAlphaAPI.data.removePullWatch(
            "[:block/children :block/string {:block/children ...}]",
            '[:block/uid "02-21-2021"]',
            myCallbackFn)
          // resolves to null

    • roamAlphaAPI.data.undo
      • Description::
        • Undo the latest change made in this session — the same operation as the Undo command (cmd-z).
      • Parameters::
        • None
      • Returns::
        • Promise resolving to null
      • Example::

        • await window.roamAlphaAPI.data.undo()
          // => null

    • roamAlphaAPI.data.redo
      • Description::
        • Redo the last undone change — the same operation as the Redo command (cmd-shift-z).
      • Parameters::
        • None
      • Returns::
        • Promise resolving to null
      • Example::

        • await window.roamAlphaAPI.data.redo()
          // => null

    • roamAlphaAPI.data.ai
      • Description::
        • Internal namespace backing Roam's MCP server tools (getPage, getBlock, getBacklinks, roamQuery, search, semanticSearch, suggestLinks, searchTemplates, getGraphGuidelines, getComments). Not a stable public surface — breaking changes land without notice; don't build on it.
    • roamAlphaAPI.data.block
      • roamAlphaAPI.data.block.create
        • Description::
          • Create a new block at a location.
          • Legacy alias: roamAlphaAPI.createBlock (older top-level name; prefer this namespaced path)
        • Parameters::
          • location (object, required)
            • parent-uid (string, required) — uid of the parent block or page
            • order (number | "first" | "last", required) — position among the parent's children, 0-indexed
          • block (object, required)
            • string (string, required) — text content of the block
            • uid (string, optional) — autogenerated if omitted; pass one (see util.generateUID) only when you need to know it ahead of time
            • open (boolean, optional, default true) — collapse state
            • heading (integer, optional) — heading styling, 0 (none) to 3
            • text-align (string, optional) — "left" | "center" | "right" | "justify"
            • children-view-type (string, optional) — view type of the block's children: "bullet" | "numbered" | "document"
            • block-view-type (string, optional) — view type of the block itself: "outline" | "horizontal-outline" | "popout" | "tabs" | "comment" | "side" | "vertical"
        • Returns::
          • Promise resolving to null; rejects if parent-uid doesn't exist or uid is already taken
        • Example::

          • await window.roamAlphaAPI.data.block.create(
              {"location": {"parent-uid": "01-21-2021", "order": 0},
               "block": {"string": "test"}})
            // => null

      • roamAlphaAPI.data.block.update
        • Description::
          • Update a block's text and/or display properties. Only the keys you pass are changed.
          • Legacy alias: roamAlphaAPI.updateBlock (older top-level name; prefer this namespaced path)
        • Parameters::
          • block (object, required)
            • uid (string, required) — block to update
            • string (string, optional) — new text content
            • open, heading, text-align, children-view-type, block-view-type — all optional, same values as in data.block.create
        • Returns::
          • Promise resolving to null
        • Example::

          • await window.roamAlphaAPI.data.block.update(
              {"block": {"uid": "f8cXfDIRn", "string": "Love"}})
            // => null

      • roamAlphaAPI.data.block.move
        • Description::
          • Move a block (together with its children) to a new location.
          • Legacy alias: roamAlphaAPI.moveBlock (older top-level name; prefer this namespaced path)
        • Parameters::
          • block (object, required)
            • uid (string, required) — block to move
          • location (object, required)
            • parent-uid (string, required) — uid of the new parent block or page
            • order (number | "first" | "last", required) — position among the new parent's children
        • Returns::
          • Promise resolving to null; rejects if the block or parent-uid doesn't exist
        • Example::

          • await window.roamAlphaAPI.data.block.move(
              {"location": {"parent-uid": "01-21-2021", "order": 0},
               "block": {"uid": "f8cXfDIRn"}})
            // => null

      • roamAlphaAPI.data.block.delete
        • Description::
          • Delete a block and all of its children; the order of the remaining siblings is recalculated.
          • Legacy alias: roamAlphaAPI.deleteBlock (older top-level name; prefer this namespaced path)
        • Parameters::
          • block (object, required)
            • uid (string, required) — block to delete
        • Returns::
          • Promise resolving to null
        • Example::

          • await window.roamAlphaAPI.data.block.delete(
              {"block": {"uid": "f8cXfDIRn"}})
            // => null

      • roamAlphaAPI.data.block.reorderBlocks
        • Description::
          • Reorder the direct children of a block. Pass all current children of parent-uid — no other blocks, no duplicates — in the desired order.
        • Parameters::
          • location (object, required)
            • parent-uid (string, required)
          • blocks (array of strings, required) — every child uid of parent-uid, listed in the new order
        • Returns::
          • Promise resolving to null
        • Example::

          • await roamAlphaAPI.data.block.reorderBlocks(
              {location: {"parent-uid": "ihu5eUofL"},
               blocks: ["QCE0cNNNL", "IATKcVmWE", "nC22orMO4"]})
            // => null

      • roamAlphaAPI.data.block.fromMarkdown
        • Description::
          • Parse a markdown string into blocks and insert them at a location. Uses the same parser as file import: nested lists become nested blocks; headings, code blocks, bold, italic, links, etc. are supported.
        • Parameters::
          • location (object, required)
            • parent-uid (string, required)
            • order (number | "first" | "last", required)
          • markdown-string (string, required) — the markdown content to parse into blocks
        • Returns::
          • Promise resolving to {uids: [...]} — the uids of the top-level blocks created
        • Example::

          • await window.roamAlphaAPI.data.block.fromMarkdown({
              location: {"parent-uid": "4VuwigG1O", "order": "first"},
              "markdown-string": "# Hello\n\n- Item 1\n- Item 2\n  - Nested"})
            // => {uids: ["aBc123xYz", "dEf456uVw", "gHi789jKl"]}

      • roamAlphaAPI.data.block.addComment
        • Description::
          • Add a comment to a block. Pass either a single plain-text reply or markdown that is parsed into multiple sibling reply blocks.
        • Parameters::
          • block-uid (string, required) — block to comment on
          • reply-string (string) — plain text for a single reply block (use this or reply-markdown, not both)
          • reply-markdown (string) — markdown parsed into multiple sibling reply blocks
        • Returns::
          • Promise resolving to null
        • Example::

          • // single reply
            await window.roamAlphaAPI.data.block.addComment(
              {"block-uid": "abc123", "reply-string": "This is a comment"})
            // => null
            
            // markdown reply (parsed into siblings)
            await window.roamAlphaAPI.data.block.addComment(
              {"block-uid": "abc123", "reply-markdown": "First block\n- Nested child"})
            // => null

    • roamAlphaAPI.data.page
      • roamAlphaAPI.data.page.create
        • Description::
          • Create a new page. A title in daily-note format (January 21st, 2021) creates that daily note if it doesn't exist yet.
          • Legacy alias: roamAlphaAPI.createPage (older top-level name; prefer this namespaced path)
        • Parameters::
          • page (object, required)
            • title (string, required)
            • uid (string, optional) — autogenerated if omitted; in normal operation you shouldn't pass one
            • children-view-type (string, optional) — "bullet" | "numbered" | "document"
        • Returns::
          • Promise resolving to null; rejects if a page with the given title or uid already exists
        • Example::

          • await window.roamAlphaAPI.data.page.create({page: {title: "My New Page"}})
            // => null

      • roamAlphaAPI.data.page.fromMarkdown
        • Description::
          • Create a new page and populate it with blocks parsed from a markdown string (same parser as file import). A daily-note title creates that daily note if it doesn't exist yet.
        • Parameters::
          • page (object, required) — same keys as data.page.create
          • markdown-string (string, required) — the markdown content to parse into blocks
        • Returns::
          • Promise resolving to {uid: <page-uid>}; rejects if a page with the given title already exists
        • Example::

          • await window.roamAlphaAPI.data.page.fromMarkdown({
              page: {title: "My New Page"},
              "markdown-string": "# Heading\n\n- Item 1\n- Item 2"})
            // => {uid: "mK9pQ2rTw"}

      • roamAlphaAPI.data.page.update
        • Description::
          • Update a page's title and/or children-view-type. Only the keys you pass are changed.
          • Legacy alias: roamAlphaAPI.updatePage (older top-level name; prefer this namespaced path)
        • Parameters::
          • page (object, required)
            • uid (string, required)
            • title (string, optional) — new title
            • children-view-type (string, optional) — "bullet" | "numbered" | "document"
        • Returns::
          • Promise resolving to null; rejects when renaming to a title that already exists in the graph
        • Example::

          • await window.roamAlphaAPI.data.page.update(
              {page: {uid: "RZVuh3aZN", title: "New Title"}})
            // => null

      • roamAlphaAPI.data.page.delete
        • Description::
          • Delete a page and all of its blocks.
          • Legacy alias: roamAlphaAPI.deletePage (older top-level name; prefer this namespaced path)
        • Parameters::
          • page (object, required)
            • uid (string, required)
        • Returns::
          • Promise resolving to null
        • Example::

          • await window.roamAlphaAPI.data.page.delete({page: {uid: "RZVuh3aZN"}})
            // => null

      • roamAlphaAPI.data.page.addShortcut
        • Description::
          • Add a page to the left-sidebar shortcuts, or move it if it's already there. Takes positional arguments.
        • Parameters::
          • uid (string, required) — page uid
          • index (number, optional) — position in the shortcut list; defaults to the end (capped to the valid range)
        • Returns::
          • Promise resolving to null
        • Example::

          • await roamAlphaAPI.data.page.addShortcut("12-11-2025");
            await roamAlphaAPI.data.page.addShortcut("12-11-2025", 4);
            // each => null

      • roamAlphaAPI.data.page.removeShortcut
        • Description::
          • Remove a page from the left-sidebar shortcuts. Takes a positional argument.
        • Parameters::
          • uid (string, required) — page uid
        • Returns::
          • Promise resolving to null
        • Example::

          • await roamAlphaAPI.data.page.removeShortcut("12-11-2025")
            // => null

    • roamAlphaAPI.data.user
      • roamAlphaAPI.data.user.upsert
        • Description::
          • Create and/or update a user entity.
        • Parameters::
          • user-uid (string, required)
          • display-name (string, optional)
        • Returns::
          • Promise resolving to null
        • Example::

          • await window.roamAlphaAPI.data.user.upsert(
              {"user-uid": "BBG4fFwolaVlT5FZQdzAI7P40aB3",
               "display-name": "Josh"})
            // => null

  • roamAlphaAPI.ui — everything that drives the interface: focus, windows, sidebars, filters, menus, and custom components
    • roamAlphaAPI.ui.getFocusedBlock
      • Description::
        • Metadata about the currently focused block, or null if none. Synchronous.
        • More robust than CSS selectors — works even from a ui.commandPalette callback, after the block has lost focus in the DOM.
      • Parameters::
        • None
      • Returns::

        • {"block-uid": "YnatnbZzF",
           "window-id": "BBG4fFwolaVlT5FZQdzAI7P40aB3-body-outline-04-15-2021"}

      • Example::

        • window.roamAlphaAPI.ui.getFocusedBlock()
          // =>
          {"block-uid": "YnatnbZzF",
           "window-id": "BBG4fFwolaVlT5FZQdzAI7P40aB3-body-outline-04-15-2021"}

    • roamAlphaAPI.ui.setBlockFocusAndSelection
      • Description::
        • Focus a block in a specific window, and optionally set the cursor position or selection.
      • Parameters::
        • location (object, optional; defaults to the currently focused block) — same shape as ui.getFocusedBlock's return value
          • block-uid (string, required)
          • window-id (string, required) — a window id from ui.rightSidebar.getWindows, or the string "main-window"
        • selection (object, optional; without it the cursor is placed at the end of the string)
          • start (integer, required) — 0-indexed
          • end (integer, optional) — with end, start–end becomes a selection; without it, the cursor is placed before the start-th character. If end is less than start, both are treated as the value of end.
      • Returns::
        • Promise resolving to null
      • Example::

        • window.roamAlphaAPI.ui.setBlockFocusAndSelection(
            {location: window.roamAlphaAPI.ui.getFocusedBlock(),
             selection: {start: 3, end: 7}})
          // resolves to null

    • roamAlphaAPI.ui.mainWindow
      • roamAlphaAPI.ui.mainWindow.openBlock
        • Description::
          • Zoom into a block in the main window. Passing a page's uid opens the page — e.g. {block: {uid: "10-16-2021"}} opens that daily note.
          • If no block or page with that uid exists, nothing happens — the promise still resolves.
        • Parameters::
          • block (object, required)
            • uid (string, required)
        • Returns::
          • Promise resolving to null
        • Example::

          • await window.roamAlphaAPI.ui.mainWindow.openBlock({block: {uid: "v9eHoHwqS"}})
            // => null

      • roamAlphaAPI.ui.mainWindow.openPage
        • Description::
          • Open a page in the main window, by title or uid. If the page doesn't exist, nothing happens — the promise still resolves.
        • Parameters::
          • page (object, required) — one of:
            • title (string)
            • uid (string)
        • Returns::
          • Promise resolving to null
        • Example::

          • await window.roamAlphaAPI.ui.mainWindow.openPage({page: {title: "test-new"}})
            await window.roamAlphaAPI.ui.mainWindow.openPage({page: {uid: "RZVuh3aZN"}})
            // each => null

      • roamAlphaAPI.ui.mainWindow.openDailyNotes
        • Description::
          • Open the daily notes log in the main window.
        • Parameters::
          • None
        • Returns::
          • Promise resolving to null
        • Example::

          • await window.roamAlphaAPI.ui.mainWindow.openDailyNotes()
            // => null

      • roamAlphaAPI.ui.mainWindow.focusFirstBlock
        • Description::
          • Focus the first block in the main window.
        • Parameters::
          • None
        • Returns::
          • Promise resolving to null
        • Example::

          • await window.roamAlphaAPI.ui.mainWindow.focusFirstBlock()
            // => null

      • roamAlphaAPI.ui.mainWindow.getOpenPageOrBlockUid
        • Description::
          • The uid of the page or block currently open in the main window.
        • Parameters::
          • None
        • Returns::
          • Promise resolving to the uid string, or null when no page/block is open (e.g. the daily notes log)
        • Example::

          • await window.roamAlphaAPI.ui.mainWindow.getOpenPageOrBlockUid()
            // => "Vfht187T1" (or null on the daily notes log)

      • roamAlphaAPI.ui.mainWindow.getOpenView
        • Description::
          • Describes what is currently displayed in the main window.
        • Parameters::
          • None
        • Returns::
          • Promise resolving to one of:

          • // page
            {type: "outline",
             uid: "Vfht187T1",
             title: "My Page Title"}
            
            // zoomed into a block
            {type: "outline",
             uid: "abc123xyz",
             "block-string": "Some block content"}
            
            // daily notes
            {type: "log"}
            
            // graph view
            {type: "graph"}
            
            // diagram
            {type: "diagram",
             uid: "diagram-uid"}
            
            // PDF viewer
            {type: "pdf",
             uid: "pdf-block-uid"}
            
            // all pages search
            {type: "search"}
            
            // custom component, see registerComponent
            {type: "custom",
             id: "component-id",
             args: []}

      • roamAlphaAPI.ui.mainWindow.registerComponent
        • Description::
          • Register a custom main-window view: a React component that can be opened as a full main-window view. Takes positional arguments.
        • Parameters::
          • id (string, required) — identifier for the component
          • component (React component, required)
        • Returns::
          • null
      • roamAlphaAPI.ui.mainWindow.unregisterComponent
        • Description::
          • Unregister a custom main-window view. Takes a positional argument.
        • Parameters::
          • id (string, required)
        • Returns::
          • null
      • roamAlphaAPI.ui.mainWindow.openComponent
        • Description::
          • Open a registered custom component in the main window. Takes positional arguments. Extra arguments are passed to the component and reported by getOpenView as args.
        • Parameters::
          • id (string, required)
          • ...args (optional) — arguments for the component
        • Returns::
          • null
      • roamAlphaAPI.ui.mainWindow.closeComponent
        • Description::
          • Close the open custom component. Takes a positional argument.
        • Parameters::
          • id (string, required)
        • Returns::
          • null
    • roamAlphaAPI.ui.leftSidebar
      • roamAlphaAPI.ui.leftSidebar.open
        • Description::
          • Make the left sidebar visible.
        • Parameters::
          • None
        • Returns::
          • Promise resolving to null
      • roamAlphaAPI.ui.leftSidebar.close
        • Description::
          • Hide the left sidebar.
        • Parameters::
          • None
        • Returns::
          • Promise resolving to null
    • roamAlphaAPI.ui.rightSidebar
      • roamAlphaAPI.ui.rightSidebar.open
        • Description::
          • Make the right sidebar visible.
        • Parameters::
          • None
        • Returns::
          • Promise resolving to null
      • roamAlphaAPI.ui.rightSidebar.close
        • Description::
          • Hide the right sidebar, keeping its open windows.
        • Parameters::
          • None
        • Returns::
          • Promise resolving to null
      • roamAlphaAPI.ui.rightSidebar.getWindows
        • Description::
          • All open sidebar windows. Synchronous.
        • Parameters::
          • None
        • Returns::
          • Array of window objects with keys:
            • type — "block" | "outline" | "mentions" | "graph" | "search-query"
            • window-id (string) — usable with e.g. ui.setBlockFocusAndSelection
            • order (number), collapsed?, pinned?, pinned-to-top? (booleans)
            • the window's target, depending on type: block-uid (plus block-string), page-uid (plus title), mentions-uid, or search-query-str
        • Example::

          • window.roamAlphaAPI.ui.rightSidebar.getWindows()
            // =>
            [{type: "outline",
              "window-id": "...",
              "page-uid": "mK9pQ2rTw",
              title: "My Page",
              order: 0,
              "collapsed?": false,
              "pinned?": false,
              "pinned-to-top?": false},
             {type: "block",
              "window-id": "...",
              "block-uid": "aBc123xYz",
              "block-string": "some block text",
              order: 1,
              "collapsed?": true,
              "pinned?": false,
              "pinned-to-top?": false}]

      • roamAlphaAPI.ui.rightSidebar.addWindow
        • Description::
          • Add a window to the right sidebar. If the sidebar is closed, opens it.
        • Parameters::
          • window (object, required) — see sidebar window argument, plus:
            • order (number, optional) — position in the sidebar; if not specified, the new window is added at the top
            • class (string | array of strings, optional) — CSS class(es) added to the window's element
        • Returns::
          • Promise resolving to null
        • Example::

          • // a block
            window.roamAlphaAPI.ui.rightSidebar
              .addWindow({window: {type: "block", "block-uid": "1fP8LY5ED"}})
            
            // a page outline
            window.roamAlphaAPI.ui.rightSidebar
              .addWindow({window: {type: "outline", "block-uid": "cArVJL_vg"}})
            
            // linked references of a block or page
            window.roamAlphaAPI.ui.rightSidebar
              .addWindow({window: {type: "mentions", "block-uid": "vutDCPD8G"}})
            
            // a window that searches for "API"
            window.roamAlphaAPI.ui.rightSidebar
              .addWindow({window: {type: "search-query", "search-query-str": "API"}})
            
            // each resolves to null

      • roamAlphaAPI.ui.rightSidebar.removeWindow
        • Description::
          • Remove a window from the right sidebar. Removing a pinned window unpins and removes it — it will not come back on reload, and no confirmation dialog is shown for API calls (the UI shows one when the user closes a pinned window).
        • Parameters::
          • window (object, required) — see sidebar window argument
        • Returns::
          • Promise resolving to null
        • Example::

          • window.roamAlphaAPI.ui.rightSidebar
              .removeWindow({window: {type: "block", "block-uid": "1fP8LY5ED"}})
            // resolves to null

      • roamAlphaAPI.ui.rightSidebar.expandWindow
        • Description::
          • Expand a collapsed sidebar window.
        • Parameters::
          • window (object, required) — see sidebar window argument
        • Returns::
          • Promise resolving to null
      • roamAlphaAPI.ui.rightSidebar.collapseWindow
        • Description::
          • Collapse a sidebar window.
        • Parameters::
          • window (object, required) — see sidebar window argument
        • Returns::
          • Promise resolving to null
      • roamAlphaAPI.ui.rightSidebar.pinWindow
        • Description::
          • Pin a sidebar window; optionally pin it to the top of the sidebar.
        • Parameters::
          • window (object, required) — see sidebar window argument
          • pin-to-top? (boolean, optional) — true pins the window to the top: the pin turns red, new windows are added below it, and a previously top-pinned window is unpinned. When omitted, the pin-to-top state is left unchanged.
        • Returns::
          • Promise resolving to null
      • roamAlphaAPI.ui.rightSidebar.unpinWindow
        • Description::
          • Unpin a sidebar window.
        • Parameters::
          • window (object, required) — see sidebar window argument
        • Returns::
          • Promise resolving to null
      • roamAlphaAPI.ui.rightSidebar.setWindowOrder
        • Description::
          • Move a sidebar window to a specific position.
        • Parameters::
          • window (object, required) — see sidebar window argument, plus:
            • order (number, required) — new position, 0 to n
        • Returns::
          • Promise resolving to null
    • roamAlphaAPI.ui.filters
      • Description::
        • Filters are per-user. The get functions are synchronous; the set functions return promises. Filters have the shape {"includes": [...page titles], "removes": [...page titles]}.
      • roamAlphaAPI.ui.filters.addGlobalFilter
        • Description::
          • Add a global filter — like clicking the globe icon on a link in the filter dialog.
        • Parameters::
          • title (string, required) — page title
          • type (string, required) — "includes" | "removes"
        • Returns::
          • Promise resolving to null
      • roamAlphaAPI.ui.filters.removeGlobalFilter
        • Description::
          • Remove a global filter.
        • Parameters::
          • title (string, required) — page title
          • type (string, required) — "includes" | "removes"
        • Returns::
          • Promise resolving to null
      • roamAlphaAPI.ui.filters.getGlobalFilters
        • Description::
          • The global filters currently in place. Synchronous.
        • Parameters::
          • None
        • Returns::
          • {"includes": [...], "removes": [...]} — lists of page titles
      • roamAlphaAPI.ui.filters.getPageFilters
        • Description::
          • The current user's filters for a page. Synchronous.
        • Parameters::
          • page (object, required) — one of:
            • title (string)
            • uid (string)
        • Returns::
          • {"includes": [...], "removes": [...]} — lists of page titles
        • Example::

          • window.roamAlphaAPI.ui.filters.getPageFilters({page: {title: "test"}})
            // => {"includes": ["March 11th, 2022"], "removes": []}

      • roamAlphaAPI.ui.filters.setPageFilters
        • Description::
          • Set a page's filters for the current user. Pass {} as filters to clear them.
        • Parameters::
          • page (object, required) — one of title | uid
          • filters (object, required)
            • includes (array of page titles, optional)
            • removes (array of page titles, optional)
        • Returns::
          • Promise resolving to null
        • Example::

          • window.roamAlphaAPI.ui.filters.setPageFilters(
              {page: {title: "test"},
               filters: {includes: ["March 11th, 2022"]}})
            
            // clear the filters
            window.roamAlphaAPI.ui.filters.setPageFilters(
              {page: {title: "test"}, filters: {}})
            
            // each resolves to null

      • roamAlphaAPI.ui.filters.getPageLinkedRefsFilters
        • Description::
          • The current user's filters on a page's linked references (mentions). Synchronous.
        • Parameters::
          • page (object, required) — one of title | uid
        • Returns::
          • {"includes": [...], "removes": [...]} — lists of page titles
      • roamAlphaAPI.ui.filters.setPageLinkedRefsFilters
        • Description::
          • Set the filters on a page's linked references (mentions) for the current user. Pass {} as filters to clear them.
        • Parameters::
          • page (object, required) — one of title | uid
          • filters (object, required) — includes / removes arrays of page titles
        • Returns::
          • Promise resolving to null
        • Example::

          • window.roamAlphaAPI.ui.filters.setPageLinkedRefsFilters(
              {page: {title: "test"},
               filters: {includes: ["Author"]}})
            // resolves to null

      • roamAlphaAPI.ui.filters.getSidebarWindowFilters
        • Description::
          • The filters on a right-sidebar window. Synchronous.
        • Parameters::
          • window (object, required) — see sidebar window argument; "search-query" windows don't support filters
        • Returns::
          • {"includes": [...], "removes": [...]} — lists of page titles
        • Example::

          • window.roamAlphaAPI.ui.filters.getSidebarWindowFilters(
              {window: {"block-uid": "WYlc2nIO9", type: "outline"}})
            // => {"includes": ["Author"], "removes": []}

      • roamAlphaAPI.ui.filters.setSidebarWindowFilters
        • Description::
          • Set the filters on a right-sidebar window. Pass {} as filters to clear them.
        • Parameters::
          • window (object, required) — see sidebar window argument; "search-query" windows don't support filters
          • filters (object, required) — includes / removes arrays of page titles
        • Returns::
          • Promise resolving to null
        • Example::

          • window.roamAlphaAPI.ui.filters.setSidebarWindowFilters(
              {window: {"block-uid": "WYlc2nIO9", type: "outline"},
               filters: {includes: ["Author"]}})
            // resolves to null

    • roamAlphaAPI.ui.commandPalette
      • roamAlphaAPI.ui.commandPalette.addCommand
        • Description::
          • Add a command to the Command Palette (cmd-p). Calling again with the same label updates the existing command instead of adding a second one.
          • Users can assign their own hotkey to any command in Settings → Hotkeys.
        • Parameters::
          • label (string, required) — text shown in the Command Palette. Prefix it with your plugin name for global uniqueness, e.g. "RoamRS: Start review session"
          • callback (function, required) — called with no arguments when the user runs the command
          • disable-hotkey (boolean, optional) — don't allow a hotkey for this command
          • default-hotkey (string | array of strings, optional) — most commands should NOT set this. Without it (and unless disable-hotkey is set), no hotkey is preassigned but the user can add one in Settings → Hotkeys.
            • A hotkey string looks like "super-shift-d" — at least one modifier plus a key.
            • An array of strings (max 5) defines a multi-step hotkey, e.g. ["ctrl-c", "ctrl-m"] (like the native "go to next block").
            • Modifiers ("defmod" is the OS default modifier — cmd on macOS, ctrl elsewhere):
              • {{table}}
                • modifier-str
                  • Windows/Linux
                    • macOS
                • "shift"
                  • shift
                    • shift
                • "ctrl"
                  • ctrl
                    • ctrl
                • "alt"
                  • alt
                    • option
                • "super"
                  • win
                    • cmd
                • "defmod"
                  • ctrl
                    • cmd
        • Returns::
          • Promise resolving to null
        • Example::

          • window.roamAlphaAPI.ui.commandPalette.addCommand(
              {label: "hi",
               callback: () => console.log("Hello World!")})
            
            // with a default hotkey — in most cases you do NOT want this;
            // the user can customize it in Settings → Hotkeys
            window.roamAlphaAPI.ui.commandPalette.addCommand(
              {label: "example1",
               callback: () => console.log("Hello World!"),
               "default-hotkey": "ctrl-cmd-l"})
            
            // each resolves to null

      • roamAlphaAPI.ui.commandPalette.removeCommand
        • Description::
          • Remove a command with the given label from the Command Palette.
        • Parameters::
          • label (string, required) — the label passed to addCommand
        • Returns::
          • Promise resolving to null
        • Example::

          • window.roamAlphaAPI.ui.commandPalette.removeCommand({label: "hi"})
            // resolves to null

    • roamAlphaAPI.ui.slashCommand
      • roamAlphaAPI.ui.slashCommand.addCommand
        • Description::
          • Add a command to the / slash menu. Calling again with the same label updates the existing command.
        • Parameters::
          • label (string, required) — text shown in the slash menu
          • display-conditional (function, optional) — called with the context object (without indexes); return true to show the command
          • callback (function, required) — called with the context object when the user selects the command. Return a string to insert at the current location, or null to handle insertion yourself (the typed search string is not removed).
          • context object:

            • {"block-uid": "YnatnbZzF",
               "window-id": "BBG4fFwolaVlT5FZQdzAI7P40aB3-body-outline-04-15-2021",
               indexes: [1, 10]}

        • Returns::
          • null
        • Example::

          • window.roamAlphaAPI.ui.slashCommand.addCommand({
              label: "Quick Test",
              callback: (context) => "It works! 🎉"
            });
            // => null

      • roamAlphaAPI.ui.slashCommand.removeCommand
        • Description::
          • Remove a command with the given label from the slash menu.
        • Parameters::
          • label (string, required) — the label passed to addCommand
        • Returns::
          • null
    • roamAlphaAPI.ui.blockContextMenu
      • Description::
        • The menu shown when right-clicking a block's bullet. Custom commands are nested under the Plugins menu item. Calling addCommand again with the same label updates the existing command.
        • Five other context menus share this same addCommand/removeCommand API and are documented below by their differences: pageContextMenu, pageRefContextMenu, blockRefContextMenu, pageLinkContextMenu, msContextMenu.
      • roamAlphaAPI.ui.blockContextMenu.addCommand
        • Parameters::
          • label (string, required) — text shown in the menu. Prefix it with your plugin name for global uniqueness, e.g. "RoamRS: Start review session"
          • display-conditional (function, optional) — called with the block context every time the menu opens; return true to include the command for that block
          • callback (function, required) — called with the block context when the user selects the command
          • block context:

            • {"block-string": "Todos",
               "block-uid": "YnatnbZzF",
               heading: null,
               "page-uid": "04-15-2021",
               "read-only?": false,
               "window-id": "BBG4fFwolaVlT5FZQdzAI7P40aB3-body-outline-04-15-2021"}

        • Returns::
          • Promise resolving to null
        • Example::

          • roamAlphaAPI.ui.blockContextMenu.addCommand(
              {label: "Debug: Console Log",
               "display-conditional": (e) => e["block-string"].includes("Test Block"),
               callback: (e) => console.log(e)})
            // resolves to null

      • roamAlphaAPI.ui.blockContextMenu.removeCommand
        • Description::
          • Remove a command with the given label.
        • Parameters::
          • label (string, required)
        • Returns::
          • Promise resolving to null
    • roamAlphaAPI.ui.pageContextMenu
      • Description::
        • Right-clicking a page title. Same addCommand/removeCommand API as ui.blockContextMenu, but both return null (synchronous).
        • context passed to display-conditional and callback:

          • {"page-uid": "YnatnbZzF",
             "page-title": "title",
             "window-id": "BBG4fFwolaVlT5FZQdzAI7P40aB3-body-outline-04-15-2021"}

      • Example::

        • roamAlphaAPI.ui.pageContextMenu.addCommand(
            {label: "Debug: Console Log", callback: (e) => console.log(e)})
          // => null

    • roamAlphaAPI.ui.pageRefContextMenu
      • Description::
        • Right-clicking a page reference inside a block. Same API as ui.blockContextMenu; addCommand/removeCommand return null (synchronous).
        • context passed to display-conditional and callback:

          • {"ref-uid": "YnatnbZzF",
             "block-uid": "xyz",       // containing block
             "window-id": "BBG4fFwolaVlT5FZQdzAI7P40aB3-body-outline-04-15-2021",
             indexes: [0, 9],          // outer indexes in the block string
             type: "attribute"}

        • type values:
          • "page-ref" — [[test]]
          • "attribute" — test::
          • "tag" — #test
          • "multitag" — #[[Test]]
          • "inline-link" — [t]([[Test]])
    • roamAlphaAPI.ui.blockRefContextMenu
      • Description::
        • Clicking a block reference. Same API as ui.blockContextMenu; addCommand/removeCommand return null (synchronous).
        • context passed to display-conditional and callback:

          • {"ref-uid": "YnatnbZzF",
             "block-uid": "abc123xyz", // containing block
             "window-id": "BBG4fFwolaVlT5FZQdzAI7P40aB3-body-outline-04-15-2021",
             indexes: [0, 9]}          // outer indexes in the block string

    • roamAlphaAPI.ui.pageLinkContextMenu
      • Description::
        • Page links that are neither a page title nor inside a block — currently that's linked references and query results when grouped by page. Same API as ui.blockContextMenu; addCommand/removeCommand return null (synchronous).
        • context passed to display-conditional and callback:

          • {"page-uid": "YnatnbZzF",
             "page-title": "title"}

    • roamAlphaAPI.ui.msContextMenu
      • Description::
        • The context menu shown when multiple blocks are selected (multiselect). Same API as ui.blockContextMenu; addCommand/removeCommand return null (synchronous).
      • Example::

        • window.roamAlphaAPI.ui.msContextMenu.addCommand(
            {label: "test", callback: () => { console.log("hey") }})
          
          window.roamAlphaAPI.ui.msContextMenu.removeCommand({label: "test"})
          
          // each => null

    • roamAlphaAPI.ui.multiselect
      • roamAlphaAPI.ui.multiselect.getSelected
        • Description::
          • The blocks currently drag-selected (highlighted) in the main window. Synchronous.
        • Parameters::
          • None
        • Returns::
          • Array of {"block-uid", "window-id"} objects; empty array if nothing is selected
        • Example::

          • window.roamAlphaAPI.ui.multiselect.getSelected()
            // => [{"block-uid": "Vfht187T1", "window-id": "main-window"},
            //     {"block-uid": "abc123xyz", "window-id": "main-window"}]

    • roamAlphaAPI.ui.individualMultiselect
      • roamAlphaAPI.ui.individualMultiselect.getSelectedUids
        • Description::
          • The uids currently selected with individual multiselect (checkbox selection, usually triggered by cmd-m). Synchronous.
        • Parameters::
          • None
        • Returns::
          • Array of block uids
        • Example::

          • window.roamAlphaAPI.ui.individualMultiselect.getSelectedUids()
            // => ["Vfht187T1", "abc123xyz"]

    • roamAlphaAPI.ui.graphView
      • Description::
        • The page-level graph views are rendered with Cytoscape; the callbacks expose the Cytoscape object to enable plugins, alternative UIs, and other experimentation.
      • roamAlphaAPI.ui.graphView.addCallback
        • Description::
          • Register a callback that fires whenever a graph view loads. Does not fire for the new whole-graph overview — see graphView.wholeGraph below.
        • Parameters::
          • label (string, required) — used to upsert or remove the callback
          • callback (function, required) — called with {cytoscape, elements, type}:
            • cytoscape — the Cytoscape graph object
            • elements — array of the nodes and edges in the graph
            • type — "page" | "all-pages"

            • {cytoscape: Core {_private: {…}},
               elements: [
                 {id: "eTCpkG-HI", name: "B", weight: 7},
                 {id: "05-04-2021", name: "May 4th, 2021", weight: 10},
                 {id: "eTCpkG-HI-FrW4nHLat", source: "eTCpkG-HI", target: "FrW4nHLat"}
               ],
               type: "page"}

          • type (string, optional) — only trigger for "page" or "all-pages" graph views; if omitted, triggers for both
        • Returns::
          • Promise resolving to null
      • roamAlphaAPI.ui.graphView.removeCallback
        • Description::
          • Remove a callback with the given label.
        • Parameters::
          • label (string, required)
        • Returns::
          • Promise resolving to null
      • roamAlphaAPI.ui.graphView.wholeGraph
        • Description::
          • API for the whole-graph overview (the old graphView.addCallback does not fire for it). Synchronous functions.
        • roamAlphaAPI.ui.graphView.wholeGraph.setMode
          • Description::
            • Set the overview mode. Positional argument: "Whole Graph" | "Explore".
        • roamAlphaAPI.ui.graphView.wholeGraph.setExplorePages
          • Description::
            • Set the pages shown in Explore mode. Positional argument: array of page titles.
        • roamAlphaAPI.ui.graphView.wholeGraph.getExplorePages
          • Returns::
            • Array of the page titles currently explored
        • roamAlphaAPI.ui.graphView.wholeGraph.addCallback
          • Description::
            • Register a callback for when the whole-graph view loads.
          • Parameters::
            • label (string, required)
            • callback (function, required)
        • roamAlphaAPI.ui.graphView.wholeGraph.removeCallback
          • Description::
            • Remove a callback with the given label.
          • Parameters::
            • label (string, required)
        • Example::

          • roamAlphaAPI.ui.graphView.wholeGraph.addCallback({
              label: "test",
              callback: (x) => console.log(x)})
            
            roamAlphaAPI.ui.graphView.wholeGraph.removeCallback({label: "test"});
            
            roamAlphaAPI.ui.graphView.wholeGraph.setExplorePages(["a"]);
            roamAlphaAPI.ui.graphView.wholeGraph.getExplorePages();
            // => ["a"]
            
            roamAlphaAPI.ui.graphView.wholeGraph.setMode("Whole Graph");
            roamAlphaAPI.ui.graphView.wholeGraph.setMode("Explore");

    • roamAlphaAPI.ui.components
      • Description::
        • Mount Roam-rendered React components into your own DOM nodes. Unmount them with unmountNode.
      • roamAlphaAPI.ui.components.renderBlock
        • Description::
          • Mount a component rendering a block with its children (editable) into a DOM node.
        • Parameters::
          • uid (string, required) — block to display
          • el (DOM node, required) — where to mount the component
          • open? (boolean, optional) — true forces the block open (children shown), false forces it closed; omitted = whatever the block's open state is in the graph
          • zoom-path? (boolean, optional) — show the zoom path above the block (similar to how linked references look)
          • zoom-start-after-uid (string, optional; only valid with zoom-path?) — the path is compacted to a clickable ... for everything before this uid
        • Returns::
          • Promise resolving to null
        • Example::

          • const newNode = document.createElement("div");
            const wrap = document.getElementById("right-sidebar");
            wrap.insertBefore(newNode, wrap.firstChild);
            
            window.roamAlphaAPI.ui.components.renderBlock(
              {uid: "6-P4ZEbIY",
               el: newNode,
               "open?": false,
               "zoom-path?": true,
               "zoom-start-after-uid": "ImSvJvm1_"})
            // resolves to null once mounted

      • roamAlphaAPI.ui.components.renderPage
        • Description::
          • Mount a component rendering a page with its children (editable) into a DOM node. Interchangeable with renderBlock unless you need zoom-path? (block-only) or hide-mentions? (page-only).
        • Parameters::
          • uid (string, required) — page to display
          • el (DOM node, required)
          • hide-mentions? (boolean, optional) — hide the linked references at the bottom of the page
        • Returns::
          • Promise resolving to null
      • roamAlphaAPI.ui.components.renderSearch
        • Description::
          • Mount search results (pages first, then blocks — the same results as the cmd-u search) into a DOM node. Also available as the {{[[search]]: query}} component. CSS classes: rm-search-query, plus the existing rm-query.
        • Parameters::
          • search-query-str (string, required) — the search query
          • el (DOM node, required)
          • closed? (boolean, optional, default false) — collapse the view
          • group-by-page? (boolean, optional, default false) — group results by page
          • hide-paths? (boolean, optional, default false) — hide block paths in results
          • config-changed-callback (function, optional) — called with the new config when the user changes the view's configuration
        • Returns::
          • Promise resolving to null
        • Example::

          • const newNode = document.createElement("div");
            const wrap = document.getElementById("right-sidebar");
            wrap.insertBefore(newNode, wrap.firstChild);
            
            window.roamAlphaAPI.ui.components.renderSearch(
              {"search-query-str": "Bret Victor",
               el: newNode,
               "group-by-page?": false,
               "config-changed-callback": (config) => console.log("new config", config)})
            // resolves to null once mounted

      • roamAlphaAPI.ui.components.renderString
        • Description::
          • Mount a component rendering a string of Roam-flavored markdown — anything a block string can contain: page links, block refs, formatting, components.
          • Avoid rendering [[Page Title]] links for pages that don't exist — those links won't work.
        • Parameters::
          • string (string, required) — the string to render
          • el (DOM node, required)
        • Returns::
          • Promise resolving to null
        • Example::

          • window.roamAlphaAPI.ui.components.renderString(
              {el: newNode,
               string: "Hello via [[Roam Alpha API]]'s `renderString` — supports ((abc123xyz)) refs too"})
            // resolves to null once mounted

      • roamAlphaAPI.ui.components.unmountNode
        • Description::
          • Unmount a previously mounted React component from a DOM node.
        • Parameters::
          • el (DOM node, required) — the node the component was mounted in
        • Returns::
          • Promise resolving to null
    • roamAlphaAPI.ui.react
      • Description::
        • React components for declarative JSX use — equivalents of ui.components. Note the props are camelCase, unlike the kebab-case keys of ui.components.
      • roamAlphaAPI.ui.react.Block
        • Description::
          • Renders a block with its children (editable).
        • Props::
          • uid (string, required) — block to display
          • open (boolean, optional) — force open/closed; omitted = the block's open state in the graph
          • zoomPath (boolean, optional) — show the zoom path
          • zoomStartAfterUid (string, optional; only valid with zoomPath) — compact the path to ... before this uid
        • Example::

          • const { Block } = window.roamAlphaAPI.ui.react;
            
            <Block uid="6-P4ZEbIY" />
            <Block uid="6-P4ZEbIY" open={false} />
            <Block uid="6-P4ZEbIY" zoomPath={true} zoomStartAfterUid="ImSvJvm1_" />

      • roamAlphaAPI.ui.react.Page
        • Description::
          • Renders a page (editable).
        • Props::
          • uid (string) / title (string) — one of the two is required
          • hideMentions (boolean, optional) — hide the linked references section at the bottom
        • Example::

          • const { Page } = window.roamAlphaAPI.ui.react;
            
            <Page uid="page-uid-123" />
            <Page title="My Page" hideMentions={true} />

      • roamAlphaAPI.ui.react.Search
        • Description::
          • Renders search results for a query.
        • Props::
          • searchQueryStr (string, required) — the search query
          • closed (boolean, optional) — collapse the view
          • groupByPage (boolean, optional) — group results by their page
          • hidePaths (boolean, optional) — hide block paths in results
          • onConfigChange (function, optional) — called with the new config object when the user changes grouping etc.
        • Example::

          • const { Search } = window.roamAlphaAPI.ui.react;
            
            <Search searchQueryStr="Bret Victor" groupByPage={true}
                    onConfigChange={(config) => console.log(config)} />

      • roamAlphaAPI.ui.react.BlockString
        • Description::
          • Renders a Roam-markdown string — [[page links]], ((block refs)), formatting. The rendered content is not editable.
        • Props::
          • string (string, required) — the Roam-markdown string to render
        • Example::

          • const { BlockString } = window.roamAlphaAPI.ui.react;
            
            <BlockString string="Hello [[World]]" />
            <BlockString string="This is **bold** and __italic__" />

    • roamAlphaAPI.ui.callout
      • roamAlphaAPI.ui.callout.addType
        • Description::
          • Register a custom callout type so it appears in the callout picker menu (shown when clicking a callout block's icon) and can be used in [!type] syntax.
          • Icon and color come entirely from CSS: style .rm-callout--{type} for the color and .rm-callout--{type} .rm-callout__icon for the icon. A built-in default icon shows until your CSS loads.
        • Parameters::
          • type (string, required) — the string used in the [!type] callout syntax
        • Returns::
          • null
        • Example::

          • window.roamAlphaAPI.ui.callout.addType({type: "recipe"})
            // => null

          • Then provide CSS via roam/css or an extension stylesheet:

            • .rm-callout--recipe {
                --callout-color: #f778ba;
              }
              .rm-callout--recipe .rm-callout__icon::before {
                content: "🍪";
                font-family: initial;
              }

      • roamAlphaAPI.ui.callout.removeType
        • Description::
          • Remove a previously registered custom callout type from the picker menu.
        • Parameters::
          • type (string, required) — the type string to remove
        • Returns::
          • null
        • Example::

          • window.roamAlphaAPI.ui.callout.removeType({type: "recipe"})
            // => null

  • roamAlphaAPI.util — uid and daily-note date helpers. All synchronous, all taking positional arguments.
    • roamAlphaAPI.util.generateUID
      • Description::
        • Generate a Roam block uid — a random string of length nine.
      • Parameters::
        • None
      • Returns::
        • string
      • Example::

        • window.roamAlphaAPI.util.generateUID()
          // => "aB3xK9mP2"

    • roamAlphaAPI.util.pageTitleToDate
      • Description::
        • Convert a daily note page title to a date.
      • Parameters::
        • title (string, required) — a daily note title like "June 16th, 2022"
      • Returns::
        • A Date, or null for anything that isn't a daily note title
    • roamAlphaAPI.util.dateToPageTitle
      • Description::
        • Convert a date to a daily note page title ("June 16th, 2022").
      • Parameters::
        • date (Date, required) — a JavaScript Date
      • Returns::
        • string
    • roamAlphaAPI.util.dateToPageUid
      • Description::
        • Convert a date to a daily note page uid ("06-16-2022"). Use this instead of generateUID when programmatically creating a daily note page and you need its uid ahead of time.
      • Parameters::
        • date (Date, required) — a JavaScript Date
      • Returns::
        • string
  • roamAlphaAPI.file — upload, fetch, and delete files hosted on Roam
    • roamAlphaAPI.file.upload
      • Description::
        • Upload a file to Roam.
        • Also exists as the legacy alias roamAlphaAPI.util.uploadFile — prefer this version; the old one won't be removed.
      • Parameters::
        • file (File, required) — a File object
        • toast (object, optional)
          • hide (boolean, optional, default false) — hide the upload toast
      • Returns::
        • Promise resolving to a firebase download url (string)
      • Example::

        • await roamAlphaAPI.file.upload({file: new File([""], "test"), toast: {hide: true}})
          // => "https://firebasestorage.googleapis.com/v0/b/firescript-577a2.appspot.com/o/imgs%2Fapp%2Fmy-graph%2FaB3xK9mP2.png?alt=media&token=..."

    • roamAlphaAPI.file.get
      • Description::
        • Fetch a file hosted on Roam. You could also fetch the url yourself, but get handles decryption on encrypted graphs and restores the original file name and type metadata.
      • Parameters::
        • url (string, required) — a firebase storage url, obtained from file.upload or from a block
      • Returns::
        • Promise resolving to a File object
      • Example::

        • await roamAlphaAPI.file.get({url: "https://firebasestorage.googleapis.com/v0/b/firescript-577a2.appspot.com/o/..."})
          // => File {name: "GVfB6XBcMR.pdf", type: "application/pdf", size: 183424, ...}

    • roamAlphaAPI.file.delete
      • Description::
        • Delete a file hosted on Roam.
      • Parameters::
        • url (string, required) — a firebase storage url, obtained from file.upload or from a block
      • Returns::
        • Promise resolving to undefined
  • roamAlphaAPI.user — info about the current user
    • roamAlphaAPI.user.uid
      • Description::
        • The current user's uid. Synchronous. Use it with data.pull to get the user's display page and other metadata.
      • Parameters::
        • None
      • Returns::
        • string, or null when not signed in
      • Example::

        • roamAlphaAPI.user.uid()
          // => "BBG4fFwolaVlT5FZQdzAI7P40aB3" (or null when signed out)
          
          // pull all info about the current user
          roamAlphaAPI.data.pull("[*]", [":user/uid", window.roamAlphaAPI.user.uid()]);
          // => {":user/uid": "BBG4fFwolaVlT5FZQdzAI7P40aB3", ":user/display-name": "Josh", ...}

    • roamAlphaAPI.user.isAdmin
      • Description::
        • Whether the current user is an admin of this graph (the graph owner). Synchronous.
      • Parameters::
        • None
      • Returns::
        • boolean
  • roamAlphaAPI.graph — properties (not functions) describing the current graph
    • roamAlphaAPI.graph.name — the name of the current graph (string)
    • roamAlphaAPI.graph.type — "hosted" or "offline" (string)
    • roamAlphaAPI.graph.isEncrypted — whether the graph is encrypted (boolean)
  • roamAlphaAPI.platform — boolean properties (not functions) describing the client
    • roamAlphaAPI.platform.isDesktop — true in the Roam Desktop App
    • roamAlphaAPI.platform.isMobileApp — true in the Roam Mobile App
    • roamAlphaAPI.platform.isMobile — true on small screens; purely a screen-size check (media query max-width: 450px)
    • roamAlphaAPI.platform.isIOS — true on iPhone, iPad, or iPod
    • roamAlphaAPI.platform.isPC — true on a PC; useful for offering different shortcuts on PC vs Mac
    • roamAlphaAPI.platform.isTouchDevice — true on touch devices
  • roamAlphaAPI.depot — installed Roam Depot extensions
    • roamAlphaAPI.depot.getInstalledExtensions
      • Description::
        • A map of the extensions currently installed through Roam Depot or dev mode. Synchronous.
      • Parameters::
        • None
      • Returns::
        • Object of {ext-id: ext-map}; version is "DEV" for developer-loaded extensions

        • {"ccc+ccc-roam-pdf-2":
            {id: "ccc+ccc-roam-pdf-2",
             name: "Roam PDF Highlighter 2",
             enabled: false,
             version: "1"},
           ...}

  • roamAlphaAPI.constants — useful constants
    • roamAlphaAPI.constants.corsAnywhereProxyUrl
      • Description::
        • The url of a CORS-anywhere proxy hosted by the Roam team — useful when your extension queries an external API with CORS restrictions.
        • Instead of fetching url directly, fetch ${roamAlphaAPI.constants.corsAnywhereProxyUrl}/${url}.
        • To prevent misuse, the proxy only works for requests originating from https://roamresearch.com.
      • Example::

        • let urlToFetch = "https://google.com"
          
          await fetch(`${roamAlphaAPI.constants.corsAnywhereProxyUrl}/${urlToFetch}`)
            .then(a => a.text())
          // => "<!doctype html><html ...>" (the fetched page's body as text)

• Resources
  • Introduction to the Roam Alpha API by Put Your Left Foot In #Community #Article
  • Deep Dive Into Roam's Data Structure - Why Roam is Much More Than a Note Taking App by Zsolt Viczian #Community #Article
  • Datalog Queries for Roam Research by David Bieber #Community #Article
  • JavaScript Functions for Inserting Blocks in Roam by David Bieber #Community #Article
  • More Datalog Queries for Roam by David Bieber #Community #Article
  • Publishing Blog Posts from Roam Research Quickly and Automatically by David Bieber #Community #Article
• Examples
  • RoamJS Extensions from David Vargas #Open Source #JavaScript #TypeScript #roam/js — a suite of tools to extend popular workflows in Roam
  • Roam42 from RoamHacker, now maintained by David Vargas #Open Source #JavaScript #roam/js — a collection of power user tools for Roam
  • roam/sr from Adam Krivka #Open Source #JavaScript #TypeScript #roam/js — spaced repetition in Roam
  • pyroam from Adam Krivka #Open Source #JavaScript #TypeScript #roam/js — Python notebooks in Roam
  • LittleScripts from Adam Krivka #Open Source #JavaScript #roam/js — suite of small Roam scripts
  • roam-inter from Stian Haklev #Open Source #JavaScript #roam/js — cross-graph referencing prototype
  • roam-toolkit from Vlad Sitalo #Open Source #JavaScript #TypeScript #Browser Extension — a Chrome and Firefox extension toolkit to extend Roam
  • Fabricius from Ian Tay #Open Source #Python #Integration — an Anki plugin that bidirectionally syncs with Roam
• Change Log
  • See Roam Alpha API for the full historical change log.