Bookmarks 

Bookmark model 

A bookmark has at least the following properties

Bookmark

Param int id:: The bookmarks unique id
Param string url:: The Uniform Resource Locator that this bookmark represents, can be a http, ftp or (since v13.1.0) a file link

Changed in version 13.1.0.
Param string target:: The target of this bookmark, can be a http, ftp or file link or a javascript link

New in version 13.1.0.
Param string title:: A short humanly readable label for the bookmark
Param string description:: A longer description or note on the bookmark
Param int added:: The UNIX timestamp when this bookmark was created
Param string userId:: The user ID of the nextcloud account that owns this bookmark
Param array tags:: A list of tags this bookmark is tagged with
Param array folders:: The folders this bookmark has been added to
Param int clickcount:: The number of times this bookmark was opened
Param bool available:: A boolean indicating whether the app could reach the bookmarked URL

New in version 3.4.0.
Param string|null htmlContent:: The html content of the bookmarked web page

New in version 4.2.0.
Param string|null textContent:: The html content of the bookmarked web page

New in version 4.2.0.
Param int|null archivedFile:: The nextcloud file id, if this bookmark links to a non-HTML, non-plaintext file

New in version 3.4.0.

Query bookmarks 

GET /public/rest/v2/bookmark

Synopsis:: Filter and query all bookmarks by the authenticated user.

New in version 0.11.0.

Query Parameters:

tags[] – An array of tags that bookmarks returned by the endpoint should have
page – if this is non-negative, results will be paginated by limit bookmarks a page. Default: 0.
limit – Results will be paginated by this amount of bookmarks per page. Default: 10.
sortby – The column to sort the results by; one of url, title, description, public, lastmodified, clickcount. Default: lastmodified.
search[] – An array of words to search for in the following columns url, title, description, tags
conjunction – Set to and to require all search terms to be present, or if one should suffice. Default: or
folder – Only return bookmarks that are direct children of the folder with the passed ID. The root folder has id -1.
url –
Only return bookmarks with this URL. With this parameter you can test whether a URL exists in the user’s bookmarks.

New in version 1.0.0.
unavailable –
Only return bookmarks that are dead links, i.e. return 404 status codes or similar.

New in version 3.4.0.
archived –
Only return bookmarks that whose contents have been archived.

New in version 3.4.0.
untagged –
Only return bookmarks that have no tags set

New in version 0.12.0.
duplicated –
Only return bookmarks that are in multiple folders

New in version 10.2.0.

Response JSON Object:

status (string) – success or error
data (array) – The list of resulting bookmarks

Note that before v3.4.0 You couldn’t mix folder, url, unavailable and archive.

Example:

GET /index.php/apps/bookmarks/public/rest/v2/bookmark?tags[]=firsttag&tags[]=secondtag&page=-1 HTTP/1.1
Host: example.com
Accept: application/json

Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "success",
  "data": [{ "id": 7, "title": "Google", "tags": ["firsttag"] }]
}

Create a bookmark 

POST /public/rest/v2/bookmark

Synopsis:: Create a bookmark

New in version 0.11.0.

Parameters:

url – the url of the new bookmark
tags (array) – Array of tags for this bookmark (these needn’t exist and are created on-the-fly) (optional)
title (string) – the title of the bookmark. (optional; If absent the title of the html site referenced by url is used)
description (string) – A description for this bookmark (optional)
folders (array) – An array of IDs of the folders this bookmark should reside in. (optional; if absent the new bookmark will be put in the root folder)

Response JSON Object:

status (string) – success or error
item (object) – The created bookmark

Example:

POST /index.php/apps/bookmarks/public/rest/v2/bookmark?tags[]=firsttag&tags[]=secondtag&page=-1 HTTP/1.1
Host: example.com
Accept: application/json

{
  "url": "http://google.com",
  "title": "Google",
  "description":"in case i forget",
  "tags": ["search-engines", "uselessbookmark"]
}

Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "success",
  "item": {
    "id": 7,
    "url": "http://google.com",
    "title": "Google",
    "description":"in case i forget",
    "tags": ["search-engines", "uselessbookmark"],
    "folders": [-1]
  }
}

