Development

Docs Why updates expire? URL Scheme API Security & Legal CleanShot Security Bug Bounty Program EULA CleanShot Cloud Terms of Service Privacy Policy Subprocessors DPA URL scheme API Our macOS app exposes actions that lets pro users and developers of other apps send commands to CleanShot. This page explains how it works. Overview URL scheme is a special type of link that works just like a normal https:// link you use every day. Instead of opening a webpage, it performs a specific action in the CleanShot macOS app. Commands are sent to CleanShot by constructing a special URL: cleanshot://command-name?parameter1=value1&parameter2=value2 Opening these links will launch the app and execute the command. For example, here's how you would tell CleanShot to take a fullscreen screenshot: cleanshot://capture-fullscreen ✨  All-In-One mode /all-in-one Launch the "All-In-One" mode. You can also provide the optional parameters to open the tool at specific location. Point (0,0) is located in the lower left corner of the screen. Parameters: x (optional) y (optional) width (optional) height (optional) display (optional) - Capture a specified display: 1 is the main display, 2 is the secondary, etc. If not specified, CleanShot will use the display which the cursor is on. Example: cleanshot://all-in-one or cleanshot://all-in-one?x=100&y=120&width=200&height=150&display=1 Requires CleanShot 4.2 or later. Parameters x, y, width, height, display require version 4.7 or later. 📸  Screenshots /capture-area Opens the standard "Capture Area" mode. You can also provide the optional parameters and capture the screen instantly. Point (0,0) is located in the lower left corner of the screen. Parameters: x (optional) y (optional) width (optional) height (optional) display (optional) - Capture a specified display: 1 is the main display, 2 is the secondary, etc. If not specified, CleanShot will use the display which the cursor is on. action (optional) - Perform a specific action after taking a screenshot: (copy/save/annotate/upload/pin). Example: cleanshot://capture-area or cleanshot://capture-area?action=annotate or cleanshot://capture-area?x=100&y=120&width=200&height=150&display=1 Requires CleanShot 3.5.1 or later. Parameter action requires version 4.7 or later. /capture-previous-area Repeats last taken screenshot. Parameters: action (optional) - Perform a specific action after taking a screenshot: (copy/save/annotate/upload/pin) Example: cleanshot://capture-previous-area Requires CleanShot 3.5.1 or later. Parameter action requires version 4.7 or later. /capture-fullscreen Takes a fullscreen screenshot. Parameters: action (optional) - Perform a specific action after taking a screenshot: (copy/save/annotate/upload/pin) Example: cleanshot://capture-fullscreen Requires CleanShot 3.5.1 or later. Parameter action requires version 4.7 or later. /capture-window Opens "Capture Window" mode. Parameters: action (optional) - Perform a specific action after taking a screenshot: (copy/save/annotate/upload/pin) Example: cleanshot://capture-window Requires CleanShot 3.5.1 or later. Parameter action requires version 4.7 or later. /self-timer Opens "Capture Area" mode with self-timer. Parameters: action (optional) - Perform a specific action after taking a screenshot: (copy/save/annotate/upload/pin) Example: cleanshot://self-timer Requires CleanShot 3.5.1 or later. Parameter action requires version 4.7 or later. /scrolling-capture Opens "Scrolling Capture" mode. You can also provide the optional parameters to open the tool at specific location. Point (0,0) is located in the lower left corner of the screen. Parameters: x (optional) y (optional) width (optional) height (optional) display (optional) - Capture a specified display: 1 is the main display, 2 is the secondary, etc. If not specified, CleanShot will use the display which the cursor is on. start (optional) - Automatically start capture (true/false) autoscroll (optional) - Enable auto-scroll mode (true/false) Example: cleanshot://scrolling-capture or cleanshot://scrolling-capture?x=100&y=120&width=200&height=150&start=true&autoscroll=true Requires CleanShot 3.5.1 or later. Parameters start and autoscroll require version 4.7 or later. /pin Opens the specified file as a pinned screenshot. Parameters: filepath (optional) - path to the file (PNG/JPEG) you want to pin. If you don’t pass this parameter, CleanShot will ask to select the file manually. Example: cleanshot://pin or cleanshot://pin?filepath=/Users/john/Desktop/my%20screenshot.png Requires CleanShot 3.5.1 or later. 🎥  Screen Recording /record-screen Opens "Record Screen" mode. You can also provide the optional parameters to open the tool at specific location. Point (0,0) is located in the lower left corner of the screen. Parameters: x (optional) y (optional) width (optional) height (optional) display (optional) - Capture a specified display: 1 is the main display, 2 is t