Fetching contributors…
Cannot retrieve contributors at this time
217 lines (140 sloc) 4.31 KB


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 (