This version of the Delicious website will be shutdown by April 2014.
We encourage users to switch to the new Delicious site at http://delicious.com , which features a responsive design for mobile and tablet users, offline access, faster loading, and more.

Developers Resources

RSS & JSON Feeds

  • What are Delicious Feeds?

    For most pages within Delicious, there are associated read-only data feeds for bookmarks and other information displayed in a browser. These feeds come in several formats — including RSS and JSON — and offer windows onto what's going on at Delicious that you can use in news readers, blogs, or your own third-party applications.

    What is RSS?

    RSS is a format used by many news sites and blogs to publish content on the web. Using RSS to publish content enables news readers and personalized start pages to pull new stuff all into one place. Applications that understand RSS can do the footwork and provide a one-stop shop to help readers keep on top of things without needing to surf all over the web in person.

    Accordingly, Delicious offers links to companion RSS feeds on most Profile pages to help you keep track of links from other users. Look for the "rss" link just under a user's profile picture.

    In addition, many web browsers — such as Firefox, Safari, and Internet Explorer — automatically detect RSS feeds associated with pages and offer convenient ways to subscribe.

    What is JSON?

    JSON, which stands for JavaScript Object Notation, is a lightweight data-interchange format easily used in browser-based mashups, blog badges, and other scenarios including server-side and desktop applications.

    You can use feeds at Delicious in JSON format to fetch, remix, and mashup a variety of data for use in your own custom applications and browser-based hacks.

    How fresh are the feeds?

    Since feeds at Delicious see quite a bit of high-volume use, it's not practical to offer immediately fresh results at all times. In particular, RSS feeds may not be updated more than twice an hour, and JSON feeds are likely to show a degree of staleness at times as well. Polling feeds more often will not yield better data, and may result in HTTP 503 Unavailable errors indicating either that your application has been blocked or the servers are otherwise temporarily throttling your requests.

    What API Feeds are available at Delicious?

    Feeds at Delicious all share the following base URL prefix:

    • http://feeds.delicious.com/v2/{format}/

    The placeholder {format} specifies the output format for the feed, which currently includes the values rss and json.

    All feed formats accept the following query-string parameters:

    • ?count={1..100} = Limit the results to the given number, between 1 and 100 (default 15)

    For RSS format feeds, Delicious performs user-agent detection and, for certain news readers, includes enhanced HTML content in items while minimizing the amount of machine-readable metadata. This feature can be intentionally switched on or disabled with the following URL query-string parameters:

    • ?plain = Disable enhanced item HTML content.
    • ?fancy = Enable enhanced item HTML content.

    To help enable JSON-based mashups, there are a few URL query-string parameters to tweak the JSON output:

    • ?callback={js call} = Allows the inclusion of a wrapper function call around the JSON data. The value is filtered by a whitelist consisting of these characters: 0-9 a-z A-Z ()[],._-+=/|\~?!#$^*: '"

    The following feed URL patterns use these placeholders:

    • {format} = replaced with either "rss" or "json"
    • {username} = replaced with a user's login name on delicious
    • {tag[+tag+...+tag]} = replaced with a tag or an intersection of tags.
    • {url md5} = is intended for the MD5 hash of a URL
    • {key} = a security key for the feed, which can be found via the page associated with the feed (eg. inbox, network or bookmarks). Allows visibilty to otherwise private data.

    Finally, what are URL patterns for feeds at Delicious?

    • Recent bookmarks:

      http://feeds.delicious.com/v2/{format}/recent
    • Recent bookmarks by tag:

      http://feeds.delicious.com/v2/{format}/tag/{tag[+tag+...+tag]}
    • Bookmarks for a specific user:

      http://feeds.delicious.com/v2/{format}/{username}
    • Private bookmarks for a specific user:

      http://feeds.delicious.com/v2/{format}/{username}?private={key}
    • Bookmarks for a specific user by tag(s):

      http://feeds.delicious.com/v2/{format}/{username}/{tag[+tag+...+tag]}
    • Private bookmarks for a specific user by tag(s):

      http://feeds.delicious.com/v2/{format}/{username}/{tag[+tag+...+tag]}?private={key}
    • Public summary information about a user:

      http://feeds.delicious.com/v2/{format}/userinfo/{username}
    • A list of all public tags for a user:

      http://feeds.delicious.com/v2/{format}/tags/{username}
    • A list of related public tags for a user tag comination:

      http://feeds.delicious.com/v2/{format}/tags/{username}/{tag[+tag+...+tag]}
    • Bookmarks from a user's subscriptions:

      http://feeds.delicious.com/v2/{format}/subscriptions/{username}
    • Private feed for a user's inbox bookmarks from others:

      http://feeds.delicious.com/v2/{format}/inbox/{username}?private={key}
    • Bookmarks from members of a user's network:

      http://feeds.delicious.com/v2/{format}/network/{username}
    • Bookmarks from members of a user's network by tag:

      http://feeds.delicious.com/v2/{format}/network/{username}/{tag[+tag+...+tag]}
    • A list of a user's network members:

      http://feeds.delicious.com/v2/{format}/networkmembers/{username}
    • Recent bookmarks for a URL:

      http://feeds.delicious.com/v2/{format}/url/{url md5}
    • Summary information about a URL:

      http://feeds.delicious.com/v2/json/urlinfo/{url md5}

APIs

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

Authentication

All /v1 api's require https requests and HTTP-Auth.

Keep in Mind

  • 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.
  • 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.
  • Please watch for 500 or 999 errors and back-off appropriately. It means that you have been throttled.
  • 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.
  • 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 - Check to see when a user last posted an item.

    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 new bookmark

    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 (comma 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 an existing bookmark

    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? - get bookmark for a single date, or fetch specific items

    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:passwd@api.del.icio.us/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:passwd@api.del.icio.us/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? - fetch recent bookmarks

    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:passwd@api.del.icio.us/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?- list dates on which bookmarks were posted

    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? - fetch all bookmarks by date or index range

    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={xx}
    (optional) Start returning posts this many results into the set.
    
     &results={xx}
    (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:passwd@api.del.icio.us/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 - fetch a change detection manifest of all items

    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:passwd@api.del.icio.us/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 - fetch popular, recommended and network tags for a specific url

    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:passwd@api.del.icio.us/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 - fetch all tags

    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 a tag from all posts

    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 a tag on all posts

    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? - fetch tag bundles

    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 bundle

    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 tag bundle

    Delete a bundle.

    arguments

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

    example response

    <result>done</result>