Ruby library for using Kippt API (
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.
spec Updates tests to new expect RSpec syntax Jul 31, 2015
.rspec Adds RSpec Apr 28, 2012
Rakefile Adds RSpec Apr 28, 2012


Kippt is a gem that provides a client library for using API.

Build Status


Add this line to your application's Gemfile:

gem "kippt"

And then execute:

$ bundle

Or install it yourself as:

$ gem install kippt



To be able to use the API you need to authenticated. There's two ways to authenticate:

With login credentials

client = "vesan", password: "s3cr3t")
# Methods called on `client` will use the passed credentials

With token

client = "vesan", token: "2544d6bfddf5893ec8617")
# Methods called on `client` will use the passed credentials

Or you can use the API unauthenticated:

client = true)


You can get the current authenticated user:

client = "vesan", token: "2544d6bfddf5893ec8617")
account = client.account
account.username #=> "vesan"
account = client.account(true) # includes the API token
account.api_token    #=> "2544d6bfddf5893ec8617"

Always use the API token instead of the password if possible because it's more secure.



Get all the lists:

client = "vesan", token: "2544d6bfddf5893ec8617")
lists = client.lists.fetch # Returns Kippt::ListCollection

Get single list:

client = "vesan", token: "2544d6bfddf5893ec8617")
list_id = 10
list = client.lists[list_id] # Returns Kippt::ListItem

Get single lists’s clips:

client = "vesan", token: "2544d6bfddf5893ec8617")
list_id = 10
list = client.lists[list_id].clips # Returns a Kippt::ClipCollection

# OR

list ={ id: list_id }, client)
list.clips # Returns a Kippt::ClipCollection


client = "vesan", token: "2544d6bfddf5893ec8617")
client.clips.fetch # Returns Kippt::ClipCollection

# Returns first page of clips for an URL
client.clips.fetch(url: "")

# Returns first page of clips added in the last day
client.clips.fetch(since: - 86400)

Both ListCollection and ClipCollection are Enumerable.


Lists and clips are paginated:

client = "vesan", token: "2544d6bfddf5893ec8617")
clips = client.clips.fetch


You can get next and previous set of results:

clips.next_page? #=> true
clips.next_page # Returns new Kippt::ClipCollection
clips.previous_page? #=> true
clips.previous_page # Returns new Kippt::ClipCollection

Limit and offset can be controlled manually:

client.clips.fetch(limit: 25, offset: 50)


Clips can be searched:"kippt") #=> Returns Kippt::ClipCollection

Other available options are is\_starred: true and list: [list-id] like: "kippt", list: 5, is_starred: true)

Creating and updating resources

You can create new resources, here for example clips:

clip =
clip.url = "" #=> Returns boolean

If you are missing required fields #save will return false and you can use #errors to get the error messages returned by the API.

clip =   #=> false
clip.errors #=> ["No url."]

Deleting resources

Deleting resources is done with #destroy:

clip_id = 1001
clip = client.clips[clip_id]
clip.destroy #=> true


To get more information on what is going on under the covers, set DEBUG=true as environment variable or pass debug: true in the Kippt::Client options hash like:

client = true, debug: true)


  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Do your changes
  4. Run the tests (rspec spec)
  5. Commit your changes (git commit -am 'Added some feature')
  6. Push to the branch (git push origin my-new-feature)
  7. Create new Pull Request (