This is historious's cache of http://www.delicious.com/help/api. It is a snapshot of the page as it appeared on 17 December 2010 00:22:42 UTC. The current page could have changed in the meantime. You can also try archive.is for the same URL.
delicious/help/api

API

Read/write access to your Delicious bookmarks and tags via an HTTP-based interface

This document and the APIs herein are subject to change at any time. Sorry, the API is still under development. We will version the API, but may deprecate early versions aggressively.

Authentication

  • All /v1 api's require https requests and HTTP-Auth.
  • To access data from accounts created using a Yahoo! ID, use the same API's as below, but change the path to /v2, and make HTTP requests using OAuth as provided by the Yahoo! Developer Network.
  • For more information on OAuth and its usage with Delicious, see our step by step example.

Keep in Mind

  1. Please let us know if you are going to release software that uses this publicly, so that we can at least have a heads-up and hopefully test things out beforehand.
  2. Please wait AT LEAST ONE SECOND between queries, or you are likely to get automatically throttled. If you are releasing a library to access the API, you MUST do this.
  3. Please watch for 500 or 999 errors and back-off appropriately. It means that you have been throttled.
  4. Please set your User-Agent to something identifiable. The default identifiers like "Java/1.4.3" or "lwp-perl" etc tend to get banned from time to time.
  5. If you are releasing software or a service for other people to use, your software or service MUST NOT add any links without a user's explicit direction. Likewise, you MUST NOT modify any urls except under the user's explicit direction.

Methods

Update

https://api.del.icio.us/v1/posts/update

Returns the last update time for the user, as well as the number of new items in the user's inbox since it was last visited.

Use this before calling posts/all to see if the data has changed since the last fetch.

Example Response

<update time="2005-03-28T17:25:52Z" inboxnew="0" />

Posts

https://api.del.icio.us/v1/posts/add?

Add a post to Delicious

Arguments

&url={URL}
(required) the url of the item.
&description={...}
(required) the description of the item.
&extended={...}
(optional) notes for the item.
&tags={...}
(optional) tags for the item (space delimited).
&dt={CCYY-MM-DDThh:mm:ssZ}
(optional) datestamp of the item (format "CCYY-MM-DDThh:mm:ssZ"). Requires a LITERAL "T" and "Z" like in ISO8601 at http://www.cl.cam.ac.uk/~mgk25/iso-time.html for example: "1984-09-01T14:21:31Z"
&replace=no
(optional) don't replace post if given url has already been posted.
&shared=no
(optional) make the item private

Example Response

If the post was successful:

<result code="done" />

If the post failed:

<result code="something went wrong" />

https://api.del.icio.us/v1/posts/delete?

Delete a post from Delicious

Arguments

&url={URL}
(required) the url of the item.

Example Response

<result code="done" />

https://api.del.icio.us/v1/posts/get?

Returns one or more posts on a single day matching the arguments. If no date or url is given, most recent date will be used.

Arguments

&tag={TAG}+{TAG}+...+{TAG}
(optional) Filter by this tag.
&dt={CCYY-MM-DDThh:mm:ssZ}
(optional) Filter by this date, defaults to the most recent date on which bookmarks were saved.
&url={URL}
(optional) Fetch a bookmark for this URL, regardless of date. Note: Be sure to URL-encode the argument value.
&hashes={MD5}+{MD5}+...+{MD5}
(optional) Fetch multiple bookmarks by one or more URL MD5s regardless of date, separated by URL-encoded spaces (ie. '+').
&meta=yes
(optional) Include change detection signatures on each item in a 'meta' attribute. Clients wishing to maintain a synchronized local store of bookmarks should retain the value of this attribute - its value will change when any significant field of the bookmark changes.

Example

$ curl https://user:[email protected]/v1/posts/get?tag=webdev&meta=yes

