Notes
Read and write notes as Markdown, avoid overwriting edits, and organise notes into folders.
Writing notes
Note content goes in as Markdown and comes out two ways. GET /notes/{noteId} returns content, the editor's JSON document, and markdown, the same document converted back. The server stores only the editor JSON, so the Markdown you read back is a conversion, not your original text.
POST /notes takes optional markdown for the first version of a note. Two operations write an existing note. PUT /notes/{noteId}/content replaces the whole document. POST /notes/{noteId}/content/append adds your blocks after the current ones and keeps their ids. Send an Idempotency-Key with the append so a retry can't add the blocks twice; without a key, send baseVersion and a retry fails with 409 instead. PUT takes no mode, and a body with one returns 400. An empty or whitespace-only markdown on an append returns 400 invalid_request with details.reason empty-append. An append drops one empty paragraph at the end of the note first, so a new or app-saved note doesn't gain a blank block. A note holds at most 200,000 visible characters, so an append that would pass that returns 400 invalid_request with details.reason note-too-large. A replace is not capped by it. Raw HTML in the Markdown is shown as text, except <u> and, inside a table cell, <br>. GET /notes/{noteId} writes the note's inline images as . A replace keeps every image that stays in your Markdown and deletes the ones you leave out from storage, so reading a note and writing its markdown back keeps all of them. An append keeps them all. An image that points at an upload the web editor hasn't confirmed yet can still be deleted 24 hours after the upload.
Writing a note's markdown back with PUT /notes/{noteId}/content gives the same document when markdownLosses is empty. That includes an image's alt text and title, which stay text even when they look like a number, such as . An image with an empty alt or title reads back with null, and so does a link with an empty title. When it isn't, the listed parts come back simplified, as described in Markdown in notes. Block ids exist only in content, and a write gives the blocks new ones. A note whose content isn't an editor document returns markdown: null, and an append to it returns 400 with details.reason legacy-content.
Every content change raises the note's version. To avoid overwriting a save made in the app or by another client, send the version you read as baseVersion. If the note changed since, the write returns 409 conflict with details.baseVersion and details.currentVersion and writes nothing. Read the note again, merge, and retry with the new version. Without baseVersion the write always goes through.
A folderId in a body that is not one of the user's folders returns 400 invalid_request with details.field folderId and details.reason unknown-folder. It works the same on POST /notes and PATCH /notes/{noteId}.
PATCH /notes/{noteId} renames a note, moves it into a folder or out of one (folderId: null), and pins it. DELETE /notes/{noteId} moves the note to the trash, where it drops out of every read, and POST /notes/{noteId}/restore brings it back within 30 days. Both need notes:delete.
Markdown in notes
Notes use CommonMark with GFM tables and strikethrough, plus a few additions for what the editor has and plain Markdown doesn't. GET /notes/{noteId} writes them, and every write endpoint reads them.
| Content | Markdown |
|---|---|
| Task list | - [ ] open and - [x] done. Every item in the list needs a checkbox, or the list stays a plain list. |
| Inline math | $x^2$. No space after the opening $ or before the closing one, and no digit right after it, so $5 and $10 stays text. |
| Block math | $$ on its own line, the latex, then $$ on its own line. |
| Mention | [@Cell biology](workroad://note/<noteId>). The kind is one of note, set, subject, task, recording, test and schedule. |
| Underline | <u>underlined</u> |
| Line break in a table cell | <br> |
| Footnote | [^1] in the text and [^1]: text on a line of its own. A footnote's further blocks follow, indented four spaces. |
| Toggle | <details><summary>Summary</summary>, a blank line, the body blocks, then </details> on its own line. The summary is plain text. |
| Callout | A quote whose first line is only [!NOTE], [!TIP], [!WARNING] or [!DANGER]; the rest of the quote is the callout's body. |
| Table of contents | A [TOC] line. It is written but not read back: writing the Markdown again gives a paragraph with that text. |
Headings 5 and 6 become heading 4, the deepest the editor has. Two lists next to each other alternate between - and *, because CommonMark joins two lists with the same bullet into one.
markdownLosses lists what a note's markdown can't carry. The values are:
Folders
A folder files notes for quick access and can sit under one of the user's subjects. GET /note-folders lists every folder the key's user owns, by name, then id. POST /note-folders creates one, and a duplicate name returns 409 conflict. Names are compared exactly, so Bio and bio are different. An icon must be one of the icons the folder picker offers, or the request returns 400 invalid_request; a folder stored with an older icon reads back as Folder.
PATCH /note-folders/{folderId} changes only the fields you send, and null on subjectId unfiles the folder. Renaming to a name another of the user's folders has returns 409 conflict, as creating one does. DELETE /note-folders/{folderId} deletes the folder and unfiles its notes rather than deleting them; their content, files and embeddings are untouched.
Folder endpoints reuse the notes:* scopes: reading a folder needs notes:view, and writing one needs the matching notes:create, notes:update or notes:delete.
List notes
Newest first. Note content is omitted; fetch a single note for content. Trashed notes and templates are not listed. Each note carries its icon, its cover image URL and its tags.
Required scopes: notes:view
AuthorizationBearer <token>limit?integerPage size, 1-100.
1 <= value <= 10025cursor?|Opaque. Pass nextCursor from the previous page unchanged.
folderId?|none for notes outside any folder, or a folder id for that folder's notes.
OK
application/json- response
data*array<>nextCursor*|Opaque. Pass as ?cursor= unchanged to fetch the next page. null on the last page.
curl -X GET 'https://workroad.app/api/v1/notes' \ -H 'Authorization: Bearer $WORKROAD_API_KEY'{ "data": [ { "id": "3c2b1a09-8f7e-4d6c-9b5a-4f3e2d1c0b9a", "name": "Photosynthesis", "folder": { "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "name": "Biology", "subjectId": null }, "subjectId": "5f0c1d2e-3a4b-4c5d-8e6f-7a8b9c0d1e2f", "icon": "🌱", "cover": "https://workroad.example/api/storage/note/3c2b1a09-8f7e-4d6c-9b5a-4f3e2d1c0b9a/cover-1a2b3c4d.jpg", "tags": [ { "id": "5f4e3d2c-1b0a-4938-8776-655443322110", "name": "Exam" } ], "createdAt": "2026-01-15T09:30:00.000Z", "updatedAt": "2026-02-01T12:00:00.000Z" } ], "nextCursor": null}Create a note
Creates a note, optionally inside one of the user's folders and under one of their subjects. Send markdown to give it content; without it the note is empty.
Use this to save content you wrote yourself. It uses none of the user's WorkRoad AI uses.
Required scopes: notes:create
AuthorizationBearer <token>Idempotency-Key?stringA client-generated key (1 to 255 visible ASCII characters) that makes this POST safe to retry. A retry with the same key and body replays the original response; the same key with a different body returns 409 idempotency_conflict. Stored for 24 hours.
^[\x21-\x7E]{1,255}$1 <= length <= 255application/json- body
Creates a note, empty unless markdown is sent.
name*string1 <= length <= 64folderId?|Must be a folder owned by the key's user.
subjectId?|The note's own subject, which wins over its folder's. Must be a subject owned by the key's user (GET /subjects); any other id is refused with 400 unknown-subject. Omit it to file the note under its folder's subject.
markdown?stringMarkdown, up to 100000 characters. Stored as editor JSON, not as Markdown.
length <= 100000Created
application/json- response
data*curl -X POST 'https://workroad.app/api/v1/notes' \ -H 'Authorization: Bearer $WORKROAD_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "name": "string"}'{ "data": { "id": "3c2b1a09-8f7e-4d6c-9b5a-4f3e2d1c0b9a", "name": "Photosynthesis", "folder": { "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "name": "Biology", "subjectId": null }, "subjectId": "5f0c1d2e-3a4b-4c5d-8e6f-7a8b9c0d1e2f", "icon": "🌱", "cover": "https://workroad.example/api/storage/note/3c2b1a09-8f7e-4d6c-9b5a-4f3e2d1c0b9a/cover-1a2b3c4d.jpg", "tags": [ { "id": "5f4e3d2c-1b0a-4938-8776-655443322110", "name": "Exam" } ], "createdAt": "2026-01-15T09:30:00.000Z", "updatedAt": "2026-02-01T12:00:00.000Z", "fullWidth": false, "contentFormat": "tiptap", "contentUnstable": true, "content": { "type": "doc", "content": [ { "type": "paragraph", "attrs": { "id": "6d5c4b3a-2f1e-4d0c-9b8a-7f6e5d4c3b2a" }, "content": [ { "type": "text", "text": "Light becomes chemical energy." } ] } ] }, "markdown": "Light becomes chemical energy.", "markdownLosses": [], "version": 3, "pinned": false, "summary": { "summary": "How plants turn light into sugar.", "keywords": [ "chlorophyll", "glucose", "light reactions" ], "createdAt": "2026-02-01T12:00:00.000Z" } }}Get a note with content
Returns a note with its editor content and the same content as Markdown.
subjectId is the note's own subject when set; otherwise it inherits its folder's subject. folder is null when the note is not in a folder. See the response schema for the remaining fields.
Required scopes: notes:view
AuthorizationBearer <token>noteId*stringNote id, scoped to the key's user.
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$uuidOK
application/json- response
data*curl -X GET 'https://workroad.app/api/v1/notes/497f6eca-6276-4993-bfeb-53cbbbba6f08' \ -H 'Authorization: Bearer $WORKROAD_API_KEY'{ "data": { "id": "3c2b1a09-8f7e-4d6c-9b5a-4f3e2d1c0b9a", "name": "Photosynthesis", "folder": { "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "name": "Biology", "subjectId": null }, "subjectId": "5f0c1d2e-3a4b-4c5d-8e6f-7a8b9c0d1e2f", "icon": "🌱", "cover": "https://workroad.example/api/storage/note/3c2b1a09-8f7e-4d6c-9b5a-4f3e2d1c0b9a/cover-1a2b3c4d.jpg", "tags": [ { "id": "5f4e3d2c-1b0a-4938-8776-655443322110", "name": "Exam" } ], "createdAt": "2026-01-15T09:30:00.000Z", "updatedAt": "2026-02-01T12:00:00.000Z", "fullWidth": false, "contentFormat": "tiptap", "contentUnstable": true, "content": { "type": "doc", "content": [ { "type": "paragraph", "attrs": { "id": "6d5c4b3a-2f1e-4d0c-9b8a-7f6e5d4c3b2a" }, "content": [ { "type": "text", "text": "Light becomes chemical energy." } ] } ] }, "markdown": "Light becomes chemical energy.", "markdownLosses": [], "version": 3, "pinned": false, "summary": { "summary": "How plants turn light into sugar.", "keywords": [ "chlorophyll", "glucose", "light reactions" ], "createdAt": "2026-02-01T12:00:00.000Z" } }}Update a note
Renames the note, moves it into or out of a folder, files it under a subject, pins it, or sets its icon. Only the fields you send change. Content is written with PUT /notes/{noteId}/content. The cover image and the tags are read here but set in the app.
Required scopes: notes:update
AuthorizationBearer <token>noteId*stringNote id, scoped to the key's user.
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$uuidapplication/json- body
Send only the fields to change. Content changes go through PUT /notes/{noteId}/content (replace) and POST /notes/{noteId}/content/append.
name?string1 <= length <= 64folderId?|A folder owned by the key's user. null takes the note out of its folder.
pinned?booleanPins the note on the notes home. Templates cannot be pinned.
subjectId?|The note's own subject, which wins over its folder's. Must be a subject owned by the key's user (GET /subjects); any other id is refused with 400 unknown-subject. null clears it, so the note takes its folder's subject again.
icon?|One emoji shown beside the note's name, such as 📘 or 🇫🇷: a single emoji, not text or several emoji. null removes it. The note's cover image and its tags are set in the app, not through this endpoint.
OK
application/json- response
data*curl -X PATCH 'https://workroad.app/api/v1/notes/497f6eca-6276-4993-bfeb-53cbbbba6f08' \ -H 'Authorization: Bearer $WORKROAD_API_KEY' \ -H 'Content-Type: application/json' \ -d '{}'{ "data": { "id": "3c2b1a09-8f7e-4d6c-9b5a-4f3e2d1c0b9a", "name": "Photosynthesis", "folder": { "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "name": "Biology", "subjectId": null }, "subjectId": "5f0c1d2e-3a4b-4c5d-8e6f-7a8b9c0d1e2f", "icon": "🌱", "cover": "https://workroad.example/api/storage/note/3c2b1a09-8f7e-4d6c-9b5a-4f3e2d1c0b9a/cover-1a2b3c4d.jpg", "tags": [ { "id": "5f4e3d2c-1b0a-4938-8776-655443322110", "name": "Exam" } ], "createdAt": "2026-01-15T09:30:00.000Z", "updatedAt": "2026-02-01T12:00:00.000Z", "fullWidth": false, "contentFormat": "tiptap", "contentUnstable": true, "content": { "type": "doc", "content": [ { "type": "paragraph", "attrs": { "id": "6d5c4b3a-2f1e-4d0c-9b8a-7f6e5d4c3b2a" }, "content": [ { "type": "text", "text": "Light becomes chemical energy." } ] } ] }, "markdown": "Light becomes chemical energy.", "markdownLosses": [], "version": 3, "pinned": false, "summary": { "summary": "How plants turn light into sugar.", "keywords": [ "chlorophyll", "glucose", "light reactions" ], "createdAt": "2026-02-01T12:00:00.000Z" } }}Write note content as Markdown
Converts markdown (up to 100000 characters) to the editor format and replaces the note's content with it. To add blocks after the existing ones, use POST /notes/{noteId}/content/append. A replace keeps the inline images that are still in the Markdown, written as  the way GET /notes/{noteId} returns them, and deletes the ones it leaves out. An image whose upload the web editor hasn't confirmed yet can still be deleted 24 hours after the upload. Send baseVersion to write only if nobody saved since you read the note.
Use this to save content you wrote yourself. It uses none of the user's WorkRoad AI uses.
Required scopes: notes:update
AuthorizationBearer <token>noteId*stringNote id, scoped to the key's user.
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$uuidapplication/json- body
markdown*stringMarkdown, up to 100000 characters. Stored as editor JSON, not as Markdown.
length <= 100000baseVersion?integerThe version you last read. When the note has changed since, nothing is written and the response is 409. Omit it to write regardless.
0 <= value <= 9007199254740991OK
application/json- response
data*curl -X PUT 'https://workroad.app/api/v1/notes/497f6eca-6276-4993-bfeb-53cbbbba6f08/content' \ -H 'Authorization: Bearer $WORKROAD_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "markdown": "string"}'{ "data": { "id": "3c2b1a09-8f7e-4d6c-9b5a-4f3e2d1c0b9a", "name": "Photosynthesis", "folder": { "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "name": "Biology", "subjectId": null }, "subjectId": "5f0c1d2e-3a4b-4c5d-8e6f-7a8b9c0d1e2f", "icon": "🌱", "cover": "https://workroad.example/api/storage/note/3c2b1a09-8f7e-4d6c-9b5a-4f3e2d1c0b9a/cover-1a2b3c4d.jpg", "tags": [ { "id": "5f4e3d2c-1b0a-4938-8776-655443322110", "name": "Exam" } ], "createdAt": "2026-01-15T09:30:00.000Z", "updatedAt": "2026-02-01T12:00:00.000Z", "fullWidth": false, "contentFormat": "tiptap", "contentUnstable": true, "content": { "type": "doc", "content": [ { "type": "paragraph", "attrs": { "id": "6d5c4b3a-2f1e-4d0c-9b8a-7f6e5d4c3b2a" }, "content": [ { "type": "text", "text": "Light becomes chemical energy." } ] } ] }, "markdown": "Light becomes chemical energy.", "markdownLosses": [], "version": 3, "pinned": false, "summary": { "summary": "How plants turn light into sugar.", "keywords": [ "chlorophyll", "glucose", "light reactions" ], "createdAt": "2026-02-01T12:00:00.000Z" } }}Append Markdown to a note
Converts markdown (up to 100000 characters) to the editor format and adds it after the note's existing blocks. Send Idempotency-Key so a retry can't append twice. Sending baseVersion too makes a retry without a key fail with 409 instead of appending again.
Use this to save content you wrote yourself. It uses none of the user's WorkRoad AI uses.
Required scopes: notes:update
AuthorizationBearer <token>noteId*stringNote id, scoped to the key's user.
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$uuidIdempotency-Key?stringA client-generated key (1 to 255 visible ASCII characters) that makes this POST safe to retry. A retry with the same key and body replays the original response; the same key with a different body returns 409 idempotency_conflict. Stored for 24 hours.
^[\x21-\x7E]{1,255}$1 <= length <= 255application/json- body
markdown*stringMarkdown, up to 100000 characters. Stored as editor JSON, not as Markdown.
length <= 100000baseVersion?integerThe version you last read. When the note has changed since, nothing is written and the response is 409. Omit it to write regardless.
0 <= value <= 9007199254740991OK
application/json- response
data*curl -X POST 'https://workroad.app/api/v1/notes/497f6eca-6276-4993-bfeb-53cbbbba6f08/content/append' \ -H 'Authorization: Bearer $WORKROAD_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "markdown": "string"}'{ "data": { "id": "3c2b1a09-8f7e-4d6c-9b5a-4f3e2d1c0b9a", "name": "Photosynthesis", "folder": { "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "name": "Biology", "subjectId": null }, "subjectId": "5f0c1d2e-3a4b-4c5d-8e6f-7a8b9c0d1e2f", "icon": "🌱", "cover": "https://workroad.example/api/storage/note/3c2b1a09-8f7e-4d6c-9b5a-4f3e2d1c0b9a/cover-1a2b3c4d.jpg", "tags": [ { "id": "5f4e3d2c-1b0a-4938-8776-655443322110", "name": "Exam" } ], "createdAt": "2026-01-15T09:30:00.000Z", "updatedAt": "2026-02-01T12:00:00.000Z", "fullWidth": false, "contentFormat": "tiptap", "contentUnstable": true, "content": { "type": "doc", "content": [ { "type": "paragraph", "attrs": { "id": "6d5c4b3a-2f1e-4d0c-9b8a-7f6e5d4c3b2a" }, "content": [ { "type": "text", "text": "Light becomes chemical energy." } ] } ] }, "markdown": "Light becomes chemical energy.", "markdownLosses": [], "version": 3, "pinned": false, "summary": { "summary": "How plants turn light into sugar.", "keywords": [ "chlorophyll", "glucose", "light reactions" ], "createdAt": "2026-02-01T12:00:00.000Z" } }}Move a note to the trash
The note disappears from every read and stops being searchable. Its files stay, and POST /notes/{noteId}/restore brings it back. The trash is emptied after 30 days.
Required scopes: notes:delete
AuthorizationBearer <token>noteId*stringNote id, scoped to the key's user.
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$uuidOK
application/json- response
data*curl -X DELETE 'https://workroad.app/api/v1/notes/497f6eca-6276-4993-bfeb-53cbbbba6f08' \ -H 'Authorization: Bearer $WORKROAD_API_KEY'{ "data": { "id": "3c2b1a09-8f7e-4d6c-9b5a-4f3e2d1c0b9a", "deleted": true }}Restore a note from the trash
Brings a trashed note back and returns it. Needs notes:delete, the scope that trashed it. Restoration succeeds even above the file or storage limit. Restored files count toward the limits on the next upload.
Required scopes: notes:delete
AuthorizationBearer <token>noteId*stringNote id, scoped to the key's user.
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$uuidIdempotency-Key?stringA client-generated key (1 to 255 visible ASCII characters) that makes this POST safe to retry. A retry with the same key and body replays the original response; the same key with a different body returns 409 idempotency_conflict. Stored for 24 hours.
^[\x21-\x7E]{1,255}$1 <= length <= 255OK
application/json- response
data*curl -X POST 'https://workroad.app/api/v1/notes/497f6eca-6276-4993-bfeb-53cbbbba6f08/restore' \ -H 'Authorization: Bearer $WORKROAD_API_KEY'{ "data": { "id": "3c2b1a09-8f7e-4d6c-9b5a-4f3e2d1c0b9a", "name": "Photosynthesis", "folder": { "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "name": "Biology", "subjectId": null }, "subjectId": "5f0c1d2e-3a4b-4c5d-8e6f-7a8b9c0d1e2f", "icon": "🌱", "cover": "https://workroad.example/api/storage/note/3c2b1a09-8f7e-4d6c-9b5a-4f3e2d1c0b9a/cover-1a2b3c4d.jpg", "tags": [ { "id": "5f4e3d2c-1b0a-4938-8776-655443322110", "name": "Exam" } ], "createdAt": "2026-01-15T09:30:00.000Z", "updatedAt": "2026-02-01T12:00:00.000Z", "fullWidth": false, "contentFormat": "tiptap", "contentUnstable": true, "content": { "type": "doc", "content": [ { "type": "paragraph", "attrs": { "id": "6d5c4b3a-2f1e-4d0c-9b8a-7f6e5d4c3b2a" }, "content": [ { "type": "text", "text": "Light becomes chemical energy." } ] } ] }, "markdown": "Light becomes chemical energy.", "markdownLosses": [], "version": 3, "pinned": false, "summary": { "summary": "How plants turn light into sugar.", "keywords": [ "chlorophyll", "glucose", "light reactions" ], "createdAt": "2026-02-01T12:00:00.000Z" } }}List note folders
Every folder owned by the key's user, sorted by name, then id.
Required scopes: notes:view
AuthorizationBearer <token>OK
application/json- response
data*array<>curl -X GET 'https://workroad.app/api/v1/note-folders' \ -H 'Authorization: Bearer $WORKROAD_API_KEY'{ "data": [ { "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "name": "Biology", "subjectId": null, "icon": "Folder" } ]}Create a note folder
Creates a folder, optionally filed under one of the user's subjects by subjectId or subjectName.
Required scopes: notes:create
AuthorizationBearer <token>Idempotency-Key?stringA client-generated key (1 to 255 visible ASCII characters) that makes this POST safe to retry. A retry with the same key and body replays the original response; the same key with a different body returns 409 idempotency_conflict. Stored for 24 hours.
^[\x21-\x7E]{1,255}$1 <= length <= 255application/json- body
name*string1 <= length <= 64subjectId?stringSubject id owned by the user.
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$uuidsubjectName?stringThe subject (the course or module, such as Software Engineering) by name instead of by id. It must match one of the user's active subjects, ignoring case and accents. A name that matches none is refused with 400 unknown-subject, whose details.subjects lists the user's subjects, unless createSubjectIfMissing is true. Send subjectId or subjectName, not both.
1 <= length <= 64createSubjectIfMissing?booleanWith subjectName, creates the subject when the user has none by that name. Needs the subjects:create scope. Only send it when the user named a course they haven't added yet.
icon?stringIcon name shown in the UI.
"Folder""Folder""File""Book""Bookmark""Star""Heart""Flag""Tag""Inbox""Archive""GraduationCap""School""Backpack""Notebook""Pencil""Ruler""Calculator""Globe""Microscope""TestTube""Dna""Atom""Rocket""Telescope""Code""Terminal""Database""Server""Cpu""Wifi""Cloud""Bug""QrCode""PlusSquare""MinusSquare""DivideSquare""Percent""Sigma""Pi""Infinity""BarChart""LineChart""Magnet""Thermometer""Leaf""Droplet""Flame""Zap""Wind""Palette""Music""Camera""Video""Brush""Pen""Scissors""Shapes""Briefcase""TrendingUp""PieChart""DollarSign""CreditCard""ShoppingCart""Activity""Stethoscope""Apple""Dumbbell""Calendar""Clock""Timer""Hourglass""AlarmClock""MessageSquare""Mail""Phone""Share""Link""Coffee""Lightbulb""Map""Compass""Target""Trophy""Puzzle""Gift""Smile"Created
application/json- response
data*curl -X POST 'https://workroad.app/api/v1/note-folders' \ -H 'Authorization: Bearer $WORKROAD_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "name": "string"}'{ "data": { "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "name": "Biology", "subjectId": null, "icon": "Folder" }}Update a note folder
Changes only the fields you send; null on subjectId unfiles the folder. Renaming to a name another of the user's folders already has is refused, as when creating one.
Required scopes: notes:update
AuthorizationBearer <token>folderId*stringNote folder id, scoped to the key's user.
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$uuidapplication/json- body
Send only the fields to change. An omitted field stays as it is.
name?string1 <= length <= 64subjectId?|Subject id owned by the user. null unfiles the folder.
icon?stringIcon name shown in the UI.
"Folder""File""Book""Bookmark""Star""Heart""Flag""Tag""Inbox""Archive""GraduationCap""School""Backpack""Notebook""Pencil""Ruler""Calculator""Globe""Microscope""TestTube""Dna""Atom""Rocket""Telescope""Code""Terminal""Database""Server""Cpu""Wifi""Cloud""Bug""QrCode""PlusSquare""MinusSquare""DivideSquare""Percent""Sigma""Pi""Infinity""BarChart""LineChart""Magnet""Thermometer""Leaf""Droplet""Flame""Zap""Wind""Palette""Music""Camera""Video""Brush""Pen""Scissors""Shapes""Briefcase""TrendingUp""PieChart""DollarSign""CreditCard""ShoppingCart""Activity""Stethoscope""Apple""Dumbbell""Calendar""Clock""Timer""Hourglass""AlarmClock""MessageSquare""Mail""Phone""Share""Link""Coffee""Lightbulb""Map""Compass""Target""Trophy""Puzzle""Gift""Smile"OK
application/json- response
data*curl -X PATCH 'https://workroad.app/api/v1/note-folders/497f6eca-6276-4993-bfeb-53cbbbba6f08' \ -H 'Authorization: Bearer $WORKROAD_API_KEY' \ -H 'Content-Type: application/json' \ -d '{}'{ "data": { "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "name": "Biology", "subjectId": null, "icon": "Folder" }}Move a note folder to the trash
Moves the folder and every note in it to the trash. POST /note-folders/{folderId}/restore brings back the folder and the notes that went with it. The trash is emptied after 30 days.
Required scopes: notes:delete
AuthorizationBearer <token>folderId*stringNote folder id, scoped to the key's user.
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$uuidOK
application/json- response
data*curl -X DELETE 'https://workroad.app/api/v1/note-folders/497f6eca-6276-4993-bfeb-53cbbbba6f08' \ -H 'Authorization: Bearer $WORKROAD_API_KEY'{ "data": { "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "deleted": true }}Restore a note folder from the trash
Brings a trashed folder back with the notes that went to the trash with it, and returns the folder. Needs notes:delete, the scope that trashed it. If a live folder took its name meanwhile, the restored folder is renamed name (2), name (3) and so on. Notes trashed on their own before the folder stay in the trash.
Required scopes: notes:delete
AuthorizationBearer <token>folderId*stringNote folder id, scoped to the key's user.
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$uuidIdempotency-Key?stringA client-generated key (1 to 255 visible ASCII characters) that makes this POST safe to retry. A retry with the same key and body replays the original response; the same key with a different body returns 409 idempotency_conflict. Stored for 24 hours.
^[\x21-\x7E]{1,255}$1 <= length <= 255OK
application/json- response
data*curl -X POST 'https://workroad.app/api/v1/note-folders/497f6eca-6276-4993-bfeb-53cbbbba6f08/restore' \ -H 'Authorization: Bearer $WORKROAD_API_KEY'{ "data": { "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "name": "Biology", "subjectId": null, "icon": "Folder" }}