splitbrain / remarkableapi

Docs and implementation of the reMarkable file sync API

reMarkable File Sync API

Goal of this project is to figure out and document the API which is used by the reMarkable Paper Tablet for syncing documents between the device, the desktop and mobile clients and the cloud service. A sample client implementation in PHP is also part of the project.

The API allows you to exchange files with your reMarkable tablet without the need to be in the same network or have physical access to the device. This makes it possible to create your own cloud services. Eg. tools that periodically sync files to other services like Dropbox or you could add automatic export to reMarkable in your tools.

API Documentation

I did my best to document what I cold figure out about the reMarkable File Sync API in the wiki: API Documentation

It should give you a good starting point when implementing your own client. You can also run the command line client in this repository (see below) with the --loglevel debug option to see the API calls in action.

Please feel free to extend and improve the documentation.

PHP API Client Library

This repository implements a PHP client to talk to the reMarkable file API. To use it in your projects, install via composer (currently only dev-master is available, versioning will be introduced later).

composer require splitbrain/remarkable-api

The library consists of three classes:

• splitbrain\ReMarkableAPI\ReMarkableAPI - this the main API interface, implementing the calls as described in the wiki
• splitbrain\ReMarkableAPI\ReMarkableFS - the reMarkable stores all info in a flat hierarchy with documents identified by UUIDs only. This class makes the items accessible by path names (using / as a directory separator)
• splitbrain\ReMarkableAPI\Client - this is just a thin wrapper around the Guzzle HTTP client which adds logging and handles authentication

After instantiating the ReMarkableAPI object, you need to call either register() or init() on it before you can issue any of the other calls. The first call will register your client through a 8 char code and return an API token. You need to save that token somewhere and pass it to init() for subsequent calls. Have a look at the command line client in remarkable.php to see how to use it all.

Command Line Client

To demonstrate the use of the PHP client library a command line script is included in the project. To use it, clone this project, then initialize the dependencies with composer:

composer install

Run the following to get a help screen on the usage:

./remarkable.php -h

Currently the following commands are implemented:

• register - register this application as a new device
• list - list all available files
• delete - delete a folder or document
• mkdir - create new folders
• upload - upload a new PDF
• download - download a Document

remarkableapi's Issues

Client error 401 response

I started getting this error:

$ ./remarkable.php list
☠ Client error: `GET https://document-storage-production-dot-remarkable-production.appspot.com/document-storage/json/2/docs` resulted in a `401 Unauthorized` response:
Serving request failed, Msg: invalid token: token contains an invalid number of segments: invalid token, Origin: invalid (truncated...)

This error might be related to the recent software update (release 2.7).

authentication endpoints respond in html

Hi,
I did few tests in the past days with these api but all of a sudden since yesterday the authentication endpoints started to respond in html instead of normal string responses.
I did my tests with Insomnia client, did not change the requests and everything was working fine but when I resumed my work yesterday I started to receive these html response (of which the rendered preview is empty).

The other endpoints seem to respond as usual.

Am I doing or did I do something wrong? Anyone else facing the same problem?

Thanks,
Nik

What is running at webapp-production-dot-remarkable-production.appspot.com?

Is this the production host for reMarkable AS infrastructure, or a third party proxy?

User token endpoint broken?

Has the API been updated by reMarkable?

I've been working on a Ruby API wrapper and am running into issues with user token endpoint. The device token endpoint is working correctly, but when I attempt to use that token to fetch / refresh a user token, I get a 400 with the message "You must connect a rM device in the webapp before you can use this service."

However, when I check the web interface, a new app has been created.

I also attempted to register a device with rmapi and am getting similar issues.

Ideas?

Issues with reMarkable API service

Do you also experience errors 500 when trying to use the API? I get a 500 for any request on https://document-storage-production-dot-remarkable-production.appspot.com. Do you know if the team at reMarkable upgraded their internal API and left this one behind?

Btw, their service manager returns the same service URL as before when queried:

$ curl "https://service-manager-production-dot-remarkable-production.appspot.com/service/json/1/document-storage"
{"Status":"OK","Host":"document-storage-production-dot-remarkable-production.appspot.com"}

more endpoints?

So far I only watched some limited network communication between the Windows-Client and the cloud service. I am pretty sure the mobile clients and the tablet itself use the same API, but they may use additional calls that I haven't seen, yet.

Any help with extending the docs would be welcome.

port API client library to other languages

I picked the language that I am most fluent with. But having a client in JavaScript or Python would also be cool.

