Roam Research Docs · Developer documentation

Roam Backend API

markdown version · view in Roam Research

• Description
  • An HTTP API for reading and writing your Roam graphs from your own code
  • Encrypted graphs are not supported (and will not be in the future)
    • If you want to capture to both unencrypted & encrypted graphs, please checkout the Roam Append API instead
  • Postman Public workspace to play around with
    • https://www.postman.com/roamresearch/workspace/roam-research-backend-api/collection/27948971-ac6bd2a2-c0f0-4259-abc1-78bde0a01958
      • A walkthrough Loom video: https://www.loom.com/share/2f14c2331b65439a81632b9b94400160
  • Please report any issues in the #developers channel in the Roam Slack or via email to [[email protected]](mailto:[email protected])
• SDKs
  • Please prefer using our sdks
    • typescript
    • clojure
    • python
    • java
    • rust
• Authentication
  • Requests to the API use graph specific tokens for authentication
  • You can only get/create these if you own the graph i.e. if you're the admin of the graph
  • These start with roam-graph-token-
  • You can create and edit roam-graph-tokens from a new section "API tokens" in the "Graph" tab in the Settings
    • 
  • How to pass the tokens in the request?
    • pass them in the X-Authorization header
      • you can use the Authorization header too (would be more secure) but you have to make sure that your code/library handles redirect properly and passes the authorization header when redirect has been followed (and the latter is generally not default behavior for most network libraries)
    • Make sure they're prefixed with a Bearer
    • An example
      • Bearer roam-graph-token-t_OjqgIAH1JZphzP4HxjJNad55lLFKpsqIM7x3bW
  • To use the Backend API, you need a roam-graph-token with either a "read+edit" or a "read-only" role
    • roam-graph-tokens with "append-only" roles can only be used with the Roam Append API
  • A cURL request example

    • curl -X POST "https://api.roamresearch.com/api/graph/MY-GRAPH/q" --location-trusted \
      -H "Accept: application/json" \
      -H "X-Authorization: Bearer roam-graph-token-XXX" \
      -H "Content-Type: application/json" \
      -d "{\"query\": \"[:find ?block-uid ?block-str :in \$ ?search-string :where [?b :block/uid ?block-uid] [?b :block/string ?block-str] [(clojure.string/includes? ?block-str ?search-string)]]\", \"args\": [\"apple\"]}"
      # =>
      # {"result": [["hjt3Bwqp2", "apple pie recipe"], ["e1Xp7HELP", "Bought apples at the farmers market"]]}

    • Some important points
      • --location-trusted is required because your request is redirected to the actual machine doing the work.
        • There is a sharding mechanism in place (such that different graphs run on different machines)
        • https://api.roamresearch.com/ abstracts away this from the developer point of view, by redirecting messages to the actual machine doing the work
      • As mentioned earlier in, you have to make sure that the tokens are prefixed with a Bearer and are passed in the Authorization header
