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

New 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

New 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 or error
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

New in version 0.15.0.

Response JSON Object:

status (string) – success or error
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

New 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 or error
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

New 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 or error
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

New in version 1.0.0.

Parameters:

fields (array) – All bookmarks fields that should be hashed (default: title, url)

Response JSON Object:

status (string) – success or error
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 array

for 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 dictionary

set object[title] to the title of the folder, if this is not the root folder

set object[children] to the value of childrenHashes

set json to to_json(object)

Return sha256(json)

hashBookmark(id, fields)

set object to an empty dictionary/hashmap

for 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

New in version 0.15.0.

Response JSON Object:

status (string) – success or error
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

New in version 0.15.0.

Response JSON Object:

status (string) – success or error

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

New in version 0.15.0.

Response JSON Object:

status (string) – success or error

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

New 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 or error
data (array) – An ordered list of child items

Response JSON Array of Objects:

type (string) – Either folder or bookmark
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

New 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 or bookmark
id (string) – The id of the bookmark or folder

Response JSON Object:

status (string) – success or error

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)

New 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 or error
data (array) – An ordered list of child items

Response JSON Array of Objects:

type (string) – Either folder or bookmark
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

New in version 3.4.0.

Response JSON Object:

status (string) – success or error
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.

New in version 3.0.0.

Response JSON Object:

status (string) – success or error
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

New in version 3.0.0.

Response JSON Object:

status (string) – success or error
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

New in version 3.0.0.

Response JSON Object:

status (string) – success or error

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.

New 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/"},
  ]
}