• Encoding
• Data Types
• Authentication
• Rate Limits
• Error Handling
• Methods
• Differences from Delicious
• Support

Pinboard API Documentation (v1)

Last updated March 25, 2011.

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

In order to make life convenient for developers, 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.

Encoding

All entities are encoded as utf8. 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

description

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. Requests are authenticated with HTTP-Auth:

https://user:password@api.pinboard.in/v1/method

We are working on adding OAuth support.

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.

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

Methods

All API methods are GET requests, even when good REST habits suggest they should use a different verb. Each method name is linked to more detailed documentation below.

Methods return data in XML format by default. Some methods can also return results as JSON; this is indicated in the argument list where approriate. Click on the example link below any method to see a formatted response.

Methods with a green background are unique to Pinboard and don't exist in the Delicious API.

• Update
• posts/update - Check to see when a user last posted an item.
• Bookmarks
• posts/add - add a new bookmark
• posts/delete - delete an existing bookmark
• posts/get - get bookmark for a single date, or fetch specific items by URL
• posts/dates - list dates on which bookmarks were posted
• posts/recent - fetch recent bookmarks
• posts/all - fetch all bookmarks by date, tag, or range
• posts/suggest - fetch popular and recommended tags for a url
• Tags
• tags/get - fetch all tags
• tags/delete - delete a tag from all bookmarks
• tags/rename - rename a tag
• User
• user/secret - get the secret RSS token (allows viewing user's private RSS feeds)

Update

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

Posts

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>

    

Tags

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

Differences From Delicious API

1. No support for tag bundles.
2. posts/update does not return an inboxnew attribute.
3. 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.
4. posts/get - Pinboard response does not include a "tag" attribute.
5. posts/get - the hashes argument is not supported.
6. posts/all?hashes is not implemented
7. 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 our Google group (pinboard-dev) for discussion.

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