Pinboard API DRAFT Documentation (v2)

Overview ‧ Reference ‧ Examples

GET /hello/

No-op. Useful for checking that credentials are OK and the API is reachable.

This API call is not rate-limited.

example

> curl 'https://api.pinboard.in/v2/hello?auth_token=user:123'
  
  { status: 'ok' }

POST /auth/

Given a username and password, returns the auth token for the user. This is the only API call that accepts password authentication.

API clients MUST NOT store user passwords. Instead, use this call to get the user's auth token and store that.

This API call is not rate-limited.

example

> curl 'https://api.pinboard.in/v2/hello?auth_token=user:123'
  
  { status: 'ok' }

GET /last_update/

Returns the timestamp of the last stateful change to a user's bookmarks. Does not apply to tab sets, subscriptions, or other account settings.

example

> curl 'https://api.pinboard.in/v2/last_update?auth_token=user:123'
  
  { status: 'ok' }

GET /delta/

Retrieve a list of changes since a given timestamp.

This call is intended as a lightweight way to poll the site to update third-party clients.

The call will return three (possibly empty) lists of bookmark IDs. If there have been too many changes, it may not be possible to get a changeset. The request will then return a too many changes error and the client should re-sync the account.

argumenttypecomment
sincedatetimeUTC datetime
Error Codes
too many changes Too many items to return, do a full update
invalid timestamp Timestamp in future or unreadable

example

curl  'https://api.pinboard.in/v2/bookmarks/delta/?since=1366858381&auth_token=user:123'

HTTP/1.1 200 OK

{ 
    status: 'ok',
    delta: {
        "since"    : ['2020-01-02 09:00Z'],
        "added"    : ['c3b24343f1', '1b50e2c976', 'f8a0a8743e'],
        "deleted"  : ['7894bb7e44'],
        "modified" : ['71b6439f4d', 'bf74aadc31']
    }
}

Bookmarks

POST or PUT /bookmarks/

Creates a new bookmark.

argumenttypecomment
urlurlURL of the new bookmark
titletitletitle
descriptionstringdescription
tagstagcomma-delimited list of tags
privatebooleanprivacy flag. Automatically set to TRUE if user has PRIVACY_LOCK
toreadbooleansets toread status
exact_urlbooleandon't normalize URL
Error Codes
bookmark_exists A bookmark already exists with this URL. Headers will redirect appropriately
url_not_valid URL did not validate
url_missing You did not provide a URL

example

curl -d "url=http://example.com" "https://api.pinboard.in/v2/bookmarks/"

HTTP/1.1 201 Created
Location: https://api.pinboard.in/v2/bookmarks/b:3a24b2222a21152c/
ETag: "c180de84f991g8"  


{ 
    status: "ok",
    site_url: "https://pinboard.in/u:user/b:3a24b2222a21152c/" 
}

GET /bookmarks/

Retrieves bookmarks in reverse chronological order. This is an expensive query, so please use it only when /delta/ isn't an option.

Query string arguments:

argumenttypecomment
fromdatetimestart date
todatetimeend date
tagstagFilter results by up to three tags (tag intersection)
filterstringAllowed values are: public, private, toread, untagged, starred.
countintegerNumber of bookmarks to return. Default is 25, max is 1000
offsetintegerStarting offset. Default is 0

example

curl https://api.pinboard.in/v2/bookmarks/unread/?auth_token=user:123&count=20

HTTP/1.1 200 OK
ETag: 036fb010feb019fe
Last-Modified: Wed, 15 Apr 2011 12:41:21 GMT

 {  status: "true",
    bookmarks : [ 
        { id : "bd341828e847",
          url : "http://example.org/123/",
          title : "The beast is back",
          desc: "Fear of bees"
          tags : ["beer", "wine", "art" ],
          created : "2012-03-02T12:34:11Z",
          updated : "2013-01-14T19:21:20Z",
          private : "1"
        }]
    }

GET /bookmarks/id/

Retrieve a specific bookmark.

example

curl 'https://api.pinboard.in/v2/bookmarks/b:a21b6ebd8d12/?auth_token=user:123'

HTTP/1.1 200 OK
ETag: 036fb010feb019fe
Last-Modified: Wed, 15 Apr 2011 12:41:21 GMT

{ 
    status: "ok",
    bookmarks : [ 
        { id : 'bd341828e847',
          url : "http://example.org/cakes/",
          title : "Cake Recipe",
          desc: "My grandma's favorite"
          tags : ["cake", "food" ],
          created : '2012-03-02T12:34:11Z',
          updated : '2012-03-02T12:34:11Z',
          private : 1
        }]
    }
}

