rMapy

https://github.com/subutux/rmapy
Admin
rMapy is an unofficial Remarkable Cloud API client written in Python that enables developers to...
Tokens:9,877
Snippets:75
Trust Score:-
License:MIT
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install rmapy using pip

Source: https://context7.com/subutux/rmapy/llms.txt

Install the rmapy library using pip. This is the first step to using the client.

```bash
pip install rmapy
```

--------------------------------

### Register Device and Authenticate Client

Source: https://context7.com/subutux/rmapy/llms.txt

Registers a new device with Remarkable Cloud using a one-time code. This is a one-time setup per device. The device token is stored locally for future use.

```python
from rmapy.api import Client

# Create a new client instance
rmapy = Client()

# Check if already authenticated (returns False for new devices)
print(rmapy.is_auth())  # False

# Register the device with a one-time code from https://my.remarkable.com/device/desktop/connect
# Replace 'your_code' with the actual code from the website
rmapy.register_device("fkgzzklrs")

# Renew the user token for this session
rmapy.renew_token()

# Verify authentication is complete
print(rmapy.is_auth())  # True
```

--------------------------------

### Get and Filter Collection Items

Source: https://github.com/subutux/rmapy/blob/master/docs/source/quickstart.md

Retrieves all metadata items from the collection and filters them to find folders. The reMarkable file system is flat in the cloud.

```python
>>> collection = rmapy.get_meta_items()
>>> collection
<rmapy.collections.Collection object at 0x7fc4718e1ed0>
>>> from rmapy.folder import Folder
>>> # Get all the folders. Note that the fs of Remarkable is flat in the cloud
>>> folders = [ f for f in collection if isinstance(f, Folder) ]
>>> folders
[<rmapy.folder.Folder 028400f5-b258-4563-bf5d-9a47c314668c>, <rmapy.folder.Folder 06a36729-f91e-47da-b334-dc088c1e73d2>, ...]
```

--------------------------------

### Get Root Folders

Source: https://github.com/subutux/rmapy/blob/master/docs/source/quickstart.md

Filters the list of folders to identify and retrieve the root-level folders.

```python
>>> # Get the root folders
>>> root = [ f for f in folders if f.Parent == "" ]
>>> root
[<rmapy.folder.Folder 028400f5-b258-4563-bf5d-9a47c314668c>, <rmapy.folder.Folder 5005a085-d7ee-4867-8859-4cd90dee0d62>, ...]
```

--------------------------------

### Update Document Metadata

Source: https://github.com/subutux/rmapy/blob/master/docs/source/quickstart.md

Modify the metadata of a document, such as its visible name, and push the changes to the Remarkable Cloud. This example demonstrates fetching a document, changing its name, and updating it.

```python
>>> from rmapy.api import Client
>>> rmapy = Client()
>>> rmapy.renew_token()
True
>>> collection = rmapy.get_meta_items()
>>> doc = [ d for d in collection if d.VissibleName == 'ModernC'][0]
>>> doc
<rmapy.document.Document a969fcd6-64b0-4f71-b1ce-d9533ec4a2a3>
>>> doc.to_dict()
{'ID': 'a969fcd6-64b0-4f71-b1ce-d9533ec4a2a3', 'Version': 1, 'Message': '', 'Succes': True, 'BlobURLGet': '', 'BlobURLGetExpires': '0001-01-01T00:00:00Z', 'BlobURLPut': '', 'BlobURLPutExpires': '', 'ModifiedClient': '2019-09-18T20:12:07.206206Z', 'Type': 'DocumentType', 'VissibleName': 'ModernC', 'CurrentPage': 0, 'Bookmarked': False, 'Parent': ''}
>>> doc.VissibleName = "Modern C: The book of wisdom"
>>> # push the changes back to the Remarkable Cloud
... rmapy.update_metadata(doc)
True
>>> collection = rmapy.get_meta_items()
>>> doc = [ d for d in docs if d.VissibleName == 'ModernC'][0]
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
IndexError: list index out of range
>>> doc = [ d for d in docs if d.VissibleName == 'Modern C: The book of wisdom'][0]
>>> doc
<rmapy.document.Document a969fcd6-64b0-4f71-b1ce-d9533ec4a2a3>
>>> doc.to_dict()
{'ID': 'a969fcd6-64b0-4f71-b1ce-d9533ec4a2a3', 'Version': 1, 'Message': '', 'Succes': True, 'BlobURLGet': '', 'BlobURLGetExpires': '0001-01-01T00:00:00Z', 'BlobURLPut': '', 'BlobURLPutExpires': '', 'ModifiedClient': '2019-09-18T20:12:07.206206Z', 'Type': 'DocumentType', 'VissibleName': 'Modern C: The book of wisdom', 'CurrentPage': 0, 'Bookmarked': False, 'Parent': ''}
```

