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
Param string title:
 A short humanly readable label for the bookmark
Param string description:
 A longer description or note on the bookmark
Param array tags:
 A list of tags this bookmark is tagged with
Param array folders:
 The folders this bookmark has been added to

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.
  • unavailable – Only return bookmarks that are dead links, i.e. return 404 status codes or similar.
  • archive – Only return bookmarks that whose contents have been archived.
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:
  • id – the url of the new bookmark
  • tags (array) – Array of tags for this bookmark (these needn’t exist and are created on-the-fly; this used to be item[tags][], which is now deprecated)
  • title (string) – the title of the bookmark. If absent the title of the html site referenced by url is used
  • description (string) – A description for this bookmark
  • folders (array) – An array of IDs of the folders this bookmark should reside in.
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:
  • id – the url of the new bookmark
  • tags (array) – Array of tags for this bookmark (these needn’t exist and are created on-the-fly; this used to be item[tags][], which is now deprecated)
  • title (string) – the title of the bookmark. If absent the title of the html site referenced by url is used
  • description (string) – A description for this bookmark
  • folders (array) – An array of IDs of the folders this bookmark should reside in.
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

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>
...