Pinboard API Documentation (v1)

Last updated July 17, 2012.



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.

Methods

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.

https://api.pinboard.in/v1/posts/update

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.

example

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

https://api.pinboard.in/v1/posts/add

Add a bookmark. Arguments with shaded background are required.

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

example

If the post was successful:

<result code="done" />

If the post failed:

<result code="something went wrong" />

https://api.pinboard.in/v1/posts/delete

Delete a bookmark. Arguments with shaded background are required.

argumenttypecomment
urlurl

https://api.pinboard.in/v1/posts/get

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.

argumenttypecomment
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

example

$ curl https://user:passwd@api.pinboard.in/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.pinboard.in/v1/posts/get?url=http%3A%2F%2Fwww.pinboard.in%2F

    
        <?xml version="1.0" encoding="UTF-8"?>
        <posts user="user" dt="2007-12-11" tag="">
        <post href="http://www.pinboard.in/"
        hash="2f9704c729e7ed3b41647b7d0ad649fe"
        description="Pinboard"
        extended="antisocial bookmarking"
        tag="bookmarks tools" time="2007-12-11T00:00:07Z" others="433" />
        </posts>
    

https://api.pinboard.in/v1/posts/recent

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

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

example

$ curl https://user:passwd@api.pinboard.in/v1/posts/recent

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

https://api.pinboard.in/v1/posts/dates

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

argumenttypecomment
tagtagfilter by up to three tags

example

$ curl https://user:passwd@api.pinboard.in/v1/posts/dates?tag=argentina

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

https://api.pinboard.in/v1/posts/all

Returns all bookmarks in the user's account.

argumenttypecomment
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

example

$ curl https://user:passwd@api.pinboard.in/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.pinboard.in/v1/posts/suggest

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.

argumenttypecomment
urlurl

example

$ curl https://user:passwd@api.pinboard.in/v1/posts/suggest?url=http://blog.com/

    <suggested>
        <popular>blog</popular>
        <popular>blogs</popular>
        <popular>people</popular>
        <popular>writing</popular>
        <recommended>blog</recommended>
        <recommended>blogs</recommended>
        <recommended>writing</recommended>
        <recommended>weblog</recommended>
        <recommended>People</recommended>
        <recommended>travel</recommended>
        <recommended>art</recommended>
        <recommended>humor</recommended>
        <recommended>programming</recommended>
        <recommended>culture</recommended>
    </suggested>

    

https://api.pinboard.in/v1/tags/get

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

example

    <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.pinboard.in/v1/tags/delete

Delete an existing tag.

argumenttypecomment
tagtag

https://api.pinboard.in/v1/tags/rename

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

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

https://api.pinboard.in/v1/user/secret

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

example

$ curl https://api.pinboard.in/v1/user/secret/?auth_token=user:TOKEN

   <?xml version="1.0" encoding="UTF-8" ?>
        <result>6493a84f72d86e7de130</result>
    

https://api.pinboard.in/v1/user/api_token/

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

example

$ curl https://api.pinboard.in/v1/user/api_token/?auth_token=user:TOKEN

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

https://api.pinboard.in/v1/notes/list

Returns a list of the user's notes

example

$ curl https://api.pinboard.in/v1/notes/list/?auth_token=user:TOKEN

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

    

https://api.pinboard.in/v1/notes/ID

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

example

$ curl https://api.pinboard.in/v1/notes/8e5d6964bb810e0050b0/?auth_token=user:TOKEN

<?xml version="1.0" encoding="UTF-8" ?>
    <note id="8e5d6964bb810e0050b0" >
        <hash>0c9c30f60cadabd31415</hash>
        <length>153</length>
        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.
    ]]></text>
    </note>
    

Encoding

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:

tag
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.
URL
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.
title
up to 255 characters long
text
up to 65536 characters long. Any URLs will be auto-linkified when displayed.
datetime
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).
date
UTC date in this format: 2010-12-11. Same range as datetime above
yes/no
the literal string 'yes' or 'no'
md5
32 character hexadecimal MD5 hash
integer
integer in the range 0..232
format
the literal string 'json' or 'xml'

Authentication

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

  1. Regular HTTP Auth:
    https://user:password@api.pinboard.in/v1/method
    
  2. API authentication tokens:
    https://api.pinboard.in/v1/method?auth_token=user:NNNNNN
    

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.

This token is intended as a stopgap measure to prevent third-party sites from having to store Pinboard credentials while the site moves to full Oauth support.

I implore any third-party sites making API requests on behalf of Pinboard users from an outside server to use this authentication method instead of storing the user's password.

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'

Support

To report bugs in the API or this documentation, please contact support@pinboard.in.If 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.