--------------------------------

### Renew User Token for Session

Source: https://context7.com/subutux/rmapy/llms.txt

Fetches a new user token for the current session. This is required at the start of each new session after the device has been registered, as user tokens expire.

```python
from rmapy.api import Client

rmapy = Client()

# Renew the user token - required at the start of each session
success = rmapy.renew_token()
print(success)  # True

# Now the client is ready to make API calls
print(rmapy.is_auth())  # True
```

--------------------------------

### Creating Folders

Source: https://context7.com/subutux/rmapy/llms.txt

Creates new folders in the Remarkable Cloud, supporting nesting by assigning a Parent ID.

```python
from rmapy.api import Client
from rmapy.folder import Folder

rmapy = Client()
rmapy.renew_token()

# Create a new folder at root level
new_folder = Folder("Technical Books")
print(f"New folder ID: {new_folder.ID}")

# Upload the folder to the cloud
success = rmapy.create_folder(new_folder)
print(f"Folder created: {success}")  # True

# Verify the folder exists
collection = rmapy.get_meta_items()
created = [f for f in collection if f.VissibleName == "Technical Books"]
print(f"Folder found: {len(created) > 0}")  # True

# Create a nested subfolder
subfolder = Folder("Python")
subfolder.Parent = new_folder.ID  # Set parent to the folder we just created
rmapy.create_folder(subfolder)
print(f"Subfolder created with parent: {subfolder.Parent}")
```

--------------------------------

### Create a New Folder

Source: https://github.com/subutux/rmapy/blob/master/docs/source/quickstart.md

Creates a new folder object and then uploads it to the reMarkable cloud. Verification is done by checking for the new folder's name and ID.

```python
>>> # Create a new folder
>>> new_folder = Folder("New Folder")
>>> new_folder
<rmapy.folder.Folder 579df08d-7ee4-4f30-9994-887e6341cae3>
>>> rmapy.create_folder(new_folder)
True
>>> # verify
>>> [ f for f in rmapy.get_meta_items() if f.VissibleName == "New Folder" ]
[<rmapy.folder.Folder 579df08d-7ee4-4f30-9994-887e6341cae3>]
>>> [ f for f in rmapy.get_meta_items() if f.VissibleName == "New Folder" ][0].ID == new_folder.ID
True
```

--------------------------------

### get_meta_items

Source: https://context7.com/subutux/rmapy/llms.txt

Fetches all documents and folders from the Remarkable Cloud.

```APIDOC
## get_meta_items

### Description
Fetches all documents and folders from the Remarkable Cloud and returns them as a Collection.
```

--------------------------------

### Register API Client

Source: https://github.com/subutux/rmapy/blob/master/docs/source/quickstart.md

Register a new device with the Remarkable API. You will need to obtain a device token from the My Remarkable website. This code stores the token locally.

```python
from rmapy.api import Client

rmapy = Client()
# Should return False
rmapy.is_auth()
# This registers the client as a new device. The received device token is
# stored in the users directory in the file ~/.rmapi, the same as with the
# go rmapi client.
# Get a token at https://my.remarkable.com/device/desktop/connect.
rmapy.register_device("fkgzzklrs")
# It's always a good idea to renew the user token every time you start
# a new session.
rmapy.renew_token()
# Should return True
rmapy.is_auth()
```

--------------------------------

### List Items in Cloud

Source: https://github.com/subutux/rmapy/blob/master/docs/source/quickstart.md

List all metadata items (documents and folders) in your Remarkable cloud. This snippet shows how to count the total number of items, documents, and folders.

```python
>>> from rmapy.api import Client
>>> rmapy = Client()
>>> rmapy.renew_token()
True
>>> collection = rmapy.get_meta_items()
>>> collection
<rmapy.collections.Collection object at 0x7fa1982d7e90>
>>> len(collection)
181
>>> # Count the amount of documents
... from rmapy.document import Document
>>> len([f for f in collection if isinstance(f, Document)])
139
>>> # Count the amount of folders
... from rmapy.folder import Folder
>>> len([f for f in collection if isinstance(f, Folder)])
42
```

--------------------------------

### Authentication and Device Registration

Source: https://github.com/subutux/rmapy/blob/master/docs/source/rmapi.md

Methods for registering a device and managing authentication tokens.

```APIDOC
## register_device

### Description
Registers a new device on the Remarkable Cloud using a one-time code.

### Parameters
- **code** (str) - Required - A unique one-time code obtained from the Remarkable device connection portal.

## renew_token

### Description
Fetches a new user_token for the session. This should be called before starting a new session.

## is_auth

### Description
Checks if the client is currently authenticated.

### Response
- **bool** - True if authenticated, False otherwise.
```

