Pinboard API Documentation (v1)

Last updated October 15, 2014 (removed language about oauth, added ban policy for third-party sites that store passwords).

The Pinboard API is a way to interact programatically with your bookmarks, notes and other Pinboard data.

Wherever possible the Pinboard API uses the same syntax and method names as the Delicious V1 API. See differences from Delicious for a full list of areas where the APIs diverge.


All API methods are GET requests, even when good REST habits suggest they should use a different verb.

Methods return data in XML (default) or JSON format. Click on the example link below any method to see a formatted response.

Returns the most recent time a bookmark was added, updated or deleted.

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


    <?xml version="1.0" encoding="UTF-8" ?>
        <update time="2011-03-24T19:02:07Z" />

Add a bookmark. Arguments with shaded background are required.

urlurlthe URL of the item
descriptiontitleTitle of the item. This field is unfortunately named 'description' for backwards compatibility with the delicious API
extendedtextDescription of the item. Called 'extended' for backwards compatibility with delicious API
tagstagList of up to 100 tags
dtdatetimecreation time for this bookmark. Defaults to current time. Datestamps more than 10 minutes ahead of server time will be reset to current server time
replaceyes/noReplace any existing bookmark with this URL. Default is yes. If set to no, will throw an error if bookmark exists
sharedyes/noMake bookmark public. Default is "yes" unless user has enabled the "save all bookmarks as private" user setting, in which case default is "no"
toreadyes/noMarks the bookmark as unread. Default is "no"


If the post was successful:

<result code="done" />

If the post failed:

<result code="something went wrong" />

Delete a bookmark. Arguments with shaded background are required.


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

tagtagfilter by up to three tags
dtdatereturn results bookmarked on this day
urlurlreturn bookmark for this URL
metayes/noinclude a change detection signature in a meta attribute


$ curl

    <?xml version="1.0" encoding="UTF-8"?>
        <posts dt="2005-11-28" tag="webdev" user="user">
            <post href=""
            description="JavaScript DOM reference"
            extended="dom reference"
        others="55" tag="dom javascript webdev" time="2005-11-28T05:26:09Z" />

$ curl

        <?xml version="1.0" encoding="UTF-8"?>
        <posts user="user" dt="2007-12-11" tag="">
        <post href=""
        extended="antisocial bookmarking"
        tag="bookmarks tools" time="2007-12-11T00:00:07Z" others="433" />

Returns a list of the user's most recent posts, filtered by tag.

tagtagfilter by up to three tags
countintnumber of results to return. Default is 15, max is 100


$ curl

    <?xml version="1.0" encoding="UTF-8" ?>
    <posts dt="2011-03-25T14:49:56Z" user="user">
        <post href="" description="Slate" 
        extended="online news and comment"  hash="3c56b6c6cfedbe75f41e79e6fa102aba" 
        tag="news opinion" time="2011-03-24T20:30:47Z" />

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

tagtagfilter by up to three tags


$ curl

    <?xml version="1.0" encoding="UTF-8" ?>
    <dates user="user" tag="argentina">
        <date count="5" date="2010-11-29" />
        <date count="15" date="2010-11-28" />
        <date count="2" date="2010-11-26" />
        <date count="2" date="2010-11-25" />
        <date count="7" date="2010-11-23" />
        <date count="20" date="2010-11-22" />
        <date count="16" date="2010-11-21" />
        <date count="4" date="2010-11-19" />

Returns all bookmarks in the user's account.

tagtagfilter by up to three tags
startintoffset value (default is 0)
resultsintnumber of results to return. Default is all
fromdtdatetimereturn only bookmarks created after this time
todtdatetimereturn only bookmarks created before this time
metaintinclude a change detection signature for each bookmark


$ curl

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

Returns a list of popular tags and recommended tags for a given URL. Popular tags are tags used site-wide for the url; recommended tags are drawn from the user's own tags.



$ curl


Returns a full list of the user's tags along with the number of times they were used.


        <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" />

Delete an existing tag.


Rename an tag, or fold it in to an existing tag

oldtagnote: match is not case sensitive
newtagif empty, nothing will happen

Returns the user's secret RSS key (for viewing private feeds)