<?xml version="1.0" encoding="UTF-8"?>
<posts dt="2005-11-28" tag="webdev" user="user">
  <post href="http://www.howtocreate.co.uk/tutorials/texterise.php?dom=1"
      description="JavaScript DOM reference"
      extended="dom reference"
      hash="c0238dc0c44f07daedd9a1fd9bbdeebd"
      meta="92959a96fd69146c5fe7cbde6e5720f2"
      others="55" tag="dom javascript webdev" time="2005-11-28T05:26:09Z" />
</posts>

$ curl https://user:[email protected]/v1/posts/get?url=http%3A%2F%2Fwww.yahoo.com%2F

<?xml version="1.0" encoding="UTF-8"?>
<posts user="user" dt="2007-12-11" tag="">
  <post href="http://www.yahoo.com/" 
      hash="2f9704c729e7ed3b41647b7d0ad649fe" 
      description="Yahoo!" 
      extended="My favorite site ever"
      tag="yahoo web search" time="2007-12-11T00:00:07Z" others="433" />
</posts>

https://api.del.icio.us/v1/posts/recent?

Returns a list of the most recent posts, filtered by argument. Maximum 100.

Arguments

&tag={TAG}
(optional) Filter by this tag.
&count={1..100}
(optional) Number of items to retrieve (Default:15, Maximum:100).

Example Response

$ curl https://user:[email protected]/v1/posts/recent

<posts tag="" user="user">
  <post href="http://www.weather.com/" description="weather.com"
  hash="6cfedbe75f413c56b6ce79e6fa102aba" tag="weather reference"
  time="2005-11-29T20:30:47Z" />
    ...
  <post href="http://www.nytimes.com/"
  description="The New York Times - Breaking News, World News & Multimedia"
  extended="requires login" hash="ca1e6357399774951eed4628d69eb84b"
  tag="news media" time="2005-11-29T20:30:05Z" />
</posts>

https://api.del.icio.us/v1/posts/dates?

Returns a list of dates with the number of posts at each date.

Arguments

&tag={TAG}
(optional) Filter by this tag

Example

<dates tag="" user="user">
  <date count="5" date="2005-11-29" />
  <date count="15" date="2005-11-28" />
  <date count="2" date="2005-11-26" />
  <date count="2" date="2005-11-25" />
  <date count="7" date="2005-11-23" />
  <date count="20" date="2005-11-22" />
  <date count="16" date="2005-11-21" />
  <date count="4" date="2005-11-19" />
</dates>

https://api.del.icio.us/v1/posts/all?

Returns all posts. Please use sparingly. Call the update function to see if you need to fetch this at all.

Arguments

