Skip to content
Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

Thumbtack - The best Pinboard API client for Ruby

GitHub Actions badge Codecov Inline Docs


Thumbtack is a simple Ruby client for the Pinboard API.

There are other Pinboard API clients for Ruby, but there are a few things that set Thumbtack apart:

  • Zero dependencies
    Thumbtack requires only a few things from Ruby's standard library.
  • Clean and consistent API
    Required arguments in Pinboard's API are required arguments in Thumbtack's method calls. With only one exception, Thumbtack's API mirrors Pinboard's 1-to-1.
  • Client-side validation
    Pinboard has clearly defined rules about data types and Thumbtack enforces them.
  • Ruby-isms
    Use regular Ruby types and let Thumbtack convert it to parameters acceptable to Pinboard (i.e. use true/false instead of 'yes'/'no').
  • Documentation
    Thorough documentation of the usage and API is a top priority for Thumbtack. No question should be unanswered.


Initialize a client with your Pinboard username and API token

client =, token)

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

update_time = client.posts.update

Add bookmarks

client.posts.add('', 'The Internate')
client.posts.add('', 'The Internate', extended: 'The personal website of Nate Smith', tags: ['awesome', 'essential'])

Delete them too


Retrieve bookmarks by tag or other filters

tagged_webdev = client.posts.get(tag: 'webdev')
tagged_webdev_and_ruby = client.posts.get(tag: ['webdev', 'ruby'])
pinboard_bookmark = client.posts.get(url: '')

Fetch recently added bookmarks

recent_bookmarks = client.posts.recent

Get bookmark creation dates with a count of bookmarks created

dates_with_counts = client.posts.dates(tag: 'argentina')

Get every bookmark from the account

all_bookmarks = client.posts.all

Fetch popular and recommended tags for a URL

tag_suggestions = client.posts.suggest('')

Find every tag with their usage count

tags_with_counts = client.tags.get

Remove tags


Rename them

client.tags.rename('delicious', 'pinboard')

Get your secret RSS key


Retrieve your API key


Fetch summaries of all notes (no text)


Then fetch the full note


The one inconsistency between Thumbtack and Pinboard

Thumbtack tries hard to mimic the Pinboard API, BUT: Pinboard's notes have an attribute named hash. Unfortunately, this collides with a special method in Ruby. To work around this, Thumbtack renames the hash attribute to digest in the Note and NoteSummary objects returned from Notes#list and Notes#get.


  • Ruby 2.3.6+, but you're already on 2.5+, right?
  • Nothing else. No gem dependencies, nothing.


The best way to install Thumbtack is with RubyGems:

$ [sudo] gem install thumbtack

API Documentation


If you'd like to make some changes to Thumbtack, start by forking the repo on GitHub:

The best way to get contributions merged into Thumbtack:

  1. Clone down your fork.
  2. Create a well-named topic branch for your change
  3. Make your change.
  4. Add tests and make sure everything passes (see the section on running the tests below).
  5. If you are adding new functionality, document it in the README.
  6. Do not change the version number.
  7. If necessary, rebase your commits into logical chunks, with no failing commits.
  8. Push the branch to GitHub.
  9. Send a pull request to the nwjsmith/thumbtack project.

Run the tests

$ bundle install

# Run only the unit tests (no communication/authentication with Pinboard)
$ bundle exec rake test:unit

# Run the full test suite (will communicate with Pinboard)
$ bundle exec rake test

Note to run the full test suite, copy and paste your API Token into the test/auth_token.txt file. It should look something like this:



Thumbtack is released under the MIT License.


The best Ruby Pinboard API client




No packages published