# Roam Backend API Change Log

- [[August 25th, 2026]]
  - [[August 25th, 2026]]
    - Some behavioral changes of our delete actions (in both our frontend and backend APIs)
      - **1. delete_block(uidOfAPage) and delete_page(uidOfABlock) now fails with an error message instead of silently succeeding**
        - what was happening in these cases was that the promise was resolving but the actual deletion was not taking place
        - this is the one that could possibly break code, so please check
        - however, we made this change because it is slightly more correct. And well, for agents … It makes a lot of sense for people to instruct agents to be more liberal with delete_block compared to delete_page, but that is moot if both fns can delete blocks as well as pages. Hence the change
      - **change to deleteBlock and deletePage return values in both frontend and backend APIs**
        - these previously did not signal if the block/page that was sent for deletion did not exist. The promise would just succeed (with value undefined) and backend would return a 200 with empty body.
        - We changed it so that Successful deletion returns {"deleted":true} instead of an empty body, while a missing target would return {"deleted":false,"reason":"not-found"} with success/HTTP 200.
        - Just to be clear, we intentionally did not make this return an error, it still counts as a success (both in the promise sense in the frontend api and in the 200 OK sense in the backend api). We did this just in cases anyone’s code was depending on the fact that deleteBlock/deletePage on non-existing stuff did not throw. So, hopefully no-one’s code breaks due to this
      - Sorry for the changes we had to make. We try to make as few breaking changes to our APIs as possible, including changes to undocumented behavior, but the old wrong-type behavior could silently lie or perform the wrong kind of deletion and needed to be made consistent.
      - If this causes a problem in an extension or integration, please let us know. We’ll help investigate and expedite any necessary compatibility fix. Thanks!
- [[April 30th, 2024]]
  - Releasing `pull-many` endpoint: `/api/graph/{graph-name}/pull-many` (POST)
  - Proper documentation for all error codes: **What does response look like?** (with **HTTP status codes**)
- [[March 7th, 2024]]
  - Better error reporting for `batch-actions` write requests
    - We're now returning [`num-actions-successfully-transacted-before-failure`](the error body's `num-actions-successfully-transacted-before-failure` tells you how many succeeded, alongside `message` and `batch-error-message`) in the `response.data` so you can figure out which action in your request failed
      - > the error body's `num-actions-successfully-transacted-before-failure` tells you how many succeeded, alongside `message` and `batch-error-message`
    - More more info and background, please read: if an action fails, the actions before it stay transacted and the rest are skipped
- [[July 29th, 2023]]
  - For the `create-block` and `move-block` write actions, you can pass a different parameter `page-title`. If you use this instead of [`parent-uid`](`parent-uid` (string) — uid of the new parent block or page), it will create the page if it does not exist already
    - `location`
      - `page-title`
        - You can use this if you want the location of the block to be a direct child of a page. 
        - Can either be 
          - a string corresponding to page's title
            - example: 
              "location": {"page-title": **"Roam Backend API (Beta)"**}
          - or
          - a map of the form `{"daily-note-page": "MM-DD-YYYY"}`.
            - **(Use this for Daily Notes Pages)**
            - example: 
              "location": {"page-title": **{"daily-note-page": "07-29-2023"}** }
- [[November 23rd, 2022]]
  - Breaking change for format of response for pulls (and for queries with pull params)
    - Previously, response.body looked like the following
      - ![](https://firebasestorage.googleapis.com/v0/b/firescript-577a2.appspot.com/o/imgs%2Fapp%2Fdeveloper-documentation%2F8jf_dApP6-.png?alt=media&token=b7dd0ec1-9d37-489b-8536-60c7be9b2157)
    - Now it looks like
      - ![](https://firebasestorage.googleapis.com/v0/b/firescript-577a2.appspot.com/o/imgs%2Fapp%2Fdeveloper-documentation%2FrF0B6tKOc3.png?alt=media&token=937181c0-03c8-4be9-bc89-c4560dd84974)
    - The change therefore is that keys inside of the "result" have ":" at the beginning
    - The rationale for this change is to minimize the number of different formats across frontend and the backend, a concern which was raised by @David Vargas here: https://roamresearch.slack.com/archives/C02TMKXNVS6/p1663773904953259
      - ![](https://firebasestorage.googleapis.com/v0/b/firescript-577a2.appspot.com/o/imgs%2Fapp%2Fdeveloper-documentation%2FQjS_ERpIUy.png?alt=media&token=9f6990e3-d109-474f-8506-8aec79f39f5d)
    - Fixing this in your code should be pretty simple - in the places where you're handling the "result" of query and/or pull, you want to change the keys of type "namespace/property" to ":namespace/property"
    - Sorry for the inconvenience caused!
  - Better (More secure) API Tokens
    - [[Screenshot]]
      - ![](https://firebasestorage.googleapis.com/v0/b/firescript-577a2.appspot.com/o/imgs%2Fapp%2Fdeveloper-documentation%2FHfSSrPx1_U.png?alt=media&token=5f40ddc8-4cfa-4a8c-89a8-748f65bcb80c)
    - Now, the only time you can get the secret token is when you're creating the token. you cannot copy it later
      - this prevents others (malicious code/malicious person who somehow got access to your machine one time) from being able to copy your long lived tokens
      - Internally, instead of storing the secret token, Roam only stores the hashed value of the tokens. So, the secret token can never be recovered.
    - However, this does mean that this is a new token format. So, please remove your old tokens and create new ones (the old ones will stop working on [[December 1st, 2022]])
    - way to get an API token is same as before: You can create and edit roam-graph-tokens from a new section "API tokens" in the "Graph" tab in the Settings, Please just make you do ... > Check for updates
  - **Graph-specific Usage Quotas**