--------------------------------

### Navigate collection hierarchy

Source: https://context7.com/subutux/rmapy/llms.txt

Use the Collection class to traverse folders and documents, including building a tree view.

```python
from rmapy.api import Client
from rmapy.folder import Folder
from rmapy.document import Document

rmapy = Client()
rmapy.renew_token()

collection = rmapy.get_meta_items()

# Get all root-level items (no parent)
root_items = collection.children(None)
print(f"Root items: {len(root_items)}")
for item in root_items:
    item_type = "Folder" if isinstance(item, Folder) else "Document"
    print(f"  [{item_type}] {item.VissibleName}")

# Get children of a specific folder
programming = [f for f in collection if isinstance(f, Folder) and f.VissibleName == "Programming"][0]
children = collection.children(programming)
print(f"\nChildren of 'Programming' folder:")
for child in children:
    print(f"  - {child.VissibleName}")

# Build a simple tree view
def print_tree(collection, parent_id="", indent=0):
    items = [i for i in collection if i.Parent == parent_id]
    for item in items:
        prefix = "  " * indent
        icon = "📁" if isinstance(item, Folder) else "📄"
        print(f"{prefix}{icon} {item.VissibleName}")
        if isinstance(item, Folder):
            print_tree(collection, item.ID, indent + 1)

print("\nFull tree structure:")
print_tree(collection)
```

--------------------------------

### register_device

Source: https://context7.com/subutux/rmapy/llms.txt

Registers a new device with the Remarkable Cloud using a one-time code.

```APIDOC
## register_device

### Description
Registers a new device with the Remarkable Cloud using a one-time code from the Remarkable website. This is the first step in the authentication process.

### Parameters
#### Request Body
- **code** (string) - Required - The one-time code from https://my.remarkable.com/device/desktop/connect
```

--------------------------------

### Uploading Documents

Source: https://context7.com/subutux/rmapy/llms.txt

Uploads PDF or EPUB files to the Remarkable Cloud, optionally specifying a target folder.

```python
from rmapy.api import Client
from rmapy.document import ZipDocument
from rmapy.folder import Folder

rmapy = Client()
rmapy.renew_token()

# Create a ZipDocument from a PDF file
raw_document = ZipDocument(doc="/path/to/document.pdf")
print(f"Document ID: {raw_document.ID}")
print(f"Document name: {raw_document.metadata['VissibleName']}")  # Extracted from filename

# Upload to root folder
success = rmapy.upload(raw_document)
print(f"Upload successful: {success}")  # True

# Upload to a specific folder
collection = rmapy.get_meta_items()
books_folder = [f for f in collection if f.VissibleName == "Books"][0]
another_doc = ZipDocument(doc="/path/to/another.epub")
success = rmapy.upload(another_doc, to=books_folder)
print(f"Upload to folder successful: {success}")  # True

# Verify upload
collection = rmapy.get_meta_items()
children = collection.children(books_folder)
doc_names = [c.VissibleName for c in children if c.Type == "DocumentType"]
print(f"Documents in Books folder: {doc_names}")
```

--------------------------------

### Document and Folder Management

Source: https://github.com/subutux/rmapy/blob/master/docs/source/rmapi.md

Endpoints for retrieving, creating, and deleting meta items like documents and folders.

```APIDOC
## get_meta_items

### Description
Fetches all meta items from the Remarkable Cloud and returns them as a collection.

## get_doc

### Description
Retrieves a specific meta item (Document or Folder) by its ID.

### Parameters
- **_id** (str) - Required - The unique identifier of the meta item.

## create_folder

### Description
Creates a new folder meta object in the cloud.

### Parameters
- **folder** (Folder) - Required - A folder instance to be created.

## delete

### Description
Deletes a document or folder from the cloud.

### Parameters
- **doc** (Document | Folder) - Required - The document or folder instance to delete.
```

--------------------------------

### Configuration Management API

Source: https://github.com/subutux/rmapy/blob/master/docs/source/rmapi.md

APIs for managing the API client configuration.

```APIDOC
## POST /config/dump

### Description
Dump configuration data to the .rmapy config file.

### Method
POST

### Endpoint
/config/dump

### Parameters
#### Request Body
- **config** (dict) - Required - A dictionary containing the configuration data to be saved.

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of the configuration dump.

#### Response Example
{
  "status": "Configuration saved successfully"
}

## GET /config/load

### Description
Load the configuration data from the .rmapy config file.

### Method
GET

### Endpoint
/config/load

### Response
#### Success Response (200)
- **config** (dict) - A dictionary containing the loaded configuration data.

#### Response Example
{
  "config": {
    "api_key": "your_api_key",
    "user_token": "your_user_token"
  }
}
```