Get a bookmark 

GET /public/rest/v2/bookmark/(int: id)

Synopsis:: Retrieve a bookmark

New in version 0.11.0.

Response JSON Object:

status (string) – success or error
item (object) – The retrieved bookmark

Example:

GET /index.php/apps/bookmarks/public/rest/v2/bookmark/7 HTTP/1.1
Host: example.com
Accept: application/json

Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "success",
  "item": {
    "id": 7,
    "url": "http://google.com",
    "title": "Google",
    "description":"in case i forget",
    "tags": ["search-engines", "uselessbookmark"],
    "folders": [-1]
  }
}

Edit a bookmark 

PUT /public/rest/v2/bookmark/(int: id)

Synopsis:: Edit a bookmark

New in version 0.11.0.

Parameters:

url – the url of the new bookmark (optional; if absent will not be changed)
tags (array) – Array of tags for this bookmark (these needn’t exist and are created on-the-fly). (optional; if absent, will not be changed)
title (string) – the title of the bookmark. (optional; if absent, will not be changed)
description (string) – A description for this bookmark (optional; if absent, will not be changed)
folders (array) – An array of IDs of the folders this bookmark should reside in, the bookmark will be removed from all other folders it may have resided in (optional; if absent, will not be changed)

Response JSON Object:

status (string) – success or error
item (object) – The new bookmark after editing

Example:

PUT /index.php/apps/bookmarks/public/rest/v2/bookmark/7 HTTP/1.1
Host: example.com
Accept: application/json

{ "title": "Boogle" }

Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "success",
  "item": {
    "id": 7,
    "url": "http://google.com",
    "title": "Boogle",
    "description":"in case i forget",
    "tags": ["search-engines", "uselessbookmark"],
    "folders": [-1]
  }
}

Delete a bookmark 

DELETE /public/rest/v2/bookmark/(int: id)

Synopsis:: Delete a bookmark. Note: Often you only want to remove a bookmark from a folder, not delete it from all folders. There is a different endpoint for the former.

New in version 0.11.0.

Response JSON Object:

status (string) – success or error

Example:

DELETE /index.php/apps/bookmarks/public/rest/v2/bookmark/7 HTTP/1.1
Host: example.com
Accept: application/json

Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "success"
}

Get a preview image 

GET /public/rest/v2/bookmark/(int: id)/image

Synopsis:: Retrieve the preview image of a bookmark

New in version 1.0.0.

Example:

GET /index.php/apps/bookmarks/public/rest/v2/bookmark/7/image HTTP/1.1
Host: example.com

Response:

HTTP/1.1 200 OK
Content-Type: image/png

... binary data ...

Get a favicon 

GET /public/rest/v2/bookmark/(int: id)/favicon

Synopsis:: Retrieve the favicon of a bookmark

New in version 1.0.0.

Example:

GET /index.php/apps/bookmarks/public/rest/v2/bookmark/7/favicon HTTP/1.1
Host: example.com

Response:

HTTP/1.1 200 OK
Content-Type: image/png

... binary data ...

Export all bookmarks 

GET /public/rest/v2/bookmark/export

Synopsis:: Export all bookmarks of the current user in a HTML file.

New in version 0.11.0.

Example:

GET /index.php/apps/bookmarks/public/rest/v2/bookmark/export HTTP/1.1
Host: example.com

Response:

HTTP/1.1 200 OK
Content-Type: text/html

<html>
...

Register that a bookmark was opened 

POST /public/rest/v2/bookmark/click

Synopsis:

Delete a bookmark. Note: Often you only want to remove a bookmark from a folder, not delete it from all folders. There is a different endpoint for the former.

Query Parameters:

url (string) – The URL of the bookmark

Example:

POST /index.php/apps/bookmarks/public/rest/v2/bookmark/click?url=https://nextcloud.com/ HTTP/1.1
Host: example.com
Accept: application/json

Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "success"
}