Updating PDF doesn't sync with tablet

I'm trying to update a PDF document. When I send the new version of the pdf document I'm making sure to update the version and the ModifiedClient metadata. So far I can see the updated pdf on the mac and android apps. But the PDF on the remarkable tablet stays the same, even after trying manual sync on settings -> storage -> check cloud sync.

If I draw on the non updated PDF on the tablet. It brings back the old version on all devices.

Is there a way to make sure the tablet downloads the latest version as well? Has anybody has updated a PDF successfully?

I'm testing on the Remarkable 2 on version 2.6.2.75

update: Same Issue with version 2.7.0.51

Authentication failing

I want to use your Api Documentation but when I make a post request to https://my.remarkable.com/token/json/2/device/new
I am not able to get a token

Using Any API Method (e.g. ./remarkable.php list) Post `register` is Failing with 401

As the title suggests, I am unable to successfully call any endpoint - even after I call remarkable.php register <valid-registration-code>.

This may even be an issue with the overall usage of remarkable's endpoints, as I have been unable to call their endpoints directly.

Steps to reproduce:

1. Query for a new token:

   	GET: https://webapp-production-dot-remarkable-production.appspot.com/token/json/2/device/new`
   

   	 { 
   	      "code": "fuzzbuzz",
   	      "deviceDesc": "desktop-windows",
   	      "deviceID": "160022F6-EA84-42C7-B413-C1F5C6C3112F"
   	 }

2. Fetch a refresh token:

   	POST: https://webapp-production-dot-remarkable-production.appspot.com/token/json/2/user/new
   	--header 'Authorization: Bearer eyJ...'
   

3. Take the token from step 2, and validate the document endpoint:

   	GET: https://service-manager-production-dot-remarkable-production.appspot.com/service/json/1/document-storage?environment=production&group=auth0%7C5a68dc51cb30df3877a1d7c4&apiVer=2
   	--header 'Authorization: Bearer eyJ...'
   

   Which returns

   	{
   	      "Status": "OK",
   	      "Host": "document-storage-production-dot-remarkable-production.appspot.com"
   	}

4. Take this endpoint, and query the docs endpoint

   	GET: https://document-storage-production-dot-remarkable-production.appspot.com/document-storage/json/2/docs
   	--header 'Authorization: Bearer eyJ...'
   

   Which returns a 401: Unauthorized status code. What am I missing?

[q] how to get ReMarkable user ID

Hi, thanks for the detailed writeup!

I see that the token given out by rM is, in fact, a JWT token that has an "auth0-userid" field.
Is it a real user ID that's unique (and same) for every user?

For instance, mine is auth0|5f634d3c591dce00704a9822; I don't have a second rM account to see if it's different for other users.

url for one-time code changed to https://my.remarkable.com/connect/desktop

https://my.remarkable.com/connect/desktop

thanks

Make the HTTP library exchangable

Currently the library depends on guzzle which is pretty popular, but other projects might already use a different HTTP client. Would be nice to switch it to https://github.com/php-http/httplug

"Corrupt" files when uploading

If I try to upload a PDF document, the PHP script seems to do the job but the tablet claims the document is corrupt when it downloads from the cloud. The "list" however seems to show that the documents are stored in the cloud (although if no "to" was given on the upload, they are placed in a separate folder named with the UUID of the document). Happy to provide more details if desired.

Downloading (which is my main use case for your code) works very well indeed. Thank you!

Feature request: include metadata in download

I have scripts that use the metadata information to process the lines files from the tablet. It would be very helpful if the download, using the php script, could include the metadata file along with the others in the zip file created.

Deleting root-node gives issues

When uploading a file with the command like this:
remarkable.php upload /path1/path2/path3/filename.txt
the script correctly creates all the directories path1->path2->path3 with the name inside path3. This worked excellent.