--------------------------------

### Initialize Client and Renew Token

Source: https://github.com/subutux/rmapy/blob/master/docs/source/quickstart.md

Initializes the rmapy client and renews the authentication token. This is a prerequisite for most operations.

```python
>>> from rmapy.api import Client
>>> rmapy = Client()
>>> rmapy.renew_token()
True
```

--------------------------------

### ZipFolder Class

Source: https://github.com/subutux/rmapy/blob/master/docs/source/rmapi.md

A dummy zipfile class used for creating folders.

```APIDOC
## class rmapy.folder.ZipFolder

### Description
A dummy zipfile class needed for creating a folder on the Remarkable Cloud.
```

--------------------------------

### Upload ZipDocument to a Folder

Source: https://github.com/subutux/rmapy/blob/master/docs/source/quickstart.md

Uploads a prepared ZipDocument to a specified folder on the reMarkable cloud. The upload is confirmed by checking the folder's children for the document's name.

```python
>>> books = [ i for i in rm.get_meta_items() if i.VissibleName == "Boeken" ][0]
>>> rm.upload(rawDocument, books)
True
>>> # verify
>>> [ i.VissibleName for i in collection.children(books) if i.Type == "DocumentType" ]
['Origin - Dan Brown', 'Flatland', 'Game Of Thrones', '27-11-2019']
```

--------------------------------

### Retrieve All Cloud Content

Source: https://context7.com/subutux/rmapy/llms.txt

Fetches all documents and folders from the Remarkable Cloud. The Remarkable file system is flat, with parent references indicating hierarchy. This returns a Collection object.

```python
from rmapy.api import Client
from rmapy.document import Document
from rmapy.folder import Folder

rmapy = Client()
rmapy.renew_token()

# Get all items from the cloud
collection = rmapy.get_meta_items()
print(f"Total items: {len(collection)}")  # Total items: 181

# Count documents (PDFs, EPUBs, notebooks)
documents = [item for item in collection if isinstance(item, Document)]
print(f"Documents: {len(documents)}")  # Documents: 139

# Count folders
folders = [item for item in collection if isinstance(item, Folder)]
print(f"Folders: {len(folders)}")  # Folders: 42

# Get root level items (items without a parent)
root_items = [item for item in collection if item.Parent == ""]
print(f"Root items: {len(root_items)}")

# Get children of a specific folder
books_folder = [f for f in folders if f.VissibleName == "Books"][0]
children = collection.children(books_folder)
for child in children:
    print(f"  - {child.VissibleName} ({child.Type})")
```

--------------------------------

### Meta Class

Source: https://github.com/subutux/rmapy/blob/master/docs/source/rmapi.md

Base class for objects interacting with the Remarkable API.

```APIDOC
## class rmapy.meta.Meta

### Description
Base class for objects expected in most Remarkable API calls.

### Attributes
- **ID**: ID of the meta object.
- **Version**: The version of this object.
- **Success**: Boolean indicating if the last API call was successful.
- **BlobURLGet**: URL to get the data blob (can be empty).
- **BlobURLGetExpires**: Expiration date of the Get URL.
- **BlobURLPut**: URL to upload the data blob (can be empty).
- **BlobURLPutExpires**: Expiration date of the Put URL.
- **ModifiedClient**: Timestamp of the last client-side modification.
- **Type**: Type of the object (e.g., DocumentType, CollectionType).
- **VissibleName**: Human-readable name of the object.
- **CurrentPage**: The currently selected page of the object.
- **Bookmarked**: Boolean indicating if the object is bookmarked.
```

--------------------------------

### Downloading Documents

Source: https://context7.com/subutux/rmapy/llms.txt

Downloads documents as ZipDocument objects, providing access to raw files, annotations, and metadata.

```python
from rmapy.api import Client
from rmapy.document import Document

rmapy = Client()
rmapy.renew_token()

# Get a document reference
collection = rmapy.get_meta_items()
doc = [d for d in collection if isinstance(d, Document) and d.VissibleName == "My Notes"][0]

# Download the full document
zip_doc = rmapy.download(doc)

# Access document contents
print(f"Document ID: {zip_doc.ID}")
print(f"Content metadata: {zip_doc.content}")
print(f"File type: {zip_doc.content.get('fileType', 'notebook')}")

# Access PDF if present
if zip_doc.pdf:
    with open("downloaded.pdf", "wb") as f:
        f.write(zip_doc.pdf.read())
    zip_doc.pdf.seek(0)  # Reset for potential reuse

# Access EPUB if present
if zip_doc.epub:
    with open("downloaded.epub", "wb") as f:
        f.write(zip_doc.epub.read())

# Access Remarkable pages (notebook strokes)
for page in zip_doc.rm:
    print(f"Page {page.order}: {page.metadata}")

# Access highlights (from EPUB annotations)
for highlight in zip_doc.highlights:
    print(f"Highlight on page {highlight.page_id}: {highlight.highlight_data}")

# Save the complete zip file
zip_doc.dump("backup.zip")
```