• Reference
  • Endpoint base url: https://api.roamresearch.com/
  • Read requests (q, pull, pull-many) have a 20 second time limit. If a request exceeds it, it fails with a 500 whose message contains "took too long to run"
  • API routes
    • /api/graph/{graph-name}/q (POST)
      • Description::
        • Runs a datalog query against the graph and returns the matching results
        • The backend version of roamAlphaAPI.data.q
        • parameters are passed as a JSON request body
      • Parameters::
        • query (string, required) — the datalog query, as an EDN string
        • args (array, optional) — inputs for the query, bound in order to the extra :in variables (the ones after $)
      • Return::
        • 200 with body {"result": [...]} — the array of query results
          • maps produced by pull expressions in the query have keys prefixed with ":", e.g. ":block/uid"
        • for error responses, see What does response look like? (with HTTP status codes)
        • sample output structure
          • 
      • Example::
        • Finds the uid and string of every block whose text contains "apple"
        • Request body (JSON)

          • {
              "query": "[:find ?block-uid ?block-str :in $ ?search-string :where [?b :block/uid ?block-uid] [?b :block/string ?block-str] [(clojure.string/includes? ?block-str ?search-string)]]",
              "args": ["apple"]
            }

        • cURL request

          • curl -X POST "https://api.roamresearch.com/api/graph/MY-GRAPH/q" --location-trusted \
            -H "Accept: application/json" \
            -H "X-Authorization: Bearer roam-graph-token-XXX" \
            -H "Content-Type: application/json" \
            -d "{\"query\": \"[:find ?block-uid ?block-str :in \$ ?search-string :where [?b :block/uid ?block-uid] [?b :block/string ?block-str] [(clojure.string/includes? ?block-str ?search-string)]]\", \"args\": [\"apple\"]}"
            # =>
            # {"result": [["hjt3Bwqp2", "apple pie recipe"], ["e1Xp7HELP", "Bought apples at the farmers market"]]}

        • TypeScript — using the official SDK

          • import { initializeGraph, q } from "@roam-research/roam-api-sdk";
            
            const graph = initializeGraph({
              token: "roam-graph-token-XXX",
              graph: "MY-GRAPH",
            });
            
            const result = await q(
              graph,
              "[:find ?block-uid ?block-str :in $ ?search-string :where [?b :block/uid ?block-uid] [?b :block/string ?block-str] [(clojure.string/includes? ?block-str ?search-string)]]",
              ["apple"]
            );
            // => [["hjt3Bwqp2", "apple pie recipe"], ["e1Xp7HELP", "Bought apples at the farmers market"]]

          • the SDK resolves to the result value directly and throws on error responses
    • /api/graph/{graph-name}/pull (POST)
      • Description::
        • Pulls the requested attributes for one entity, given a pull selector and an entity id
        • The backend version of roamAlphaAPI.data.pull
        • parameters are passed as a JSON request body
      • Parameters::
        • selector (string, required) — the pull pattern, as an EDN string
        • eid (string, required) — the entity to pull, as an EDN string: an entity id number or a lookup ref like [:block/uid "abc123xyz"]
      • Return::
        • 200 with body {"result": {...}} — the pulled map, containing only the attributes the entity actually has
          • keys are prefixed with ":", e.g. ":block/uid"
        • for error responses, see What does response look like? (with HTTP status codes)
        • sample output structure
          • 
      • Example::
        • Pulls a daily note page's uid and title, plus the uid and string of its children and the title/string/uid of everything they reference
        • Request body (JSON)

          • {
              "eid": "[:block/uid \"08-30-2022\"]",
              "selector": "[:block/uid :node/title :block/string {:block/children [:block/uid :block/string]} {:block/refs [:node/title :block/string :block/uid]}]"
            }

        • cURL request

          • curl -X POST "https://api.roamresearch.com/api/graph/MY-GRAPH/pull" --location-trusted \
            -H "Accept: application/json" \
            -H "X-Authorization: Bearer roam-graph-token-XXX" \
            -H "Content-Type: application/json" \
            -d "{\"eid\": \"[:block/uid \\\"08-30-2022\\\"]\", \"selector\": \"[:block/uid :node/title :block/string {:block/children [:block/uid :block/string]} {:block/refs [:node/title :block/string :block/uid]}]\"}"
            # =>
            # {"result": {":block/uid": "08-30-2022", ":node/title": "August 30th, 2022", ":block/children": [{":block/uid": "hjt3Bwqp2", ":block/string": "apple pie recipe"}, ...]}}

        • TypeScript — using the official SDK

          • import { initializeGraph, pull } from "@roam-research/roam-api-sdk";
            
            const graph = initializeGraph({
              token: "roam-graph-token-XXX",
              graph: "MY-GRAPH",
            });
            
            const result = await pull(
              graph,
              "[:block/uid :node/title :block/string {:block/children [:block/uid :block/string]} {:block/refs [:node/title :block/string :block/uid]}]",
              '[:block/uid "08-30-2022"]'
            );
            // =>
            // {":block/uid": "08-30-2022",
            //  ":node/title": "August 30th, 2022",
            //  ":block/children": [{":block/uid": "hjt3Bwqp2", ":block/string": "apple pie recipe"}, ...]}

          • the SDK resolves to the result value directly and throws on error responses
    • /api/graph/{graph-name}/pull-many (POST)
      • Description::
        • Pulls the requested attributes for multiple entities in one request — the many-entity version of /api/graph/{graph-name}/pull (POST)
        • The backend version of roamAlphaAPI.data.pull_many
        • parameters are passed as a JSON request body
      • Parameters::
        • selector (string, required) — the pull pattern, as an EDN string, applied to every eid
        • eids (required) — the entities to pull
          • either one EDN string containing a list of eids (as in the example), or a JSON array whose elements are individual eids
      • Return::
        • 200 with body {"result": [...]} — an array of pulled maps, one per eid, in the same order
          • keys are prefixed with ":", e.g. ":block/uid"
        • for error responses, see What does response look like? (with HTTP status codes)
      • Example::
        • Pulls the uid, title, and children of two daily note pages in one request
        • Request body (JSON)

          • {
              "eids": "[[:block/uid \"08-30-2022\"] [:block/uid \"08-31-2022\"]]",
              "selector": "[:block/uid :node/title {:block/children [:block/uid :block/string]}]"
            }

        • cURL request

          • curl -X POST "https://api.roamresearch.com/api/graph/MY-GRAPH/pull-many" --location-trusted \
            -H "Accept: application/json" \
            -H "X-Authorization: Bearer roam-graph-token-XXX" \
            -H "Content-Type: application/json" \
            -d "{\"eids\": \"[[:block/uid \\\"08-30-2022\\\"] [:block/uid \\\"08-31-2022\\\"]]\", \"selector\": \"[:block/uid :node/title {:block/children [:block/uid :block/string]}]\"}"
            # =>
            # {"result": [{":block/uid": "08-30-2022", ":node/title": "August 30th, 2022", ":block/children": [...]}, {":block/uid": "08-31-2022", ":node/title": "August 31st, 2022", ":block/children": [...]}]}

        • TypeScript — using the official SDK

          • import { initializeGraph, pull_many } from "@roam-research/roam-api-sdk";
            
            const graph = initializeGraph({
              token: "roam-graph-token-XXX",
              graph: "MY-GRAPH",
            });
            
            const result = await pull_many(
              graph,
              "[:block/uid :node/title {:block/children [:block/uid :block/string]}]",
              '[[:block/uid "08-30-2022"] [:block/uid "08-31-2022"]]'
            );
            // =>
            // [{":block/uid": "08-30-2022", ":node/title": "August 30th, 2022", ":block/children": [...]},
            //  {":block/uid": "08-31-2022", ":node/title": "August 31st, 2022", ":block/children": [...]}]

          • the SDK resolves to the result value directly and throws on error responses
    • /api/graph/{graph-name}/search (POST)
      • Description::
        • Ranked text search over page titles and block strings — the same search that powers the app's "Find or Create Page" search box
        • results are ranked: exact title matches first, then substring matches, then multi-word (spread) matches; pages come before blocks, and newer entities win ties
        • parameters are passed as a JSON request body
      • Parameters::
        • search-str (string, required) — the text to search for
          • search-string is accepted as an alias
        • search-pages (boolean, optional, default true) — include page results
        • search-blocks (boolean, optional, default true) — include block results
        • hide-code-blocks (boolean, optional, default false) — exclude code blocks from block results
        • limit (number, optional, default 300, max 1000) — maximum number of results
        • pull (string, optional) — pull pattern applied to each result, as an EDN string; default [:block/string :node/title :block/uid]
      • Return::
        • 200 with body {"result": [...], "search-str": "..."} — result is an array of pulled maps
          • keys are prefixed with ":", e.g. ":block/uid"
        • for error responses, see What does response look like? (with HTTP status codes)
      • Example::
        • Searches pages and blocks for "apple"
        • Request body (JSON)

          • {
              "search-str": "apple",
              "hide-code-blocks": true,
              "limit": 20
            }

        • cURL request

          • curl -X POST "https://api.roamresearch.com/api/graph/MY-GRAPH/search" --location-trusted \
            -H "Accept: application/json" \
            -H "X-Authorization: Bearer roam-graph-token-XXX" \
            -H "Content-Type: application/json" \
            -d "{\"search-str\": \"apple\", \"hide-code-blocks\": true, \"limit\": 20}"
            # =>
            # {"result": [{":node/title": "apple", ":block/uid": "x83-jseuA"}, {":block/string": "apple pie recipe", ":block/uid": "hjt3Bwqp2"}], "search-str": "apple"}

        • TypeScript — plain fetch (this route is not in the SDK yet)

          • const response = await fetch("https://api.roamresearch.com/api/graph/MY-GRAPH/search", {
              method: "POST",
              headers: {
                "Content-Type": "application/json",
                "X-Authorization": "Bearer roam-graph-token-XXX",
              },
              body: JSON.stringify({ "search-str": "apple", "hide-code-blocks": true, "limit": 20 }),
            });
            const { result } = await response.json();
            // => [{":node/title": "apple", ":block/uid": "x83-jseuA"}, {":block/string": "apple pie recipe", ":block/uid": "hjt3Bwqp2"}]

    • /api/graph/{graph-name}/roam-query (POST)
      • Description::
        • Runs a Roam query — the same syntax used in {{[[query]]: ...}} blocks — and returns the matching blocks and pages
        • The backend version of roamAlphaAPI.data.roamQuery
          • unlike the frontend version, there are no grouping or sorting options — results come back as a flat array
        • blocks that themselves contain a query are excluded from the results (matching the app's behavior)
        • parameters are passed as a JSON request body
      • Parameters::
        • query (string, required) — the query string, e.g. {and: [[project]] [[active]]}
        • current-date (string, required) — the client's current date, as "yyyy-MM-dd"
          • used as the reference date for {between: } clauses; required even if the query has none
        • block-uid (string, optional) — uid of an existing block to treat as the query's location
          • if that block is on a daily note page, the page's date is used for {between: } clauses instead of current-date
          • the block itself is excluded from the results
        • limit (number, optional) — maximum number of results
        • pull (string, optional) — pull pattern applied to each result, as an EDN string; default [:block/string :node/title :block/uid]
      • Return::
        • 200 with body {"result": [...]} — an array of pulled maps
          • keys are prefixed with ":", e.g. ":block/uid"
        • for error responses, see What does response look like? (with HTTP status codes)
      • Example::
        • Finds everything tagged with both [[project]] and [[active]]
        • Request body (JSON)

          • {
              "query": "{and: [[project]] [[active]]}",
              "current-date": "2023-07-29",
              "limit": 20
            }

        • cURL request

          • curl -X POST "https://api.roamresearch.com/api/graph/MY-GRAPH/roam-query" --location-trusted \
            -H "Accept: application/json" \
            -H "X-Authorization: Bearer roam-graph-token-XXX" \
            -H "Content-Type: application/json" \
            -d "{\"query\": \"{and: [[project]] [[active]]}\", \"current-date\": \"2023-07-29\", \"limit\": 20}"
            # =>
            # {"result": [{":block/string": "kick off [[project]] review #active", ":block/uid": "hjt3Bwqp2"}, ...]}

        • TypeScript — plain fetch (this route is not in the SDK yet)

          • const response = await fetch("https://api.roamresearch.com/api/graph/MY-GRAPH/roam-query", {
              method: "POST",
              headers: {
                "Content-Type": "application/json",
                "X-Authorization": "Bearer roam-graph-token-XXX",
              },
              body: JSON.stringify({
                "query": "{and: [[project]] [[active]]}",
                "current-date": "2023-07-29",
                "limit": 20,
              }),
            });
            const { result } = await response.json();
            // => [{":block/string": "kick off [[project]] review #active", ":block/uid": "hjt3Bwqp2"}, ...]

    • /api/graph/{graph-name}/write (POST)
      • Description::
        • A single endpoint for all write actions — pass the action's name as the action key in the JSON request body, alongside that action's own parameters
        • each available action, with its full parameters, is documented below
        • to run several actions in one request, use batch-actions
      • Parameters::
        • action (string, required) — one of: create-block, move-block, update-block, delete-block, create-page, update-page, delete-page, batch-actions
        • the rest of the body is the chosen action's own parameters — written out under each action below
      • Actions::
        • create-block
          • Description::
            • creates a new block at the given location
            • equivalent to roamAlphaAPI.data.block.create
          • Parameters::
            • location (map, required)
              • parent-uid (string) — uid of the parent block or page the new block goes under
              • page-title — target a page by title instead of uid; creates the page if it does not exist
                • either a title string, or a map {"daily-note-page": "MM-DD-YYYY"} for daily note pages
              • pass exactly one of parent-uid or page-title
              • order (number | "first" | "last", required) — position among the parent's children
            • block (map, required)
              • string (string, required) — the block's text
              • uid (string, optional) — uid for the new block, autogenerated if omitted
              • open (boolean, optional, default true) — expanded or collapsed
              • heading (number, optional) — 0, 1, 2, or 3, where 0 means normal text (no heading)
              • text-align (string, optional) — left, center, right, or justify
              • children-view-type (string, optional) — bullet, numbered, or document
        • move-block
          • Description::
            • moves an existing block (together with its children) to a new location
            • equivalent to roamAlphaAPI.data.block.move
          • Parameters::
            • block (map, required)
              • uid (string, required) — the block to move
            • location (map, required)
              • parent-uid (string) — uid of the new parent block or page
              • page-title — target a page by title instead of uid; creates the page if it does not exist
                • either a title string, or a map {"daily-note-page": "MM-DD-YYYY"} for daily note pages
              • pass exactly one of parent-uid or page-title
              • order (number | "first" | "last", required) — position among the new parent's children
        • update-block
          • Description::
            • updates a block's text and/or display properties; only the keys you pass are changed
            • equivalent to roamAlphaAPI.data.block.update
          • Parameters::
            • block (map, required)
              • uid (string, required) — the block to update
              • string (string, optional) — the new text
              • open (boolean, optional) — expanded or collapsed
              • heading (number, optional) — 0, 1, 2, or 3, where 0 means normal text (no heading)
              • text-align (string, optional) — left, center, right, or justify
              • children-view-type (string, optional) — bullet, numbered, or document
        • delete-block
          • Description::
            • deletes a block and all of its children
            • equivalent to roamAlphaAPI.data.block.delete
          • Parameters::
            • block (map, required)
              • uid (string, required) — the block to delete
        • create-page
          • Description::
            • creates a new page
            • equivalent to roamAlphaAPI.data.page.create
          • Parameters::
            • page (map, required)
              • title (string, required) — the page's title
              • uid (string, optional) — uid for the new page, autogenerated if omitted
              • children-view-type (string, optional) — bullet, numbered, or document
        • update-page
          • Description::
            • renames a page and/or updates its display properties; only the keys you pass are changed
            • equivalent to roamAlphaAPI.data.page.update
          • Parameters::
            • page (map, required)
              • uid (string, required) — the page to update
              • title (string, optional) — the new title
              • children-view-type (string, optional) — bullet, numbered, or document
        • delete-page
          • Description::
            • deletes a page and all of its blocks
            • equivalent to roamAlphaAPI.data.page.delete
          • Parameters::
            • page (map, required)
              • uid (string, required) — the page to delete
        • batch-actions
          • Description::
            • runs several write actions, in order, in one request
            • tempids: in place of real uids, you can pass negative integers in uid and parent-uid values and reuse them across the batch — e.g. create a page with uid -1, then create blocks under parent-uid -1
              • the response maps each tempid to the real uid it was assigned: {"tempids-to-uids": {"-1": "EBiw8LzPb"}}
            • if an action fails, the actions before it stay transacted and the rest are skipped
              • the error body's num-actions-successfully-transacted-before-failure tells you how many succeeded, alongside message and batch-error-message
          • Parameters::
            • actions (array, required) — a list of action maps, each shaped exactly like the individual actions above
              • cannot contain another batch-actions
      • Return::
        • 200 with an empty body — the write completed
          • exception: batch-actions responds with {"tempids-to-uids": {...}} when tempids are used
        • for error responses, see What does response look like? (with HTTP status codes)
      • Example::
        • A full create-block request — creates a new block as the last child of the September 28th, 2022 daily note page
          • Request body (JSON)

            • {
                "action": "create-block",
                "location": {
                    "parent-uid": "09-28-2022",
                    "order": "last"
                },
                "block": {
                    "string": "new block created via the backend"
                }
              }

          • cURL request

            • curl -X POST "https://api.roamresearch.com/api/graph/MY-GRAPH/write" --location-trusted \
              -H "Accept: application/json" \
              -H "X-Authorization: Bearer roam-graph-token-XXX" \
              -H "Content-Type: application/json" \
              -d "{\"action\":\"create-block\",\"location\":{\"parent-uid\":\"09-28-2022\",\"order\":\"last\"},\"block\":{\"string\":\"new block created via the backend\"}}"
              # => 200 OK (empty body)

          • TypeScript — using the official SDK

            • import { initializeGraph, createBlock } from "@roam-research/roam-api-sdk";
              
              const graph = initializeGraph({
                token: "roam-graph-token-XXX",
                graph: "MY-GRAPH",
              });
              
              const ok = await createBlock(graph, {
                location: { "parent-uid": "09-28-2022", order: "last" },
                block: { string: "new block created via the backend" },
              });
              // => true

            • the SDK has one function per action (createBlock, moveBlock, updateBlock, deleteBlock, createPage, updatePage, deletePage) — each fills in action for you and resolves to true on success
        • A single batch-actions request that uses every action — creates pages and blocks (reusing tempids), captures to a daily note page, then moves, updates, and deletes

          • {
              "action": "batch-actions",
              "actions": [
                {
                  "action": "create-page",
                  "page": { "title": "Batch action test page", "uid": -1 }
                },
                {
                  "action": "create-block",
                  "location": { "parent-uid": -1, "order": "last" },
                  "block": { "string": "First" }
                },
                {
                  "action": "create-block",
                  "location": { "parent-uid": -1, "order": "last" },
                  "block": { "string": "Second", "uid": -2, "heading": 2, "open": false }
                },
                {
                  "action": "create-block",
                  "location": { "page-title": {"daily-note-page": "07-29-2023"}, "order": "first" },
                  "block": { "string": "captured to a daily note page" }
                },
                {
                  "action": "move-block",
                  "block": { "uid": -2 },
                  "location": { "parent-uid": -1, "order": 0 }
                },
                {
                  "action": "update-block",
                  "block": { "uid": -2, "string": "Second (updated)", "heading": 0 }
                },
                {
                  "action": "create-page",
                  "page": { "title": "Scratch page", "uid": -3, "children-view-type": "numbered" }
                },
                {
                  "action": "update-page",
                  "page": { "uid": -3, "title": "Scratch page (renamed)" }
                },
                {
                  "action": "delete-page",
                  "page": { "uid": -3 }
                },
                {
                  "action": "delete-block",
                  "block": { "uid": -2 }
                }
              ]
            }
            // =>
            // {"tempids-to-uids": {"-1": "EBiw8LzPb", "-2": "X4DelKvsP", "-3": "mR7wJq2Lc"}}

  • What does response look like? (with HTTP status codes)
    • (If you're building an integration, be sure to implement at least the response codes below)
    • 200 OK #important
      • if successful
      • If q request , see sample output structure
      • if pull request, see sample output structure
      • if write request, 200 status code in response means all done
    • 308 PERMANENT REDIRECT
      • the API endpoint for backend API i.e. Endpoint base url: https://api.roamresearch.com/ actually returns the actual URL you want to hit for your read/write requests
      • In many cases, the network tool/library you're using will follow the redirect without additional config on your side
    • 4XX BAD REQUEST (with error message specifying what went wrong)
      • 400 BAD REQUEST #important
        • this error code is returned in many cases. So, please checkout response body's message value
        • some cases
          • When input format error / invalid parameter values
            • Example:: if we pass "order": 2 in an update-block request
              • 
          • If write request fails
            • For batch-actions especially, You have to carefully handle this (to know how many requests suceeded)
              • Please checkout if an action fails, the actions before it stay transacted and the rest are skipped
                • if an action fails, the actions before it stay transacted and the rest are skipped
                  • the error body's num-actions-successfully-transacted-before-failure tells you how many succeeded, alongside message and batch-error-message
          • When one is trying to use an Encrypted graph
            • Encrypted graphs are NOT supported by the Roam Backend API
          • When no graph name in request, or invalid graph name
          • If invalid write action
          • When token cannot be verified or improperly formatted
      • 401 UNAUTHORIZED #important
        • If one is unauthorized or if one does not have required access to the graph (read/write)
        • Please note that in some cases, When token cannot be verified or improperly formatted returns a 400 BAD REQUEST #important
          • this is a bug on our part, but changing it now could break existing integrations, so leaving it like this for this version of the API
      • 404 NOT FOUND
        • If the API route you're calling is not found
          • i.e. if you request an API route NOT in API routes
      • 429 TOO MANY REQUESTS #important
        • When you run into the per graph limit/quota. See Graph-specific Usage Quotas
          • Quotas are per minute, per graph, and depend on the type of request
    • 500 INTERNAL SERVER ERROR #important ( default fallback code for errors )
      • default fallback code for errors
        • So, please checkout response body's message value
      • If you get this & message does not make clarify, please contact us at [email protected] or in the #developers channel in the Roam Slack
      • Some cases
        • If message contains "took too long to run", then the query/pull request is running into our time limit (20 seconds for now). In this case, you want to request less data or add limits.
          • You might want to add limited recursion limits to pull specs: https://docs.datomic.com/pro/query/pull.html#recursive-specifications
    • 503 SERVICE UNAVAILABLE #important
      • if graph is not ready for requests yet or is unavailable at the moment. If you get this, please try again in a bit
        • a common cause: the graph isn’t loaded on our servers yet (brand new, or not accessed in a while) — your request triggers the load, so retrying after a few seconds usually succeeds
      • Example
        • 
  • Graph-specific Usage Quotas
    • Quotas are per minute, per graph, and depend on the type of request
      • 500 requests/minute for pull and pull-many requests
      • 200 requests/minute (shared) for q, search, and roam-query requests
      • 100 requests/minute for write requests
        • a batch-actions request counts as the number of actions in it, not as 1 request
      • If you run into the limits regularly even when using the strategies mentioned below, please let us know
    • When you run into the limit/quota, server will respond with a 429 TOO MANY REQUESTS #important
      • so please account for that in your code by using timeouts etc
    • Batch writes save round trips but do not reduce quota usage — a batch-actions request counts as the number of actions in it
• FAQ::
  • Q:: How do I do the --location-trusted if I'm using something other than cURL?
    • The two main things
      • You want the request library to automatically follow redirects
        • this is generally the default in most libraries and applications
      • You want the authorization header to be passed when redirect has been followed
        • This is generally not default behavior, so this will probably need extra configuration
        • another approach would be to use the X-Authorization header instead of the Authorization header
          • pass them in the X-Authorization header
            • you can use the Authorization header too (would be more secure) but you have to make sure that your code/library handles redirect properly and passes the authorization header when redirect has been followed (and the latter is generally not default behavior for most network libraries)
    • Examples
      • Python
        • some examples, courtesy of Matt Vogel: https://gist.github.com/8bitgentleman/75561ac116b5b925fd58ff595389d591
      • Postman client: https://www.postman.com/
        • Postman already fulfills criteria 1: it automatically follows redirects
          • If it doesn't for you, you have to go to the settings and enable "Automatically follow redirects"
            • 
        • For criteria 2 i..e passing authorization header on redirect, that is a per "request" setting and it can be enabled in the request level settings > Follow Authorization Header
          • If you don't do this, you will get a "message": "You are not authenticated" response from the server, which is super confusing unless you go to the console and really look at the requests
          • 
  • Q:: I can't get the request to work using fetch or equivalent in my roam/js (i.e. in the browser)
    • A:: This works now — you can fetch directly from the browser. Just make sure you pass your token in the X-Authorization header, not Authorization (browsers drop the Authorization header when following the cross-origin redirect)
      • From inside Roam, you can also use roamAlphaAPI.data.backend.q — a client-side wrapper that makes this same request for you
• Change Log
  • Roam Backend API Change Log