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

Note

The root folder has the magic id -1, which is the same for every user.

Get full 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
  • parent_folder (int) – The id of the parent folder for the new folder
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.

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

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}
  ]
}

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. By default only immediate children are returned.
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:
 
  • 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

Response JSON Array of Objects:
 
  • url (string) – The URL of the bookmark
  • title (string) – The title of the bookmark
  • description (string) – Description of the bookmark

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 contents

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

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"
}

Get 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",
}