POST /bookmarks/id/

Update an existing bookmark.

argumenttypecomment
idhexbookmark ID
urlurlURL of the bookmark
createddatetimecreation date
titletitletitle (up to 255 chars)
tagstagcomma-delimited list of tags. Empty value will clear tags; leave undefined if you want to keep existing tags
descriptionstringBookmark description
privatebooleansets or unsets the privacy attribute. Ignored if PRIVACY LOCK is on
unreadbooleansets or unsets the read later attribute
Error Codes
bad_url URL was not valid
404 Not Found Not found
bad_id bad identifier
missing_id no identifier

example

curl --data-urlencode 'title=A New Title' --data-urlencode='url=http://example.org/'

HTTP/1.1 200 OK


{ 
    status: "ok"
}

DELETE /bookmarks/id/

Permanently delete a bookmark.

example

curl -X DELETE 'https://api.pinboard.in/v2/bookmarks/b:a21b6ebd8d12/'

HTTP/1.1 202 Accepted


{ 
    status: "ok"
}

GET /bookmarks/id/archived

Returns the URL and crawl metadata to a cached copy of the bookmark content. Available only to archival users.

example

curl -X DELETE 'https://api.pinboard.in/v2/bookmarks/b:a21b6ebd8d12/archived'

HTTP/1.1 202 Accepted


{ 
    url: "https://cache9.pinboard.in....."
}

POST /bookmarks/id/archived

Requests that an archived bookmark get crawled again. This will overwrite the original copy.

DELETE /bookmarks/

Delete multiple bookmarks. To avoid painful mistakes, it's not possible to delete all bookmarks via the API.

argumenttypecomment
idshexlist of up to 100 bookmark IDs

example

curl -X DELETE --data 'ids=518f9a067606+95b74fa4b450+c3098165a314' \
	 'https://api.pinboard.in/v2/bookmarks/many/'

HTTP/1.1 202 Accepted

{ 
    status: "ok"
}

Tags

Tags are free-form identifiers attached to a bookmark. A tag may not contain whitespace. Tags are not case-sensitive, but Pinboard tries to remember and display them with the original capitalization.

GET /tags/

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

example

curl  "https://api.pinboard.in/v2/tags/?auth_token=user:123"

HTTP/1.1 200 OK

{ 
    status: 'ok',
    tags : { 'activedesktop' : 1,
               'business' : 12,
               'radio' : 3,
               'xml' : 4,
               'xp' : 4,
               'xpi' : 13 }
}

POST /tags/rename/

Renames a tag. Note that this won't work if you're trying to change the case on a tag.

argumenttypecomment
oldtagcomma-delimited list of up to 3 tags. Note: match is not case sensitive
newtagtag to rename to. If empty, nothing will happen

example

curl --data-urlencode "old=polsci pol" \
     --data-urlencode "new=politics" \
      "https://api.pinboard.in/v2/tags/rename/?auth_token=user:123"

HTTP/1.1 202 Accepted

{ 
    status: 'ok'
}

DELETE /tags/tag

Deletes all instances of this tag.

example

curl -X DELETE "https://api.pinboard.in/v2/tags/t:food/?auth_token=user:123"

HTTP/1.1 202 Accepted

{ 
    status: 'ok'
}

DELETE /tags/

Deletes multiple tags.

argumenttypecomment
tagstagcomma-delimited list of up to 10 tags to delete

example

curl -X DELETE --data-urlencode "tags=finance economics money" \
      "https://api.pinboard.in/v2/tags/multiple/?auth_token=user:123"

HTTP/1.1 202 Accepted

{ 
    status: 'ok'
}


Network

A user's network is a list of other users they follow.

GET /network/people/

Retrieves a list of people in the user’s network

example

curl  "https://api.pinboard.in/v2/network/people/?auth_token=user:123"

HTTP/1.1 200 OK

{ 
    status: "ok",
    people: ["alice", "bob", "fred", "pat"]
}

PUT or POST /network/people/username/

Adds a user to the network.

example

curl  -X PUT  "https://api.pinboard.in/v2/network/people/u:jdoe/?auth_token=user:123"

HTTP/1.1 200 OK

{ 
    status: "ok"
}

DELETE /network/people/username/

Removes a user from the network

example