--------------------------------

### ZipDocument Class

Source: https://github.com/subutux/rmapy/blob/master/docs/source/rmapi.md

Handles the creation, loading, and dumping of zip files for Remarkable documents.

```APIDOC
## class rmapy.document.ZipDocument

### Description
Handles the creation, loading, and dumping of zip files for Remarkable documents. It manages the specific file formats expected by the tablet.

### Attributes
- **content**: Default content for the .content file.
- **metadata**: Parameters describing the blob.
- **highlights**: Contents of the .highlights folder.
- **pagedata**: Content of the .pagedata file.
- **zipfile**: The raw zipfile in memory.
- **pdf**: The raw PDF file if present.
- **epub**: The raw EPUB file if present.
- **rm**: A list of `rmapy.document.RmPage` objects in this zip.

### Methods
#### dump(file)
- **Description**: Dumps the contents of ZipDocument back to a zip file.
- **Parameters**:
  - **file** (BytesOrString) - Where to save the zipfile.

#### load(file)
- **Description**: Loads a zipfile into this class.
- **Parameters**:
  - **file** (BytesOrString) - A string of a file location or a BytesIO instance of a raw zipfile.

### Special Methods
- **__repr__()**: Returns a string representation of the class.
- **__str__()**: Returns a string representation of the class.
```

--------------------------------

### Document and Folder Operations

Source: https://github.com/subutux/rmapy/blob/master/docs/source/rmapi.md

APIs for updating metadata and uploading documents.

```APIDOC
## POST /update_metadata

### Description
Send an update of the current metadata of a meta object.
Update the meta item.

### Method
POST

### Endpoint
/update_metadata

### Parameters
#### Request Body
- **docorfolder** (Document | Folder) - Required - A document or folder to update the meta information from.

### Response
#### Success Response (200)
- **status** (string) - Indicates the success of the operation.

#### Response Example
{
  "status": "success"
}

## POST /upload

### Description
Upload a document to the cloud. Add a new document to the Remarkable Cloud.

### Method
POST

### Endpoint
/upload

### Parameters
#### Request Body
- **zip_doc** (ZipDocument) - Required - A ZipDocument instance containing the data of a Document.
- **to** (Folder) - Optional - The parent of the document. Defaults to the root folder.

### Raises
- **ApiError** - An error occurred while uploading the document.

### Response
#### Success Response (200)
- **message** (string) - Confirmation message of the upload.

#### Response Example
{
  "message": "Document uploaded successfully"
}
```

--------------------------------

### Move Document to a Folder

Source: https://github.com/subutux/rmapy/blob/master/docs/source/quickstart.md

Retrieves a document, updates its parent folder ID, and submits the metadata changes. The operation is verified by fetching the document again and checking its parent.

```python
>>> # Move a document in a folder
>>> doc = rmapy.get_doc("a969fcd6-64b0-4f71-b1ce-d9533ec4a2a3")
>>> doc
<rmapy.document.Document a969fcd6-64b0-4f71-b1ce-d9533ec4a2a3>
>>> doc.Parent = new_folder.ID
>>> # Submit the changes
>>> rmapy.update_metadata(doc)
True
>>> doc = rmapy.get_doc("a969fcd6-64b0-4f71-b1ce-d9533ec4a2a3")
>>> doc.Parent == new_folder.ID
True
```

--------------------------------

### Folder Class

Source: https://github.com/subutux/rmapy/blob/master/docs/source/rmapi.md

Represents a folder within the Remarkable file system.

```APIDOC
## class rmapy.folder.Folder

### Description
Represents a folder with methods to prepare create and update requests.

### Methods
#### create_request()
- **Description**: Prepares parameters to create this folder.
- **Returns**: Tuple[BytesIO, dict] - ZipFolder and JSON body for upload request.

#### update_request()
- **Description**: Prepares parameters to update a folder.
- **Returns**: dict - Data structure to submit to the API.
```

--------------------------------

### Data Operations

Source: https://github.com/subutux/rmapy/blob/master/docs/source/rmapi.md

Methods for downloading documents and checking version information.

```APIDOC
## download

### Description
Downloads a raw document from the Remarkable Cloud.

### Parameters
- **document** (Document) - Required - The document instance to download.

### Response
- **ZipDocument** - An instance containing the raw data files.

## get_current_version

### Description
Fetches the latest version information for a specific document or folder.

### Parameters
- **docorfolder** (Document | Folder) - Required - The item to check.
```

