You can change the fields that will be returned by the API using the fields= query parameter, which takes a list of comma separated fields. For example, to get the longitude and latitude of a note, use this:
curl http://localhost:41184/notes/ABCD123?fields=longitude,latitude
+To get the IDs only of all the tags:
+curl http://localhost:41184/tags?fields=id
+{ x: x, y: y, width: width, height: height }tag1,tag2.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
When a new note is created, it is automatically assigned a new unique ID so normally you do not need to set the ID. However, if for some reason you want to set it, you can supply it as the id property. It needs to be a 32 characters long hexadecimal string. Make sure it is unique, for example by generating it using whatever GUID function is available in your programming language.
curl --data '{ "id": "00a87474082744c1a8515da6aa5792d2", "title": "My note with custom ID"}' http://127.0.0.1:41184/notes
+Sets the properties of the note with ID :id
Deletes the note with ID :id
@@ -604,12 +617,24 @@ for (let portToTest = 41184; portToTest <= 41194; portToTest++) {Gets all resources
Gets resource with ID :id
+Gets the actual file associated with this resource.
Creates a new resource
Creating a new resource is special because you also need to upload the file. Unlike other API calls, this one must have the "multipart/form-data" Content-Type. The file data must be passed to the "data" form field, and the other properties to the "props" form field. An example of a valid call with cURL would be:
diff --git a/readme/api.md b/readme/api.md index 6a142333e7..e9417d4ab3 100644 --- a/readme/api.md +++ b/readme/api.md @@ -14,6 +14,7 @@ for (let portToTest = 41184; portToTest <= 41194; portToTest++) { } } ``` + # Authorisation To prevent unauthorised applications from accessing the API, the calls must be authentified. To do so, you must provide a token as a query parameter for each API call. You can get this token from the Joplin desktop application, on the Web Clipper Options screen. @@ -23,6 +24,7 @@ This would be an example of valid cURL call using a token: curl http://localhost:41184/notes?token=ABCD123ABCD123ABCD123ABCD123ABCD123 In the documentation below, the token will not be specified every time however you will need to include it. + # Using the API All the calls, unless noted otherwise, receives and send **JSON data**. For example to create a new note: @@ -42,6 +44,16 @@ The four verbs supported by the API are the following ones: * **PUT**: To update an item. Note in a REST API, traditionally PUT is used to completely replace an item, however in this API it will only replace the properties that are provided. For example if you PUT {"title": "my new title"}, only the "title" property will be changed. The other properties will be left untouched (they won't be cleared nor changed). * **DELETE**: To delete items. +# Filtering data + +You can change the fields that will be returned by the API using the `fields=` query parameter, which takes a list of comma separated fields. For example, to get the longitude and latitude of a note, use this: + + curl http://localhost:41184/notes/ABCD123?fields=longitude,latitude + +To get the IDs only of all the tags: + + curl http://localhost:41184/tags?fields=id + # About the property types * Text is UTF-8. @@ -85,6 +97,7 @@ body_html | text | Note body, in HTML format base_url | text | 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 | text | An image to attach to the note, in [Data URL](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URIs) format. crop_rect | text | 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 }` +tags | text | Comma-separated list of tags. eg. `tag1,tag2`. ## GET /notes @@ -118,6 +131,12 @@ Examples: 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 +### Creating a note with a specific ID + +When a new note is created, it is automatically assigned a new unique ID so **normally you do not need to set the ID**. However, if for some reason you want to set it, you can supply it as the `id` property. It needs to be a 32 characters long hexadecimal string. **Make sure it is unique**, for example by generating it using whatever GUID function is available in your programming language. + + curl --data '{ "id": "00a87474082744c1a8515da6aa5792d2", "title": "My note with custom ID"}' http://127.0.0.1:41184/notes + ## PUT /notes/:id Sets the properties of the note with ID :id @@ -188,6 +207,8 @@ file_extension | text | encryption_cipher_text | text | encryption_applied | int | encryption_blob_encrypted | int | +fetch_status | int | +fetch_error | text | ## GET /resources @@ -197,6 +218,10 @@ Gets all resources Gets resource with ID :id +## GET /resources/:id/file + +Gets the actual file associated with this resource. + ## POST /resources Creates a new resource