The Joplin Web Clipper API is now more consistent and documented below
https://joplin.cozic.net/clipper/
You can expect it to remain stable from now on. More end points or properties might be supported later on but what's there shouldn't change.
Using the Web Clipper service
The Web Clipper service can be used to create notes from any other application. It exposes a REST API with a number of methods to list folders and to create notes or attach images.
In order to use it, you'll first need to find on which port the service is running. To do so, open the Web Clipper Option in Joplin and if the service is running it should tell you on which port. Normally it runs on port 41184. If you want to find it programmatically, you may follow this kind of algorithm:
let port = null;
for (let portToTest = 41184; portToTest <= 41194; portToTest++) {
const result = pingPort(portToTest); // Call GET /ping
if (result == 'JoplinClipperServer') {
port = portToTest; // Found the port
break;
}
}
start from 41184, then ping it (using the /ping method below)
The following methods are available:
GET /ping
Tells whether the service is active or not. It should return "JoplinClipperServer" if it works.
Example: curl http://127.0.0.1:41184/ping
GET /folders
Returns the list of notebooks (called "folders" internally) as a tree. The sub-notebooks of a notebook, if any, are under the children
key.
Example: curl http://127.0.0.1:41184/folders
POST /notes
Creates a new note. You can either specify the note body as Markdown by setting the body
parameter, or in HTML by setting the body_html
. All parameter are optional.
Parameters:
Key |
Description |
title |
Note title |
body |
Note body, in Markdown |
body_html |
Note body, in HTML format |
source_url |
The URL the note comes from |
parent_id |
The notebook (ID) to move the note to |
base_url |
If body_html is provided and contains relative URLs, provide the base_url parameter too so that all the URLs can be converted to absolute ones. The base URL is basically where the HTML was fetched from, minus the query (everything after the '?'). For example if the original page was https://stackoverflow.com/search?q=%5Bjava%5D+test , the base URL is https://stackoverflow.com/search . |
image_data_url |
An image to attach to the note, in Data URL format. |
crop_rect |
If an image is provided, you can also specify an optional rectangle that will be used to crop the image. In format { x: x, y: y, width: width, height: height }
|
Examples:
- Create a note from some Markdown text
curl --data '{ "title": "My note", "body": "Some note in **Markdown**"}' http://127.0.0.1:41184/notes
- Create a note from some HTML
curl --data '{ "title": "My note", "body_html": "Some note in <b>HTML</b>"}' http://127.0.0.1:41184/notes
- Create a note and attach an image to it:
curl --data '{ "title": "Image test", "body": "Here is Joplin icon:", "image_data_url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAgAAAAICAIAAABLbSncAAAAGXRFWHRTb2Z0d2FyZQBBZG9iZSBJbWFnZVJlYWR5ccllPAAAANZJREFUeNoAyAA3/wFwtO3K6gUB/vz2+Prw9fj/+/r+/wBZKAAExOgF4/MC9ff+MRH6Ui4E+/0Bqc/zutj6AgT+/Pz7+vv7++nu82c4DlMqCvLs8goA/gL8/fz09fb59vXa6vzZ6vjT5fbn6voD/fwC8vX4UiT9Zi//APHyAP8ACgUBAPv5APz7BPj2+DIaC2o3E+3o6ywaC5fT6gD6/QD9/QEVf9kD+/dcLQgJA/7v8vqfwOf18wA1IAIEVycAyt//v9XvAPv7APz8LhoIAPz9Ri4OAgwARgx4W/6fVeEAAAAASUVORK5CYII="}' http://127.0.0.1:41184/notes