### 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 >>> 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 [, , ...] ``` -------------------------------- ### 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 [, , ...] ``` -------------------------------- ### 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 >>> 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 "", line 1, in IndexError: list index out of range >>> doc = [ d for d in docs if d.VissibleName == 'Modern C: The book of wisdom'][0] >>> doc >>> 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.create_folder(new_folder) True >>> # verify >>> [ f for f in rmapy.get_meta_items() if f.VissibleName == "New Folder" ] [] >>> [ 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 >>> 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 >>> 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 >>> 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) - 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 ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.