curl -X DELETE "https://api.pinboard.in/v2/network/people/u:jdoe/?auth_token=user:123"

HTTP/1.1 202 Accepted

{ 
    status: "ok"
}

GET /network/bookmarks/

Fetches bookmarks in the user's network

argumenttypecomment
countintegernumber of results to return. Default is 25, max is 100
beforedatetimereturn results before this date
filterbooleanfilter out mechanically-added bookmarks

example

curl  "https://api.pinboard.in/v2/network/bookmarks/?auth_token=user:123"

HTTP/1.1 200 OK

{ 
    status: 'ok',
    bookmarks : [ 
        { 
            id : 'f82e20805e8ed721',
            url : 'http://example.com/pizza/32',
            author : 'fred',
            title : "Salmon pizza recipe",
            tags : ['food', 'cooking'],
            created : '2013-05-02T12:34:11Z'
        },
        { 
            id : 'dfdf43ddf065c39f',
            url : 'http://example.org/wines/',
            author : "jane",
            title : "Best pinot noir",
            tags : ["wine"],
            created : '2013-05-02T12:34:11Z'
        }
    ]
}


Notes

A note is a small document with a body, title, and URL. Users can decide if notes should be displayed using markdown. A note can be public or private.

GET /notes/

Returns a list of the user's notes in reverse chronological order.

example

curl  "https://api.pinboard.in/v2/notes/?auth_token=user:123"

HTTP/1.1 200 OK

{ 
     status : 'ok',
      notes : [
        {
          'id' : '2e75e5494ee79e68',
          'title' : "Grandma's Potato Recipe",
          'created' : '2012-11-30T13:24:22Z',
          'updated' : '2012-11-30T13:24:22Z',
          'length' : "492", 
          "api_url" : "https://api.pinboard.in/v2/notes/note:2e75e5494ee79e68".
          "site_url" : "https://notes.pinboard.in/u:user/note:2e75e5494ee79e68"

          },
          { 'id' : '1182c38f3b387ada',
          'title' : "Grandpa's Potato Recipe",
          'created' : '2013-10-10T09:17:58Z'
          'updated' : '2013-10-13T21:55:02Z',
          'length' : "212"
          "api_url" : "https://api.pinboard.in/v2/notes/note:2e75e5494ee79e68"
          "site_url" : "https://notes.pinboard.in/u:user/2e75e5494ee79e68/"
          }
        ]
    }}

GET /notes/id/

Retrieves a specific note.

example

curl  "https://api.pinboard.in/v2/notes/note:2e75e5494ee79e68/?auth_token=user:123"

HTTP/1.1 200 OK
Etag: 2e75e5494ee79e68
Last-Modified: xxx

{ 
     status : 'ok',
     'id' : '85e177fc00',
     'title' : "Grandma's Potato Recipe",
     'created' : '2012-11-30T13:24:22Z',
     'updated' : '2012-11-30T13:24:22Z',
     "note" : "Cut a potato in half, salt it, eat it"
}

POST /notes/id/

Updates a note. Empty arguments will overwrite data with blanks; leave them unspecified if you want to keep what is there.

argumenttypecomment
notestringnote content
titlestringnote title
use_markdownbooleanformat this note using Markdown

example

curl --data-urlencode "title=Best Potato Recipe" \
     --data-urlencode "note=Cut a potato in quarters" \
      "https://api.pinboard.in/v2/notes/note:2e75e5494ee79e68/?auth_token=user:123"

HTTP/1.1 200 OK

{ 
     status : 'ok'
}

POST or PUT /notes/

Creates a new note and returns the identifier.

argumenttypecomment
notestringnote content
titlestringnote title
use_markdownbooleanformat this note using Markdown (default false)

example

curl --data-urlencode "title=New Potato Recipe" \
     --data-urlencode "note=Cut a potato in thirds" \
      "https://api.pinboard.in/v2/notes/?auth_token=user:123"

HTTP/1.1 201 Created
Location: https://api.pinboard.in/v2/notes/note:8b07fddb3ad5cf517b82/


{ 
     status : 'ok',
     id : '8b07fddb3ad5cf517b82',
     api_url  : "https://api.pinboard.in/v2/notes/note:8b07fddb3ad5cf517b82/",
     site_url : "https://notes.pinboard.in/u:user/8b07fddb3ad5cf517b82/"
}

DELETE /notes/id/

Deletes a note.

example

curl -X DELETE "https://api.pinboard.in/v2/notes/note:2a8a2ec9f3a076a1/?auth_token=user:123"