--------------------------------

### get_doc

Source: https://context7.com/subutux/rmapy/llms.txt

Fetches a specific document or folder by its unique ID.

```APIDOC
## get_doc

### Description
Fetches a specific document or folder from the Remarkable Cloud by its unique ID.

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique ID of the document or folder.
```

--------------------------------

### ZipDocument Factory Functions

Source: https://github.com/subutux/rmapy/blob/master/docs/source/rmapi.md

Functions to create ZipDocument instances from different sources.

```APIDOC
## rmapy.document.from_request_stream

### Description
Returns a ZipDocument from a request stream containing a zipfile.

### Parameters
- **_id** (str) - The object ID this zipfile represents.
- **stream** (Response) - A stream containing the zipfile.

### Returns
- ZipDocument: The object of the downloaded zipfile.

## rmapy.document.from_zip

### Description
Returns a ZipDocument from a zipfile.

### Parameters
- **_id** (str) - The object ID this zipfile represents.
- **file** (str) - The filename of the zipfile.

### Returns
- ZipDocument: An instance of the supplied zipfile.
```

--------------------------------

### Retrieve a Specific Document by ID

Source: https://context7.com/subutux/rmapy/llms.txt

Fetches a specific document or folder from the Remarkable Cloud using its unique ID. Returns a Document or Folder instance with full metadata, including blob URLs for downloading. Handles DocumentNotFound exceptions.

```python
from rmapy.api import Client
from rmapy.exceptions import DocumentNotFound

rmapy = Client()
rmapy.renew_token()

# Get a document by ID
try:
    doc = rmapy.get_doc("a969fcd6-64b0-4f71-b1ce-d9533ec4a2a3")
    print(f"Document: {doc.VissibleName}")
    print(f"Type: {doc.Type}")
    print(f"ID: {doc.ID}")
    print(f"Parent folder ID: {doc.Parent}")
    print(f"Current page: {doc.CurrentPage}")
    print(f"Bookmarked: {doc.Bookmarked}")
except DocumentNotFound as e:
    print(f"Document not found: {e}")
```

--------------------------------

### Manipulate documents with ZipDocument

Source: https://context7.com/subutux/rmapy/llms.txt

Create, load, modify, and save Remarkable documents using the ZipDocument class.

```python
from rmapy.document import ZipDocument, RmPage
from io import BytesIO

# Create an empty notebook
notebook = ZipDocument()
notebook.content["fileType"] = "notebook"
notebook.metadata["VissibleName"] = "My Custom Notebook"

# Create from existing PDF
pdf_doc = ZipDocument(doc="/path/to/file.pdf")
print(f"Created from PDF: {pdf_doc.metadata['VissibleName']}")
print(f"File type: {pdf_doc.content['fileType']}")  # pdf

# Load from existing zip file
existing = ZipDocument(_id="existing-uuid", file="/path/to/backup.zip")
print(f"Loaded pages: {len(existing.rm)}")
print(f"Has PDF: {existing.pdf is not None}")
print(f"Has EPUB: {existing.epub is not None}")
print(f"Highlights: {len(existing.highlights)}")

# Access and modify content
existing.metadata["VissibleName"] = "Renamed Document"
existing.content["lastOpenedPage"] = 5

# Save modified document
existing.dump("modified_backup.zip")

# Access individual pages
for page in existing.rm:
    print(f"Page {page.order}:")
    print(f"  Metadata: {page.metadata}")
    print(f"  Has thumbnail: {hasattr(page, 'thumbnail')}")
```

--------------------------------

### Handle API exceptions

Source: https://context7.com/subutux/rmapy/llms.txt

Catch specific exceptions like AuthError and DocumentNotFound to manage API interaction failures.

```python
from rmapy.api import Client
from rmapy.exceptions import (
    AuthError,
    DocumentNotFound,
    ApiError,
    FolderNotFound,
    UnsupportedTypeError
)

rmapy = Client()

# Handle authentication errors
try:
    # Attempting to use API without authentication
    rmapy.renew_token()
except AuthError as e:
    print(f"Authentication failed: {e}")
    # Need to register device first
    rmapy.register_device("new_code")
    rmapy.renew_token()

# Handle document not found
try:
    doc = rmapy.get_doc("non-existent-id")
except DocumentNotFound as e:
    print(f"Document not found: {e}")

# Handle API errors
try:
    collection = rmapy.get_meta_items()
    doc = [d for d in collection][0]
    rmapy.delete(doc)
except ApiError as e:
    print(f"API error: {e}")
    if e.response:
        print(f"HTTP status: {e.response.status_code}")
        print(f"Response body: {e.response.text}")
```