$ curl

   <?xml version="1.0" encoding="UTF-8" ?>

Returns the user's API token (for making API calls without a password)


$ curl

   <?xml version="1.0" encoding="UTF-8" ?>

Returns a list of the user's notes


$ curl

    <?xml version="1.0" encoding="UTF-8" ?>
        <note id="cf73bfc02e00edaa1e2b">
            <title>Paul Graham on Hirin' The Ladies</title>
            <created_at>2011-10-28 13:37:23</created_at>
            <updated_at>2011-10-28 13:37:23</updated_at>
        <note id="8e5d6964bb810e0050b0">
            <title>StarCraft beta coming this week!</title>
            <created_at>2010-02-11 03:46:56</created_at>
            <updated_at>2010-02-11 03:47:47</updated_at>

Returns an individual user note. The hash property is a 20 character long sha1 hash of the note text.


$ curl

<?xml version="1.0" encoding="UTF-8" ?>
    <note id="8e5d6964bb810e0050b0" >
        StarCraft beta coming this week!
        <text><![CDATA[It was clear that readers showing up for our live blog of the Activision Blizzard earnings call were interested in one thing: when the closed beta for StarCraft 2 was set to begin. It took a while to get there, but we were provided a solid answer. The beta will begin before the end of the month, with the game itself set for release in the middle of 2010.


All entities are encoded as UTF-8. In the length limits below, 'characters' means logical characters rather than bytes.

All arguments should be passed URL-encoded. Where multiple arguments are allowed, they should be separated by URL-encoded whitespace (apple+pear+orange)

Data Types

The Pinboard API recognizes the following data types:

up to 255 characters. May not contain commas or whitespace. Please be aware that tags beginning with a period are treated as private and trigger special private tag semantics.
as defined by RFC 3986. Allowed schemes are http, https, javascript, mailto, ftp and file. The Safari-specific feed scheme is allowed but will be treated as a synonym for http.
up to 255 characters long
up to 65536 characters long. Any URLs will be auto-linkified when displayed.
UTC timestamp in this format: 2010-12-11T19:48:02Z. Valid date range is Jan 1, 1 AD to January 1, 2100 (but see note below about future timestamps).
UTC date in this format: 2010-12-11. Same range as datetime above
the literal string 'yes' or 'no'
32 character hexadecimal MD5 hash
integer in the range 0..232
the literal string 'json' or 'xml'


The Pinboard v1 API requires you to use HTTPS. There are two ways to authenticate:

  1. Regular HTTP Auth:
  2. API authentication tokens:

An authentication token is a short opaque identifier in the form "username:TOKEN".

Users can find their API token on their settings page. They can request a new token at any time; this will invalidate their previous API token.

Any third-party sites making API requests on behalf of Pinboard users from an outside server MUST use this authentication method instead of storing the user's password. Violators will be blocked from using the API.

Rate Limits

API requests are limited to one call per user every three seconds, except for the following:

If you need to make unusually heavy use of the API, please consider discussing it with me first, to avoid unhappiness.

Make sure your API clients check for 429 Too Many Requests server errors and back off appropriately. If possible, keep doubling the interval between requests until you stop receiving errors.

Error Handling

The Pinboard API does its best to mimic the behavior Delicious API. If something goes wrong, you'll get the mysterious:

<result code="something went wrong" />

If an action succeeds, you'll get:

<result code="done" />

Or their JSON equivalents.

Differences From Delicious API

  1. Pinboard is way more awesome.
  2. No support for tag bundles.
  3. posts/update does not return an inboxnew attribute.
  4. posts/delete returns
    <result code="item not found" />
    if the user does not have that URL in their bookmarks. Delicious does not return an error in this context.
  5. posts/get - Pinboard response does not include a "tag" attribute.
  6. posts/get - the hashes argument is not supported.
  7. posts/all?hashes is not implemented
  8. posts/suggest - the top level element is called 'suggested' rather than 'suggest'


To report bugs in the API or this documentation, please contact you have an API feature idea, please post it to the Google group (pinboard-dev) for discussion.

You can find me on Twitter as @pinboard and on IRC as #pinboard on freenode.