HTTP/1.1 202 Accepted

{ 
     status : 'ok'
}

Bundles

Bundles in Pinboard parlance are tag unions. They consist of a name, ID, and a list of tags.

GET /bundles/

Returns a list of the user's tag bundles along with the number of tags in each.

example

curl  "https://api.pinboard.in/v2/bundles/?auth_token=user:123"

HTTP/1.1 200 OK

{ 
     status : 'ok',
      bundles : { 'activedesktop' : 1,
                 'business' : 12,
                 'radio' : 3,
                 "xml" : 4,
                 "xp" : 4,
                 "xpi" : 13 }
}

PUT or POST /bundles/

Create a new tag bundle. Redirects to an existing bundle if the name is already in use.

argumenttypecomment
namestringbundle name
tagstaglist of tags

example

> curl 'https://api.pinboard.in/v2/bundles/?auth_token=user:123' \
    --data "name=music&tags=rock+pop+classical+funk"

HTTP/1.1 201 Created
Location: https://pinboard.in/u:user/bundle:music/
   
{ status : 'ok' }

GET /bundles/name/

Retrieve a list of tags in the bundle.

example

> curl 'https://api.pinboard.in/v2/bundles/bundle:music/tags/?auth_token=user:123'

   {
        status : 'ok',
        tags : [ 'rock', 'pop', 'disco', 'flamenco']
    }

PUT or POST /bundles/name/

Adds one or more tags to the bundle

argumenttypecomment
tagstaglist of tags

example

> curl --data 'tags=soul+rhythm%26blues  \
    'https://api.pinboard.in/v2/bundles/bundle:music/?auth_token=user:123'

   {
        status : 'ok',
        tags : [ 'rock', 'pop', 'disco', 'flamenco']
    }

DELETE /bundles/name/

Delete the tag bundle.

example

> curl -X DELETE 'https://api.pinboard.in/v2/bundles/bundle:music/?auth_token=user:123'

   {
        status : 'ok',
        tags : [ 'rock', 'pop', 'disco', 'flamenco']
    }

DELETE /bundles/name//{tag}/

Remove this tag from the bundle.

example

> curl -X DELETE 'https://api.pinboard.in/v2/bundles/bundle:music/t:rock?auth_token=user:123'
  
   { status : 'ok' }

User

The user object contains information about the user's account status, total bookmark counts, and capabilities (like archiving).

GET /user/

Retrieves information about a user, including account creation date, type (regular or archival), account status.

example

> curl 'https://api.pinboard.in/v2/user/?auth_token=user:123'
   {
        status : 'ok',
        user : {
        	account_type: "subscription",
        	last_active : "2021-01-03 08:45Z",
			valid_until : "2022-12-01 12:32Z",
            "has_archiving" : "true",
            "joined" : "2012-01-13",
            "bookmark_counts" : {
                "public" : 2020,
                "private" : 323,
                "unread" : 23
                }        
        }}
    }

GET /user/settings/

Fetches a list of the user's current settings.

example

> curl 'https://api.pinboard.in/v2/user/settings/?auth_token=user:123'

   { status : 'ok',
     settings :
     {  absolute_dates : '1',                 
        alphabetize_tags : '1',                       
        bookmark_by_email : '1',              
        click_means_read : '1',               
        default_private : '1',                          
        disable_history : '1',                          
        fandom_flag : '1',                                
        keyboard_shortcuts : '1',             
        new_window : '1',                                      
        privacy_lock : '1',                   
        public_network : '1',                 
        public_profile : '1',                 
        public_subscriptions : '1',           
        public_tag_subs : '1',                     
        show_urls : '1',                      
        tag_bundles : '1',                    
        tag_mode : '1',                       
        tag_subscriptions : '1',              
        user_time_zone : 'America/Los Angeles',   
    }
  }

GET /user/tokens/

Fetch a list of the user's secret tokens.

example

   {
        status : 'ok',
        tokens : { 'rss_secret' : '2c2621c956',
                 'email_secret' : '67765'  }
    }

Tab Sets

GET /tabs/

Retrieve a list of saved tab sets.

example

> curl 'https://api.pinboard.in/v2/user/tabs/?auth_token=user:123'
   {
        status : 'ok',
        tab_sets : [ { 'id' : '2849d534e5', 
                      'title' :  'Active Desktop',
                      'created' : '2011-03-21:T00:32:21Z',
                      'windows' : 4,
                      'tabs'    : 21 },
                      ...
                    ]}
    }

