• update

  • posts/update

• posts

  • posts/add
  • posts/delete
  • posts/get
  • posts/dates
  • posts/recent
  • posts/all
  • posts/suggest

• tags

  • tags/get
  • tags/delete
  • tags/rename

• user

  • user/secret
  • user/api_token

• notes

  • notes/list
  • notes/ID

Pinboard API Documentation (v1)

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.

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.

example

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

Delete a bookmark. Arguments with shaded background are required.

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.

example

    <?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>
    

    
        <?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.

example

    <?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.

example

    <?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.

example

    <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.

example

    <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.

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

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

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

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

example

   <?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

   <?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

    <?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

<?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..2³²

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:[email protected]/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.

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:

• posts/all - once every five minutes
• posts/recent - once every minute

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 [email protected].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.