In this document, the Notes API major version 1 and all its minor versions are described. An introduction with general information about versions, capabilities, compatibility between versions, authentication and input parameters can be found in the README.
| API version | Introduced with app version | Remarkable Changes |
|---|---|---|
| 1.0 | Notes 3.3 (May 2020) | Separate title, no auto rename based on content |
| 1.1 | Notes 3.4 (May 2020) | Filter "Get all notes" by category |
| 1.2 | Notes 4.1 (June 2021) | Preventing lost updates, read-only notes, settings |
| 1.3 | Notes 4.5 (August 2022) | Allow custom file suffixes |
The app and the API is mainly about notes. So, let's have a look about the attributes of a note. The description of endpoints and operations will refer to this attribute definition.
| Attribute | Type | Description | since API version |
|---|---|---|---|
id |
integer (read‑only) | Every note has a unique identifier which is created by the server. It can be used to query and update a specific note. | 1.0 |
etag |
string (read‑only) | The note's entity tag (ETag) indicates if a note's attribute has changed. I.e., if the note changes, the ETag changes, too. Clients can use the ETag for detecting if the local note has to be updated from server and for optimistic concurrency control (see section Preventing lost updates and conflict solution). | 1.2 |
readonly |
boolean (read‑only) | Indicates if the note is read-only. This is true, e.g., if a file or folder was shared by another user without allowing editing. If this attribute is true, then all read/write attributes become read-only; except for the favorite attribute. |
1.2 |
content |
string (read/write) | Notes can contain arbitrary text. Formatting should be done using Markdown, but not every markup can be supported by every client. Therefore, markup should be used with care. | 1.0 |
title |
string (read/write) | The note's title is also used as filename for the note's file. Therefore, some special characters are automatically removed and a sequential number is added if a note with the same title in the same category exists. When saving a title, the sanitized value is returned and should be adopted by your client. | 1.0 |
category |
string (read/write) | Every note is assigned to a category. By default, the category is an empty string (not null), which means the note is uncategorized. Categories are mapped to folders in the file backend. Illegal characters are automatically removed and the respective folder is automatically created. Sub-categories (mapped to sub-folders) can be created by using / as delimiter. |
1.0 |
favorite |
boolean (read/write) | If a note is marked as favorite, it is displayed at the top of the notes' list. Default is false. |
1.0 |
modified |
integer (read/write) | Unix timestamp for the last modified date/time of the note. If not provided on note creation or content update, the current time is used. | 1.0 |
Since API version 1.2, it is possible to change app settings using the API. The following settings attributes exist:
| Attribute | Type | Description | since API version |
|---|---|---|---|
notesPath |
string | Path to the folder, where note's files are stored in Nextcloud. The path must be relative to the user folder. Default is the localized string Notes. |
1.2 |
fileSuffix |
string | Newly created note's files will have this file suffix. For API version 1.2, only the values .txt or .md are allowed. Since API version 1.3, also custom suffixes can be chosen. Default is .txt. |
1.2 |
The base URL for all calls is:
https://user:password@yournextcloud.com/index.php/apps/notes/api/v1/
All defined routes in the specification are appended to this url. To access all notes for instance use this url (here shown as curl command):
curl -u user:password -H "Accept: application/json" https://yournextcloud.com/index.php/apps/notes/api/v1/notes
Details
| Parameter | Type | Description | since API version |
|---|---|---|---|
category |
string, optional | Filter the result by category name, e.g. ?category=recipes. Notes with another category are not included in the result. Compatibility note: before API v1.1, this parameter is ignored; i.e., the result contains all notes regardless of this parameter. |
1.1 |
exclude |
string, optional | Fields which should be excluded from response, seperated with a comma e.g.: ?exclude=content,title. You can use this in order to reduce transferred data size if you are interested in specific attributes, only. |
1.0 |
pruneBefore |
integer, optional | All notes without change before of this Unix timestamp are purged from the response, i.e. only the attribute id is included. You should use the Unix timestamp value from the last request's HTTP response header Last-Modified in order to reduce transferred data size. |
1.0 |
chunkSize |
integer, optional | The response will contain no more than the given number of full notes. If there are more notes, then the result is chunked and the HTTP response header X-Notes-Chunk-Cursor is sent with a string value. In order to request the next chunk, a new request have to be made with parameter chunkCursor filled with that string value. Compatibility note: before API v1.2, this parameter is ignored; i.e., the result contains all notes regardless of this parameter. |
1.2 |
chunkCursor |
string, optional | To be used together with the parameter chunkSize. You must use the string value from the last request's HTTP response header X-Notes-Chunk-Cursor in order to get the next chunk of notes. Don't use this parameter for requesting the first chunk. Compatibility note: before API v1.2, this parameter is ignored; i.e., the result contains all notes regardless of this parameter. |
1.2 |
If-None-Match |
HTTP header, optional | Use this in order to reduce transferred data size (see HTTP ETag). You should use the value from the last request's HTTP response header ETag. |
1.0 |
- HTTP Header:
ETag(see HTTP ETag).X-Notes-Chunk-Cursor: Only ifchunkSizeis provided and not0and if the response does not contain all remaining notes. In this case, the response does not contain pruned notes. In order to get the next chunk, you will have to make a new request and use this header value as request parameterchunkCursor. The last chunk response will not contain this header but it will contain all pruned notes. In summary: a client have to repeatedly request the notes list from server with the desiredchunkSizeand with updatedchunkCursoruntil the response does not contain anyX-Notes-Chunk-CursorHTTP header – only this last request can be used to check for deleted notes.X-Notes-Chunk-Pending: number of pending notes that have to be requested using the chunk cursor provided in the HTTP response headerX-Notes-Chunk-Cursor.
- Body: list of notes (see section Note attributes), example:
[
{
"id": 76,
"etag": "be284e00488c61c101ee28309d235e0b",
"readonly": false,
"modified": 1376753464,
"title": "New note",
"category": "sub-directory",
"content": "New note\n and something more",
"favorite": false
}, // etc
]No valid authentication credentials supplied.
Details
| Parameter | Type | Description |
|---|---|---|
id |
integer, required (path) | ID of the note to query. |
If-None-Match |
HTTP header, optional | Use this in order to reduce transferred data size (see HTTP ETag). You should use the value from the note's attribute etag or from the last request's HTTP response header ETag. |
- HTTP Header:
ETag(see HTTP ETag). The value is identical to the note's attributeetag(see section Note attributes). - Body: note (see section Note attributes), example:
{
"id": 76,
"etag": "be284e00488c61c101ee28309d235e0b",
"readonly": false,
"modified": 1376753464,
"title": "New note",
"category": "sub-directory",
"content": "New note\n and something more",
"favorite": false
}Invalid ID supplied.
No valid authentication credentials supplied.
Note not found.
Details
- Body: some or all "read/write" attributes (see section Note attributes), example:
{
"title": "New note",
"category": "Category/Sub Category",
"content": "New note\n and something more",
}- Body: note (see section Note attributes), example see section Get single note.
Invalid ID supplied.
No valid authentication credentials supplied.
Not enough free storage for saving the note's content.
Details
| Parameter | Type | Description |
|---|---|---|
id |
integer, required (path) | ID of the note to update. |
If-Match |
HTTP header, optional | Use this for optimistic concurrency control (optional, but strongly recommended in order to prevent lost updates). As value of this HTTP header, the client has to use the last known note's etag (see section Note attributes). If the note has changed in the meanwhile (concurrent change), the update request is blocked with HTTP status 412 (see below). Otherwise, the request will be processed normally. |
- Body: some or all "read/write" attributes (see section Note attributes), example see section Create note.
- Body: note (see section Note attributes), example see section Get single note.
Invalid ID supplied.
No valid authentication credentials supplied.
The note is read-only.
Note not found.
(since API v1.2) Update cannot be performed since the note has been changed on the server in the meanwhile (concurrent change). The body contains the current note's state from server (see section Note attributes), example see section Get single note. The client should use this response data in order to perform a conflict solution (see section Preventing lost updates and conflict solution).
Not enough free storage for saving the note's content.
Details
| Parameter | Type | Description |
|---|---|---|
id |
integer, required (path) | ID of the note to delete. |
Note is deleted.
Invalid ID supplied.
No valid authentication credentials supplied.
The note is read-only.
Note not found.
Details
(since API v1.2)
None.
- Body: user's app settings (see section Settings), example:
{
"notesPath": "Notes",
"fileSuffix": ".txt"
}Endpoint not supported by installed notes app version (requires API version 1.2).
No valid authentication credentials supplied.
Details
(since API v1.2)
- Body: some or all settings attributes (see section Settings). Omitted settings attributes are not changed. Empty values are replaced by the settings attribute's default value. All values are sanitized (e.g. prevent path traversal attacks, check allowed suffixes), so the result can differ from the request (the request will still succeed). The client may show an information to the user if the response differs from the request. Example:
{
"fileSuffix": ".md"
}- Body: user's app settings after validation (see section Settings), example see section Get settings.
Endpoint not supported by installed notes app version (requires API version 1.2).
No valid authentication credentials supplied.
While changing a note using a Notes client, the same note may be changed by another client.
In order to prevent lost updates of those concurrent changes, the notes API uses a well established mechanism called optimistic concurrency control.
For this purpose, notes have the attribute etag which is an identifier that changes if (and only if) the note changes on the server.
Clients have to store the etag for every note and send its value with every update request (HTTP header If-Match, see section Update note).
If there was no parallel change on the server (i.e., the etag on server is the same as the one send from the client), the update request is performed as usual.
But if there was a parallel change, the etag on the server has changed and the server will refuse the update request.
In this case, the client has to perform a conflict resolution, i.e. the local changes have to be merged with the remote changes. In order to compare local changes with remote changes, it is useful that the client stores the full note's state as reference state before performing any local updates. If an update conflict occurs, the client can use this reference state in order to merge all changes attribute-wise:
- Attributes, that have changed only locally or remotely, can be merged by picking the (local resp. remote) change.
- Attributes, that have changed both localy and remotely, have to be merged (see below).
There are several options on how to merge an attribute:
- a) Let the user decide: ask the user whether i) overwrite local changes, ii) overwrite remote changes, or iii) save local (or remote) changes as new note.
- b) Let the user merge: provide an interface which allows for merging the files (you know it from your version control).
- c) Try to merge automatically: merge all changes automatically, e.g. for the
contentattribute using the google-diff-match-patch (Demo, Code) library.