GET /tabs/id:{id}/

Get a list of windows and tabs in the saved tab set.

example

> curl 'https://api.pinboard.in/v2/user/tabs/id:2849d534e5?auth_token=user:123'
   {
        status : 'ok',
       { 'id' : '2849d534e5', 
          'title' :  'Active Desktop',
          'created' : '2011-03-21:T00:32:21Z',
          'windows' : [
            [ { 'title' : "First tab", "url" : "http://example.org/v1/" },
              { 'title' : "Second tab", "url" : "http://nowhere.net/" }
            ],
            [
              { 'title' : "Another window", "url" : 'http://somewhere.else" }
            ]]
       }
    }

Search

GET /search/user/

Searches within the user's bookmarks.

argumenttypecomment
querystringquery string for the search engine
countintegernumber of results to return. Default is 25, max is 100
fulltextbooleaninclude fulltext results (archival users only)
offsetintegeroffset. Default is 0, maximum 1000

example

> curl 'https://api.pinboard.in/v2/user/tabs/id:2849d534e5?auth_token=user:123'
   {
        status : 'ok',
       { 'id' : '2849d534e5', 
          'title' :  'Active Desktop',
          'created' : '2011-03-21:T00:32:21Z',
          'windows' : [
            [ { 'title' : "First tab", "url" : "http://example.org/v1/" },
              { 'title' : "Second tab", "url" : "http://nowhere.net/" }
            ],
            [
              { 'title' : "Another window", "url" : 'http://somewhere.else" }
            ]]
       }
    }

GET /search/network/

Searches within the user's network.

argumenttypecomment
querystringquery string for the search engine
countintegernumber of results to return. Default is 25, max is 100
offsetintegeroffset. Default is 0, maximum 1000

example

> curl 'https://api.pinboard.in/v2/user/tabs/id:2849d534e5?auth_token=user:123'
   {
        status : 'ok',
       { 'id' : '2849d534e5', 
          'title' :  'Active Desktop',
          'created' : '2011-03-21:T00:32:21Z',
          'windows' : [
            [ { 'title' : "First tab", "url" : "http://example.org/v1/" },
              { 'title' : "Second tab", "url" : "http://nowhere.net/" }
            ],
            [
              { 'title' : "Another window", "url" : 'http://somewhere.else" }
            ]]
       }
    }

GET /search/site/

Searches sitewide, with optional tag filters.

argumenttypecomment
querystringquery string for the search engine
countintegernumber of results to return. Default is 25, max is 100
offsetintegeroffset. Default is 0, maximum 1000
tagtagcomma delimited list of up to 3 tags

example

> curl 'https://api.pinboard.in/v2/user/tabs/id:2849d534e5?auth_token=user:123'
   {
        status : 'ok',
       { 'id' : '2849d534e5', 
          'title' :  'Active Desktop',
          'created' : '2011-03-21:T00:32:21Z',
          'windows' : [
            [ { 'title' : "First tab", "url" : "http://example.org/v1/" },
              { 'title' : "Second tab", "url" : "http://nowhere.net/" }
            ],
            [
              { 'title' : "Another window", "url" : 'http://somewhere.else" }
            ]]
       }
    }

Site

GET /site/popular/

Searches sitewide, with optional tag filters.

argumenttypecomment
filterstringoptional string may be one of 'fandom', 'wikipedia', 'twitter'
countintegernumber of results to return. Default is 25, max is 100
datedatetimeoptional day to return results from. Defaults to current day
tagtagcomma delimited list of up to 3 tags. Cannot be used with date argument

example

> curl 'https://api.pinboard.in/v2/user/tabs/id:2849d534e5?auth_token=user:123'
   {
        status : 'ok',
       { 'id' : '2849d534e5', 
          'title' :  'Active Desktop',
          'created' : '2011-03-21:T00:32:21Z',
          'windows' : [
            [ { 'title' : "First tab", "url" : "http://example.org/v1/" },
              { 'title' : "Second tab", "url" : "http://nowhere.net/" }
            ],
            [
              { 'title' : "Another window", "url" : 'http://somewhere.else" }
            ]]
       }
    }

POST /awesome/

Use this call to express approbation of Pinboard. Will return a struct with 'thank you'.

This API call is not rate-limited.

example

> curl -X POST 'https://api.pinboard.in/v2/awesome/?auth_token=user:123'

{ status : "thank you!" }