Notes through the API
Add, read, change and delete notes, with their files and tags.
A token with only notes:write reaches the notes it added. One that may also read all your notes reaches any note. What a token may reach has the rest.
Add a note
POST /v1/notes
Send {"text": "…"}, or the words alone as text/plain. A form works too, as a Shortcut’s Form body or curl --data-urlencode "text=…" sends it, with text and, if you like, date or written_at. Any other form is taken as the words, so curl -d "my words" still works, and a multipart body is refused.
Hashtags in the words are its tags, and links get their names, as on the web. What else you can send:
-
tagsgives it tags by name, with spaces or emoji if you like:{"text": "…", "tags": ["Road Trip", "lake"]}. A#in front is dropped, and “Road Trip”, “road trip” and “road-trip” are one tag. Up to 20, each up to 50 characters, with no commas or line breaks. The words’ hashtags are its tags too, after these. From version 1.21.0. -
dateputs it on an earlier day, back to your birthday. -
written_atis the moment the words were typed: a note sent late files to the day it was typed. With neither, it’s today’s. -
uploadsgives it files (see Photos, recordings and PDFs), and then it needs no words. -
placesays where it was (see Places). -
"markup": "rich"says itstexthas rich-text marks, like**bold**and lists. Without it, the words are plain and the marks show as typed. An edit keeps what the note is. From version 1.16.0.
The answer has the note’s id, date, version and revision, and how many files it has.
Read notes
GET /v1/notes?from=YYYY-MM-DD&to=YYYY-MM-DD
The notes this token added on those days, or every note on them if it may read all your notes, oldest first, each as the request below gives it.
tois the last day, and left out it’sfrom, so one day is?from=alone.- A request reads up to 31 days; ask for a longer span in pieces.
limitsets how many a page holds, andnextin the answer, sent back asafter, gives the next page.- A page stops at about a megabyte, so it can hold fewer than
limitnotes: keep asking withafteruntilnextis null. - Days with none give an empty list.
GET /v1/notes/{date}/{id}
One note this token added, or any note if it may read all your notes, with its text, revision and written_at, and its files as media: each one’s number n, kind, type, name, size, and thumb when it has a small copy.
A note also says:
tags, each tag’s key, likeroad-trip, which is what matches, andtag_names, the same tags as they were written, like “Road Trip” (from version 1.21.0)markup(rich, or null for plain words)parts, its words cut into strings, links and tags, ready to show- its own
place, andno_placeif you took its place away edited_at,tzandlate- who wrote it (
authorandclient), andfromfor an import attachments, how many files its email carried that weren’t kept
Each file says its transcript and description, the words Release Notes kept if you turned those on, or null, and writing while a transcript is still to come. A transcript arriving doesn’t change the note’s revision; transcript.added in the activity log says when.
Add ?include=urls to either request to get each file’s url and its small copy’s in the answer, good for ten minutes, instead of asking for them one by one. All of this is from version 1.14.0.
Change a note
PUT /v1/notes/{date}/{id}: replace its text. Send{"text": "…", "revision": "…"}with the revision you read; a note changed since, on the web say, is refused with the current one.POST /v1/notes/{date}/{id}/append: add a paragraph to it, with{"text": "…"}.PUT /v1/notes/{date}/{id}/place: say where it was. See Places.DELETE /v1/notes/{date}/{id}/place: take its place away, so it saysno_placeand shows none from its day.DELETE /v1/notes/{date}/{id}: delete it.
Photos, recordings and PDFs
A file goes in three steps:
- Ask for a form with
POST /v1/uploads, giving the file’stype, likeimage/jpeg, its exactsizein bytes, and itsnameif it has one. The answer has the upload’s id asupload, thetypeit was signed for, and aurland itsfields. - Post the file to that
urlwithin 5 minutes, asmultipart/form-data: every one of thefields, then the file itself, last, asfile. - Name it in a note’s
uploads, as{"upload": "…", "type": "image/jpeg", "name": "lake.jpg"}: onPOST /v1/notesfor a new note, or onPOST /v1/notes/{date}/{id}/mediato add it to one this token added.
form=$(curl -fsS https://notes.yourversionnumber.com/v1/uploads \
-H "Authorization: Bearer $RN_TOKEN" \
-H "Content-Type: application/json" \
--data "$(jq -n --argjson size "$(wc -c < lake.jpg)" '{name: "lake.jpg", type: "image/jpeg", size: $size}')")
curl -fsS "$(jq -r .url <<<"$form")" \
$(jq -r '.fields | to_entries[] | "--form-string \(.key)=\(.value)"' <<<"$form") \
-F file=@lake.jpg
curl -fsS https://notes.yourversionnumber.com/v1/notes \
-H "Authorization: Bearer $RN_TOKEN" \
-H "Content-Type: application/json" \
-H "Accept: text/plain" \
-H "Idempotency-Key: $(uuidgen)" \
--data "$(jq '{text: "The lake at dawn #lake", uploads: [{upload, type, name: "lake.jpg"}]}' <<<"$form")"
Release Notes checks each file against what arrived, then keeps it with the note, as it keeps one you add on the web: a photo gets its thumbnail and, on a note with no place of its own, the place it was taken, and photos and recordings get the descriptions and transcripts you’ve turned on. A note can have up to 20 files, at 50 MB a file. A note takes each upload once, and an upload no note takes is gone after a day. A form has no Idempotency-Key: if an upload fails, ask for a new one.
Send photos as JPEG, PNG or WebP where you can. A HEIC photo is kept as it is, with its time and place, and gets a JPEG thumbnail like any other, but only some browsers can open the whole photo.
The other file requests
POST /v1/notes/{date}/{id}/media: add files to a note, with{"uploads": […]}.GET /v1/notes/{date}/{id}/media/{n}: an address for one of its files, asurl, good for ten minutes and fetched with no token.?size=thumbgives a photo’s small copy instead, for a list.DELETE /v1/notes/{date}/{id}/media/{n}: take one file off it, with its small copy, transcript and description. The other files keep their numbers, and itsrevisionchanges. A note with no words can’t lose its last file, so delete the note instead. A file that came by email stays in that note’s email until the note is deleted, and no app can read it there. Taking a file off a note you didn’t add through this token also needs a token that may read and change all your notes. From version 1.17.0.
Tags
GET /v1/tags: your tag row, the pinned tags and then up to 20 recent ones, the tags used most in the last 30 days. A token that adds or reads notes may ask. Each has its key and, from version 1.21.0, its name:pinned_namesbesidepinned, and anameon each recent one.PUT /v1/tags/pinned: replace your pinned tags, with{"pinned": ["house", "Road Trip"]}, up to 12 tags, by name, in any language’s letters, likeМоскваor東京. They’re the same ones the web shows under the note box.