--------------------------------

### Convert PDF to Remarkable ZipDocument

Source: https://github.com/subutux/rmapy/blob/master/docs/source/quickstart.md

Initializes the rmapy client, renews the token, and converts a local PDF file into the ZipDocument format required for uploading. The visible name is extracted from the metadata.

```python
>>> from rmapy.document import ZipDocument
>>> from rmapy.api import Client
>>> rm = Client()
>>> rm.renew_token()
True
>>> rawDocument = ZipDocument(doc="/home/svancampenhout/27-11-2019.pdf")
>>> rawDocument
<rmapy.document.ZipDocument b926ffc2-3600-460e-abfa-0fcf20b0bf99>
>>> rawDocument.metadata["VissibleName"]
'27-11-2019'
```

--------------------------------

### Delete folder with contents

Source: https://context7.com/subutux/rmapy/llms.txt

Recursively deletes children before removing the parent folder.

```python
folder_with_contents = [f for f in collection if f.VissibleName == "Archive"][0]
children = collection.children(folder_with_contents)
for child in children:
    rmapy.delete(child)
    print(f"Deleted child: {child.VissibleName}")
rmapy.delete(folder_with_contents)
print("Folder and contents deleted")
```

--------------------------------

### Collection Management API

Source: https://github.com/subutux/rmapy/blob/master/docs/source/rmapi.md

APIs for managing collections of documents and folders.

```APIDOC
## GET /collections/items

### Description
Retrieves all items (documents and folders) within a collection.

### Method
GET

### Endpoint
/collections/items

### Parameters
#### Query Parameters
- **folder** (Folder) - Optional - The folder from which to retrieve children. If not provided, retrieves children from the root.

### Response
#### Success Response (200)
- **items** (Array<Document | Folder>) - A list of documents and folders.

#### Response Example
{
  "items": [
    {
      "id": "doc-123",
      "type": "Document",
      "name": "My Document"
    },
    {
      "id": "folder-456",
      "type": "Folder",
      "name": "My Folder"
    }
  ]
}

## GET /collections/parent

### Description
Returns the parent folder of a given document or folder.

### Method
GET

### Endpoint
/collections/parent

### Parameters
#### Query Parameters
- **doc_or_folder** (Document | Folder) - Required - The document or folder to find the parent of.

### Response
#### Success Response (200)
- **parent_folder** (Folder) - The parent folder object.

#### Response Example
{
  "parent_folder": {
    "id": "folder-abc",
    "type": "Folder",
    "name": "Parent Folder"
  }
}

## POST /collections/add

### Description
Adds an item to the collection. The item is automatically wrapped in the correct class based on its type.

### Method
POST

### Endpoint
/collections/add

### Parameters
#### Request Body
- **doc_dict** (dict) - Required - A dictionary representing a document or folder to be added.

### Response
#### Success Response (200)
- **message** (string) - Confirmation message of the addition.

#### Response Example
{
  "message": "Item added to collection"
}

## POST /collections/add_document

### Description
Adds a document to the collection.

### Method
POST

### Endpoint
/collections/add_document

### Parameters
#### Request Body
- **doc_dict** (dict) - Required - A dictionary representing a document to be added.

### Response
#### Success Response (200)
- **message** (string) - Confirmation message of the document addition.

#### Response Example
{
  "message": "Document added to collection"
}

## POST /collections/add_folder

### Description
Adds a folder to the collection.

### Method
POST

### Endpoint
/collections/add_folder

### Parameters
#### Request Body
- **dir_dict** (dict) - Required - A dictionary representing a folder to be added.

### Response
#### Success Response (200)
- **message** (string) - Confirmation message of the folder addition.

#### Response Example
{
  "message": "Folder added to collection"
}
```

--------------------------------

### rmapy.types Module

Source: https://github.com/subutux/rmapy/blob/master/docs/source/rmapi.md

This section describes the types and attributes available within the rmapy.types module, which represent objects and data structures used in the Remarkable Cloud API.

