Skip to main content

Overview

The Diigo API allows you to build apps that interact with the Diigo service. For example, you can use the API to fetch or post bookmarks for a user. The Diigo API is entirely HTTP based and conform to HTTP standards and conventions, making it easy to use with standard technologies.

The API is still under development. The current version is v2. If you have any questions or suggestions, please contact service@diigo.com.

API key

To use the Diigo API, an API key is required. The key must be included in each API request as an HTTP query parameter.

You can sign up for an API Key here.

Authentication

The Diigo API allows you to interact with the service on behalf a Diigo user. The authentication uses HTTP Basic authentication - a standard authentication method that includes base64 encoded username and password in the Authorization request header. Developers must NOT use the credentials provided by users for any other purposes. Other authentication options such as OAuth may be supported in future.

RESTful API style

The Diigo API is RESTful.

Each API method URL corresponds to a resource. The HTTP method (aka. verb) is used to specify the operation.

  • A GET request is used to retreive data.
  • A POST request may add, update or destroy data.
  • The DELETE method is also accepted for methods that destroy data.

API methods usually require a particular HTTP method. Such requirements are documented for each method.

Calling the API

To call an API method, just make an HTTP request to the corresponding URL with proper parameters.

The API URLs are prefixed by version. The current version is v2. All API URLs begin with

https://secure.diigo.com/api/v2/

The Diigo API only accepts and returns text encoded in UTF-8.

Prameters are passed in standard HTTP query string. Parameters are required to be properly URL encoded.

The API key is also passed as a parameter.

An API request looks like

https://secure.diigo.com/api/v2/method_path?key=your_api_key&param1=xxx&param2=xxx...

Responses

The Diigo API attempts to returns meaningful HTTP status codes for each request. Possible codes are

200 OK
Success!
400 Bad Request
Some request parameters are invalid or the API rate limit is exceeded.
401 Not Authorized
Authentication credentials are missing or invalid.
403 Forbidden
The request has been refused because of the lack of proper permission.
404 Not Found
Either you're requesting an invalid URI or the resource in question doesn't exist (e.g. no such user).
500 Internal Server Error
Something is broken.
502 Bad Gateway
Diigo is down or being upgraded.
503 Service Unavailable
The Diigo servers are too busy to server your request. Please try again later.

The response body contains data in the JSON format - a light weight serialization format for structured data.

API Methods

Retrieve bookmarks

https://secure.diigo.com/api/v2/bookmarks

Returns a list of bookmarks satisfying various criteria. Request method: GET

Parameters

user
required, string, the username of whose bookmarks to fetch
start
optional, number, the start offset of the bookmarks to fetch starting from 0, defaults to 0
count
optional, number, the number of bookmarks to fetch, defaults to 10, max:100
sort
optional, number 0-3, determines the order of bookmarks to fetch, 0: created_at, 1: updated_at, 2: popularity, 3: hot, defaults to 0
tags
optional, string, only bookmarks with specified tags will be returned. multiple tags are separated by comma
filter
optional, string, public: only returns public bookmarks; all: returns all bookmarks including private ones, defaults to public
list
optional, string, the list name of a bookmark list, when specified, user must be also specified

Example request

https://secure.diigo.com/api/v2/bookmarks?key=your_api_key&user=joel&count=10

Response

An array of bookmarks.

Example Response (JSON)

[
  {
    "title":"Diigo API Help",
    "url":"http://www.diigo.com/help/api.html",
    "user":"foo",
    "desc":"",
    "tags":"test,diigo,help",
    "shared":"yes",
    "created_at":"2008/04/30 06:28:54 +0800",
    "updated_at":"2008/04/30 06:28:54 +0800",
    "comments":[],
    "annotations":[]
  },
  {
    "title":"Google Search",
    "url":"http://www.google.com",
    "user":"bar",
    "desc":"",
    "tags":"test,search",
    "shared":"yes",
    "created_at":"2008/04/30 06:28:54 +0800",
    "updated_at":"2008/04/30 06:28:54 +0800",
    "comments":[],
    "annotations":[]
  }
]

Save bookmark

https://secure.diigo.com/api/v2/bookmarks

Saves a bookmark for the authenticated user

Request method:POST

Parameters

title
required, string 1-250, the title of the bookmark
url
required, string 1-250, the url of the bookmark
shared
optional, string, the value can be yes/no, yes means the bookmark is public, no means the bookmark is private, defaults to no
tags
optional, string, 1-250, tags separated by comma
desc
optional, string 1-250, the description for the bookmark
readLater
optional, string, value can be yes/no, specifies whether the bookmark is "unread", defaults to no
merge
optional, string, value can be yes/no, specifies merge or replace infomation of the bookmark, defaults to yes

Example request

POST https://secure.diigo.com/api/v2/bookmarks

?key=your_api_key&url=http%3A%2F%2Fwww.diigo.com&title=Diigo+-+Web+Highlighter+and+Sticky+Notes&tags=diigo,bookmark,highlight
&shared=yes

Response

Example Response (JSON)

{ "message" : "added 1 bookmark(s)" }