Folders
Folder model
- Folder
- Param int id:
The folder’s unique id
- Param string title:
The humanly-readable label for the folder
- Param int parent_folder:
The folder’s parent folder
- Param string userId:
The user ID of the nextcloud account that owns this folder
- Param string userDisplayName:
The name of the nextcloud account that owns this folder
Added in version 12.1.0.
Note
The root folder has the magic id
-1
, which is the same for every user.
Get full folder hierarchy
- GET /public/rest/v2/folder
- Synopsis:
Retrieve the folder hierarchy
Added in version 0.15.0.
- Query Parameters:
root (int) – The id of the folder whose contents to retrieve (Default:
-1
, which is the root folder)layers (int) – How many layers of folders to return at max. By default, all layers are returned.
- Response JSON Object:
status (string) –
success
orerror
data (array) – The folder hierarchy
- Response JSON Array of Objects:
id (int) – The id of the folder
title (string) – the folder title
parent_folder (int) – the folder’s parent folder
children (array) – The folder’s children (folders only)
Example:
GET /index.php/apps/bookmarks/public/rest/v2/folder HTTP/1.1 Host: example.com Accept: application/json
Response:
HTTP/1.1 200 OK Content-Type: application/json { "status": "success", "data": [ {"id": 1, "title": "work", "parent_folder": -1}, {"id": 2, "title": "personal", "parent_folder": -1, "children": [ {"id": 3, "title": "garden", "parent_folder": 2}, {"id": 4, "title": "music", "parent_folder": 2} ]}, ] }
Get single folder
- GET /public/rest/v2/folder/(int: id)
- Synopsis:
Retrieve a single folder
Added in version 0.15.0.
- Response JSON Object:
status (string) –
success
orerror
item (object) – The retrieved folder
Example:
GET /index.php/apps/bookmarks/public/rest/v2/folder/2 HTTP/1.1 Host: example.com Accept: application/json
Response:
HTTP/1.1 200 OK Content-Type: application/json { "status": "success", "item": { "id": 2, "title": "My Personal Bookmarks", "parent_folder": -1 } }
Create a folder
- POST /public/rest/v2/folder
- Synopsis:
Create a new folder
Added in version 0.15.0.
- Request JSON Object:
title (string) – The title of the new folder, defaults to “”
parent_folder (int) – The id of the parent folder for the new folder, defaults to -1
- Response JSON Object:
status (string) –
success
orerror
item (object) – The new folder
Example:
POST /index.php/apps/bookmarks/public/rest/v2/folder HTTP/1.1 Host: example.com Accept: application/json {"title": "sports", "parent_folder": "-1"}
Response:
HTTP/1.1 200 OK Content-Type: application/json { "status": "success", "item": { "id": 5, "title": "sports", "parent_folder": "-1" } }
Edit a folder
- PUT /public/rest/v2/folder/(int: id)
- Synopsis:
Edit an existing folder
Added in version 0.15.0.
- Request JSON Object:
title (string) – The title of the new folder
parent_folder (int) – The id of the parent folder of the folder
- Response JSON Object:
status (string) –
success
orerror
item (object) – The new folder
Example:
POST /index.php/apps/bookmarks/public/rest/v2/folder/5 HTTP/1.1 Host: example.com Accept: application/json {"title": "optional physical activity"}
Response:
HTTP/1.1 200 OK Content-Type: application/json { "status": "success", "item": { "id": 5, "title": "optional physical activity", "parent_folder": -1 } }
Hash a folder
- GET /public/rest/v2/folder/(int: id)/hash
- Synopsis:
Compute the hash of a folder
Added in version 1.0.0.
- Parameters:
fields (array) – All bookmarks fields that should be hashed (default:
title
,url
)
- Response JSON Object:
status (string) –
success
orerror
data (string) – The SHA256 hash in hexadecimal notation
This endpoint is useful for synchronizing data between the server and a client. By comparing the hash of the data on your client with the hash from the server you can figure out which parts of the tree have changed.
The algorithm works as follows:
Hash endpoint: return
hashFolder(id, fields)
hashFolder(id, fields)
set
childrenHashes
to empty arrayfor all children of the folder
if it’s a folder
add to
childrenHashes
:hashFolder(folderId, fields)
if it’s a bookmark
add to
childrenHashes
:hashBookmark(bookmarkId, fields)
set
object
to an empty dictionaryset
object[title]
to the title of the folder, if this is not the root folderset
object[children]
to the value ofchildrenHashes
set
json
toto_json(object)
Return
sha256(json)
hashBookmark(id, fields)
set
object
to an empty dictionary/hashmapfor all entries in
fields
set
object[field]
to the value of the associated field of the bookmark
Return
sha256(to_json(object))
to_json
: A JSON stringification algorithm that adds no unnecessary white-space and doesn’t use JSON’s backslash escaping unless necessary (character set is UTF-8)sha256
: The SHA-256 hashing algorithm
Example:
GET /index.php/apps/bookmarks/public/rest/v2/folder/5/hash HTTP/1.1 Host: example.com Accept: application/json
Response:
HTTP/1.1 200 OK Content-Type: application/json { "status": "success", "data": "6543a23c78aefd0274f3ac98de98723" }
Delete a folder
- DELETE /public/rest/v2/folder/(int: id)
- Synopsis:
Delete a folder
Added in version 0.15.0.
- Response JSON Object:
status (string) –
success
orerror
item (object) – The new folder
Example:
DELETE /index.php/apps/bookmarks/public/rest/v2/folder/5 HTTP/1.1 Host: example.com Accept: application/json
Response:
HTTP/1.1 200 OK Content-Type: application/json { "status": "success" }
Add bookmark to folder
- POST /public/rest/v2/folder/(int: folder_id)/bookmarks/(int: bookmark_id)
- Synopsis:
Add a bookmark to a folder
Added in version 0.15.0.
- Response JSON Object:
status (string) –
success
orerror
Example:
POST /index.php/apps/bookmarks/public/rest/v2/folder/5/bookmarks/418 HTTP/1.1 Host: example.com Accept: application/json
Response:
HTTP/1.1 200 OK Content-Type: application/json { "status": "success" }
Remove bookmark from folder
- DELETE /public/rest/v2/folder/(int: folder_id)/bookmarks/(int: bookmark_id)
- Synopsis:
Remove a bookmark from a folder
Added in version 0.15.0.
- Response JSON Object:
status (string) –
success
orerror
If this is the only folder this bookmark resides in, the bookmark will be deleted entirely.
Example:
DELETE /index.php/apps/bookmarks/public/rest/v2/folder/5/bookmarks/418 HTTP/1.1 Host: example.com Accept: application/json
Response:
HTTP/1.1 200 OK Content-Type: application/json { "status": "success" }
Get folder’s content order
- GET /public/rest/v2/folder/(int: folder_id)/childorder
- Synopsis:
Retrieve the order of contents of a folder
Added in version 0.15.0.
- Query Parameters:
layers (int) – The number of tree layers to return, defaults to 0 which returns only the immediate children
- Response JSON Object:
status (string) –
success
orerror
data (array) – An ordered list of child items
- Response JSON Array of Objects:
type (string) – Either
folder
orbookmark
id (string) – The id of the bookmark or folder
children (array) – In case more than one layers are returned, folders will have a this additional property with an array containing more items (or none)
Example:
GET /index.php/apps/bookmarks/public/rest/v2/folder/5/childorder HTTP/1.1 Host: example.com Accept: application/json
Response:
HTTP/1.1 200 OK Content-Type: application/json { "status": "success", "data": [ {"type": "folder", "id": 17}, {"type": "bookmark", "id": 204}, {"type": "bookmark", "id": 192}, {"type": "bookmark", "id": 210} ] }
Example:
GET /index.php/apps/bookmarks/public/rest/v2/folder/5/childorder?layers=1 HTTP/1.1 Host: example.com Accept: application/json
Response:
HTTP/1.1 200 OK Content-Type: application/json { "status": "success", "data": [ {"type": "folder", "id": 17, "children": [ {"type": "bookmark", "id": 234}, {"type": "bookmark", "id": 492}, {"type": "bookmark", "id": 250}, {"type": "folder", "id": 18 } ] }, {"type": "bookmark", "id": 204}, {"type": "bookmark", "id": 192}, {"type": "bookmark", "id": 210} ] }
Set folder’s content order
- PATCH /public/rest/v2/folder/(int: folder_id)/childorder
- Synopsis:
Set the order of contents of a folder
Added in version 0.15.0.
- Request JSON Object:
data (array) – An ordered list of child items
- Request JSON Array of Objects:
type (string) – Either
folder
orbookmark
id (string) – The id of the bookmark or folder
- Response JSON Object:
status (string) –
success
orerror
Example:
PATCH /index.php/apps/bookmarks/public/rest/v2/folder/5/childorder HTTP/1.1 Host: example.com Accept: application/json { "status": "success", "data": [ {"type": "folder", "id": 17}, {"type": "bookmark", "id": 204}, {"type": "bookmark", "id": 192}, {"type": "bookmark", "id": 210} ] }
Response:
HTTP/1.1 200 OK Content-Type: application/json { "status": "success" }
Get folder’s contents
- GET /public/rest/v2/folder/(int: folder_id)/children
- Synopsis:
Retrieve all of a folder’s contents (with varying depth)
Added in version 3.0.0.
- Query Parameters:
layers (int) – How many layers of descendants to return at max. Defaults to 0, retuning only immediate children.
- Response JSON Object:
status (string) –
success
orerror
data (array) – An ordered list of child items
- Response JSON Array of Objects:
type (string) – Either
folder
orbookmark
id (string) – The id of the bookmark or folder
If the type of the item is
folder
- Response JSON Array of Objects:
id (int) – The id of the folder
title (string) – The title of the folder
userId (string) – The owner of the folder
children (array) – The children of the folder. This is only set, when the number of layers to return includes this folder.
If the type of the item is
bookmark
it will have all properties of the Bookmark type (see Bookmark model).Example:
GET /index.php/apps/bookmarks/public/rest/v2/folder/5/children HTTP/1.1 Host: example.com Accept: application/json
Response:
HTTP/1.1 200 OK Content-Type: application/json { "status": "success", "data": [ {"type": "folder", "id": "17", "title": "foo", "userId": "admin"}, {"type": "bookmark", "id": "204", "title": "Nextcloud", "url": "https://nextcloud.com/"}, {"type": "bookmark", "id": "204", "title": "Google", "url": "https://google.com/"}, ] }
Get folder’s content count
- GET /public/rest/v2/folder/(int: folder_id)/count
- Synopsis:
Retrieve the number of bookmarks contained in this folder and all descendants
Added in version 3.4.0.
- Response JSON Object:
status (string) –
success
orerror
item (int) – The number of descendant bookmarks
Example:
GET /index.php/apps/bookmarks/public/rest/v2/folder/5/count HTTP/1.1 Host: example.com Accept: application/json
Response:
HTTP/1.1 200 OK Content-Type: application/json { "status": "success", "item": 512 }
Get public token
- GET /public/rest/v2/folder/(int: folder_id)/publictoken
- Synopsis:
Retrieve the public token of a folder that has been shared via a public link. This will return a 404 if the folder has no public token yet.
Added in version 3.0.0.
- Response JSON Object:
status (string) –
success
orerror
item (string) – The public token
To use the token either make API requests with it (see User-based authentication). Or point your browser to
https://yournextcloud.com/index.php/apps/bookmarks/public/{token}
Example:
GET /index.php/apps/bookmarks/public/rest/v2/folder/5/publictoken HTTP/1.1 Host: example.com Accept: application/json
Response:
HTTP/1.1 200 OK Content-Type: application/json { "status": "success", "item": "dk3J8Qm" }
Create public token
- POST /public/rest/v2/folder/(int: folder_id)/publictoken
- Synopsis:
Create a public link for a folder
Added in version 3.0.0.
- Response JSON Object:
status (string) –
success
orerror
item (string) – The token that can be used to access the folder publicly.
Example:
POST /index.php/apps/bookmarks/public/rest/v2/folder/5/publictoken HTTP/1.1 Host: example.com Accept: application/json
Response:
HTTP/1.1 200 OK Content-Type: application/json { "status": "success", "item": "dk3J8Qm" }
Delete public token
- DELETE /public/rest/v2/folder/(int: folder_id)/publictoken
- Synopsis:
Remove the public link for a folder
Added in version 3.0.0.
- Response JSON Object:
status (string) –
success
orerror
Example:
POST /index.php/apps/bookmarks/public/rest/v2/folder/5/publictoken HTTP/1.1 Host: example.com Accept: application/json
Response:
HTTP/1.1 200 OK Content-Type: application/json { "status": "success", }
Import bookmarks into folder
- POST /public/rest/v2/folder/(int: folder_id)/import
- Synopsis:
Import an HTML bookmarks file into a folder. Returns the newly created items.
Added in version 1.1.0.
- Form Parameters:
bm_import – The HTML file to be uploaded
Example:
POST /index.php/apps/bookmarks/public/rest/v2/folder/-1/import HTTP/1.1 Host: example.com Content-Length: 5038 Content-Type: multipart/form-data; boundary=------------------------8c1687317cdae5bf --------------------------8c1687317cdae5bf Content-Disposition: form-data; name="bm_import"; filename="bookmarks.html" Content-Type: text/html <html> ...
Response:
HTTP/1.1 200 OK Content-Type: application/json { "status": "success", "data": [ {"type": "folder", "id": "17", "title": "foo", "children": [ {"type": "folder", "id": 18, "title": "bla", "children": [] } {"type": "bookmark", "id": 234, "title": "Gnome", "url": "https://www.gnome.org"}, {"type": "bookmark", "id": 492, "title": "kernel", "url": "https://www.kernel.org"}, {"type": "bookmark", "id": 250, "title": "Test", "url": "https://www.test.de"}, {"type": "folder", "id": 18, "title": "foobar" "children": [] } ] }, {"type": "bookmark", "id": "204", "title": "Nextcloud", "url": "https://nextcloud.com/"}, {"type": "bookmark", "id": "205", "title": "Google", "url": "https://google.com/"}, ] }