```APIDOC
## rmapy.types Module

### Description
This module contains type definitions for objects used within the Remarkable Cloud API. It includes attributes for various object properties and methods for data conversion.

### Object Attributes

#### Parent
- **Description**: If empty, this object is the root folder. This can be an ID of a CollectionType.
- **Type**: String or CollectionType ID
- **Required**: Optional

#### BlobURLGet
- **Description**: URL for retrieving a blob.
- **Type**: String
- **Required**: Optional

#### BlobURLGetExpires
- **Description**: Expiration time for the BlobURLGet.
- **Type**: String
- **Required**: Optional

#### BlobURLPut
- **Description**: URL for uploading a blob.
- **Type**: String
- **Required**: Optional

#### BlobURLPutExpires
- **Description**: Expiration time for the BlobURLPut.
- **Type**: String
- **Required**: Optional

#### Bookmarked
- **Description**: Indicates if the item is bookmarked.
- **Type**: Boolean
- **Required**: Optional (Defaults to False)

#### CurrentPage
- **Description**: The current page number, relevant for paginated results.
- **Type**: Integer
- **Required**: Optional (Defaults to 1)

#### ID
- **Description**: The unique identifier for the object.
- **Type**: String
- **Required**: Optional

#### Message
- **Description**: A message associated with the object, possibly for status or errors.
- **Type**: String
- **Required**: Optional

#### ModifiedClient
- **Description**: Identifier for the client that modified the object.
- **Type**: String
- **Required**: Optional

#### Success
- **Description**: Indicates the success status of an operation.
- **Type**: Boolean
- **Required**: Optional (Defaults to True)

#### Type
- **Description**: The type of the object.
- **Type**: String
- **Required**: Optional

#### Version
- **Description**: The version number of the object.
- **Type**: Integer
- **Required**: Optional (Defaults to 0)

#### VissibleName
- **Description**: The visible name of the object.
- **Type**: String
- **Required**: Optional

### Methods

#### to_dict()
- **Description**: Returns a dictionary representation of the object. Used for API calls.
- **Returns**: A dictionary of the current object.
```

--------------------------------

### Deleting Documents and Folders

Source: https://context7.com/subutux/rmapy/llms.txt

Permanently removes items from the cloud. Note that folder deletion does not cascade to children.

```python
from rmapy.api import Client
from rmapy.document import Document
from rmapy.folder import Folder
from rmapy.exceptions import ApiError

rmapy = Client()
rmapy.renew_token()

collection = rmapy.get_meta_items()

# Delete a document
doc = [d for d in collection if d.VissibleName == "Old Notes"][0]
try:
    success = rmapy.delete(doc)
    print(f"Document deleted: {success}")  # True
except ApiError as e:
    print(f"Failed to delete: {e}")

# Delete an empty folder
folder = [f for f in collection if isinstance(f, Folder) and f.VissibleName == "Empty Folder"][0]
success = rmapy.delete(folder)
print(f"Folder deleted: {success}")  # True
```

--------------------------------

### Rmapy Exceptions

Source: https://github.com/subutux/rmapy/blob/master/docs/source/rmapi.md

Custom exceptions used within the rmapy library.

```APIDOC
## rmapy.exceptions Module

### Exceptions
- **ApiError(msg, response=None)**: Base class for API errors.
- **AuthError(msg)**: Represents authentication errors.
- **DocumentNotFound(msg)**: Raised when a requested document is not found.
- **FolderNotFound(msg)**: Raised when a requested folder is not found.
- **UnsupportedTypeError(msg)**: Raised when an unsupported type is encountered.
```

--------------------------------

### Move document to a different folder

Source: https://context7.com/subutux/rmapy/llms.txt

Updates the Parent property of a document to move it into a specific folder.

```python
folders = [f for f in collection if f.VissibleName == "Programming Books"]
if folders:
    target_folder = folders[0]
    doc.Parent = target_folder.ID
    rmapy.update_metadata(doc)
    print(f"Moved to folder: {target_folder.VissibleName}")
```

--------------------------------

### update_metadata

Source: https://context7.com/subutux/rmapy/llms.txt

Updates the metadata of a document or folder in the Remarkable Cloud.

```APIDOC
## update_metadata

### Description
Updates the metadata of a document or folder in the Remarkable Cloud, such as renaming items, moving them, or changing status.

### Parameters
#### Request Body
- **doc** (object) - Required - The document or folder instance with updated metadata.
```

--------------------------------

### renew_token

Source: https://context7.com/subutux/rmapy/llms.txt

Fetches a new user token for the current session.

```APIDOC
## renew_token

### Description
Fetches a new user token for the current session. This should be called at the start of each new session after the device has been registered.
```

--------------------------------

### Update Document Metadata

Source: https://context7.com/subutux/rmapy/llms.txt

Updates the metadata of a document or folder in the Remarkable Cloud. This can be used to rename items, move them to different folders, change bookmarked status, or update the current page.

```python
from rmapy.api import Client

rmapy = Client()
rmapy.renew_token()

# Get a document
collection = rmapy.get_meta_items()
doc = [d for d in collection if d.VissibleName == "ModernC"][0]
print(f"Original name: {doc.VissibleName}")

# Rename the document
doc.VissibleName = "Modern C: The Book of Wisdom"

# Push changes to the cloud
success = rmapy.update_metadata(doc)
print(f"Update successful: {success}")  # True
```
Tokens:
Raw