&tag={TAG}
(optional) Filter by this tag.
&start={#}
(optional) Start returning posts this many results into the set.
&results={#}
(optional) Return this many results.
&fromdt={CCYY-MM-DDThh:mm:ssZ}
(optional) Filter for posts on this date or later
&todt={CCYY-MM-DDThh:mm:ssZ}
(optional) Filter for posts on this date or earlier
&meta=yes
(optional) Include change detection signatures on each item in a 'meta' attribute. Clients wishing to maintain a synchronized local store of bookmarks should retain the value of this attribute - its value will change when any significant field of the bookmark changes.

Example

$ curl https://user:[email protected]/v1/posts/all

<posts tag="" user="user">
  <post href="http://www.weather.com/" description="weather.com"
  hash="6cfedbe75f413c56b6ce79e6fa102aba" tag="weather reference"
  time="2005-11-29T20:30:47Z" />
    ...
  <post href="http://www.nytimes.com/"
  description="The New York Times - Breaking News, World News & Multimedia"
  extended="requires login" hash="ca1e6357399774951eed4628d69eb84b"
  tag="news media" time="2005-11-29T20:30:05Z" />
</posts>

https://api.del.icio.us/v1/posts/all?hashes

Returns a change manifest of all posts. Call the update function to see if you need to fetch this at all.

This method is intended to provide information on changed bookmarks without the necessity of a complete download of all post data.

Each post element returned offers a url attribute containing an URL MD5, with an associated meta attribute containing the current change detection signature for that bookmark.

Example

$ curl https://user:[email protected]/v1/posts/all?hashes

<?xml version="1.0" encoding="UTF-8"?>
<posts>
    <post meta="d4b6adc08932f237ec1bfe8021629f4b" url="b14d529834a601567b14f76192e39e96"/>
    <post meta="77e1ec24a43bae61fb67586649683d30" url="2f9704c729e7ed3b41647b7d0ad649fe"/>
    <post meta="9bbc254e930cd5f719c35d97a5180852" url="96bdf631592930d5f540bb962dced0f2"/>
    <post meta="72d92edd9588c3aab5ea8a56d2d79328" url="c5f7ac7a3ec5f014723738c15891a896"/>
    ...
    <post meta="84aea258c8835a2adf226d0d4d439fb7" url="7e2c9d4c49569409d9b455cdf8189a77"/>
</posts>

https://api.del.icio.us/v1/posts/suggest

Returns a list of popular tags, recommended tags and network tags for a user.

This method is intended to provide suggestions for tagging a particular url.

Arguments

&url={URL}
(required) URL for which you'd like suggestions

Example

$ curl https://user:[email protected]/v1/posts/suggest?url=http://yahoo.com/

<?xml version="1.0" encoding="UTF-8"?>
<suggest>
  <popular>yahoo!</popular>
  <popular>yahoo</popular>
  <popular>web</popular>
  <popular>tools</popular>
  <popular>searchengines</popular>
  <recommended>yahoo!</recommended>
  <recommended>yahoo</recommended>
  <recommended>web</recommended>
  <recommended>tools</recommended>
  <recommended>search</recommended>
  <recommended>reference</recommended>
  <recommended>portal</recommended>
  <recommended>news</recommended>
  <recommended>music</recommended>
  <recommended>internet</recommended>
  <recommended>home</recommended>
  <recommended>games</recommended>
  <recommended>entertainment</recommended>
  <recommended>email</recommended>
  <network>for:Bernard</network>
  <network>for:britta</network>
  <network>for:deusx</network>
  <network>for:joshua</network>
  <network>for:stlhood</network>
  <network>for:theteam</network>
</suggest>

Tags

https://api.del.icio.us/v1/tags/get

Returns a list of tags and number of times used by a user.

Example Response

<tags>
  <tag count="1" tag="activedesktop" />
  <tag count="1" tag="business" />
  <tag count="3" tag="radio" />
  <tag count="5" tag="xml" />
  <tag count="1" tag="xp" />
  <tag count="1" tag="xpi" />
</tags>

https://api.del.icio.us/v1/tags/delete?

Delete an existing tag.

Arguments

&tag={TAG}
(required) Tag to delete

Example Response

<result>done</result>

https://api.del.icio.us/v1/tags/rename?

Rename an existing tag with a new tag name.

Arguments

&old={TAG}
(required) Tag to rename.
&new={TAG}
(required) New tag name.

Example Response

<result>done</result>

Tag Bundles

https://api.del.icio.us/v1/tags/bundles/all?

Retrieve all of a user's bundles.

Arguments

&bundle={NAME}
(optional) Fetch just the named bundle.

Example Response

<bundles>
  <bundle name="music" tags="ipod mp3 music" />
</bundles>

https://api.del.icio.us/v1/tags/bundles/set?

Assign a set of tags to a single bundle, wipes away previous settings for bundle.

Arguments

&bundle={NAME}
(required) Name of the bundle
&tags={TAG}+{TAG}+...+{TAG}
(required) List of tags, space-separated.

Example Response

If the bundle was created:

<result>ok</result>

If the bundle was not created:

<result>you must supply a bundle name and at least one tag</result>

https://api.del.icio.us/v1/tags/bundles/delete?

Delete a bundle.

Arguments

&bundle={NAME}
(required) Name of the bundle

Example Response

<result>done</result>