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
Added 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
Added in version 3.4.0.
- Param string|null htmlContent:
The html content of the bookmarked web page
Added in version 4.2.0.
- Param string|null textContent:
The html content of the bookmarked web page
Added in version 4.2.0.
- Param int|null archivedFile:
The nextcloud file id, if this bookmark links to a non-HTML, non-plaintext file
Added in version 3.4.0.
Query bookmarks
- GET /public/rest/v2/bookmark
- Synopsis:
Filter and query all bookmarks by the authenticated user.
Added 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.
Added in version 1.0.0.
unavailable –
Only return bookmarks that are dead links, i.e. return 404 status codes or similar.
Added in version 3.4.0.
archived –
Only return bookmarks that whose contents have been archived.
Added in version 3.4.0.
untagged –
Only return bookmarks that have no tags set
Added in version 0.12.0.
duplicated –
Only return bookmarks that are in multiple folders
Added in version 10.2.0.
- Response JSON Object:
status (string) –
success
orerror
data (array) – The list of resulting bookmarks
Note that before v3.4.0 You couldn’t mix
folder
,url
,unavailable
andarchive
.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
Added 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
orerror
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
Added in version 0.11.0.
- Response JSON Object:
status (string) –
success
orerror
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
Added 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
orerror
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.
Added in version 0.11.0.
- Response JSON Object:
status (string) –
success
orerror
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
Added 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
Added 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.
Added 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" }