But then I tried to delete "path1" directly, without deleting the sub-directories.
This delete is not "recursive", so the sub-directories seem to still exist, and then seems to lead to some corruption.
When I tried to run the "remarkable.php list"-command, it gave an error message about wrong metadata (Don't remember the exact error message)

But if I deleted all the path2, path3 and the file inside path3, the list-command worked again, and it seems that I cleaned everything up.

=>
Please consider one of two options:

1. Don't allow to delete directories that are not empty
2. Make the delete-command recursive to delete everything

Else, love the php-"app"!

Error during Authentication: "Failed to decode POST body as JSON"

Hey, I'm trying to authenticate a custom script of mine, but I'm having some issues. Here's my code

import requests

r = requests.post(
    "https://my.remarkable.com/token/json/2/device/new",
    data={
        "code": "<code>",
        "deviceDesc": "desktop-windows",
        "deviceID": "<uuid4>",
    },
)

When I run this I get a response with a code of 400 and the text "Failed to decode POST body as JSON".

Has the API changed?

Thanks for the awesome writeup.

Problem connecting as of today

I've been using your script since February with no problems at all. Works very well and is indispensable for me as I only have Linux systems.
As of this morning, I get the following error message when I try to use the script to even list the contents of the cloud:
☠ Client error: POST https://my.remarkable.com/token/user/new resulted in a 403 Forbidden response:
You have been signed out. Please update your app to log in again.
I get the same message if I try to "register" again. Any suggestions?
Thanks,
eric

Add License

There is no license for this repository, so it's not clear what is and isn't allowed with the code.

"Download" svg and PDF

Currently the download command only creates a zip file with raw .lines data. It would be cool if could also create SVGs and PDFs from it. This would require at least porting the existing lines to svg python code to PHP.

Error in the Authentication section of the writeup

Hi,

I'm using your great wiki section to implement my own cloud API client, and I came across a couple of errors in the authentication section, both to do with what you call the "refresh" function. Both of these things are correct in your PHP example but not in the documentation.

Firstly, it should be a POST, not a GET.

Second, it doesn't just update the token, it always produces a new token, and it's always necessary to do. You don't seem to be able to use the token from the first API call ("device" token, per the URL) as the Bearer for the storage API, you have to "refresh" it to get a second token ("user" token per the URL). It isn't a matter of expiration.

Thanks for the excellent writeup!

"Meatadata"

https://github.com/splitbrain/ReMarkableAPI/blob/master/src/RemarkableAPI.php#L244

Should this say metadata rather than meatadata, or is this a misspelling on the part of reMarkable?

Interfacing with reMarkable2 and trash items

The command line tool crashed with:

☠ Unknown ID trash. Inconsitent meta data

I think it's because I have deleted a file on the reMarkable2. It's a bit difficult to test, sorry about that.

The --loglevel debug shows:

-> GET https://document-storage-production-dot-remarkable-production.appspot.com/document-storage/json/2/docs
<- Status 200 5705 bytes
[
 ...
    {
        "ID": "c2a07c8d-2fa1-47ec-9522-b178f88f443e",
        "Version": 2,
        "Message": "",
        "Success": true,
        "BlobURLGet": "",
        "BlobURLGetExpires": "0001-01-01T00:00:00Z",
        "ModifiedClient": "2020-12-25T11:21:56.481481Z",
        "Type": "DocumentType",
        "VissibleName": "redacted.pdf",
        "CurrentPage": 0,
        "Bookmarked": false,
        "Parent": "trash"
    },
...
Exception caught in /home/ohad/dev/ReMarkableAPI/src/RemarkableFS.php:165
#0 /home/ohad/dev/ReMarkableAPI/src/RemarkableFS.php(176): splitbrain\RemarkableAPI\RemarkableFS->calcPath('trash')
#1 /home/ohad/dev/ReMarkableAPI/src/RemarkableFS.php(50): splitbrain\RemarkableAPI\RemarkableFS->calcPath('c2a07c8d-2fa1-4...')
#2 /home/ohad/dev/ReMarkableAPI/src/RemarkableFS.php(28): splitbrain\RemarkableAPI\RemarkableFS->refreshIndex()
#3 /home/ohad/dev/ReMarkableAPI/remarkable.php(117): splitbrain\RemarkableAPI\RemarkableFS->__construct(Object(splitbrain\RemarkableAPI\RemarkableAPI))
#4 /home/ohad/dev/ReMarkableAPI/remarkable.php(73): Remarkable->cmdList()
#5 /home/ohad/dev/ReMarkableAPI/vendor/splitbrain/php-cli/src/CLI.php(131): Remarkable->main(Object(splitbrain\phpcli\Options))
#6 /home/ohad/dev/ReMarkableAPI/remarkable.php(225): splitbrain\phpcli\CLI->run()
#7 {main}

change User agent

According to juruen/rmapi#23 (comment) you may now provide your own user agent string.

I guess it is about this...

ReMarkableAPI/src/RemarkableAPI.php

Line 69 in 5eafff7

'deviceDesc' => 'desktop-windows', # we have to lie here