Skip to content


Subversion checkout URL

You can clone with
Download ZIP
tree: d7a5ec1a93
Fetching contributors…

Cannot retrieve contributors at this time

executable file 85 lines (47 sloc) 2.717 kb

Create An Application

First, join Findings!

create an application here

Record your consumer key and secret. Be sure to set the callback url of your application.

OAuth Client

Put your key and secret from your application into the API_SETTINGS in the client.

Example Application

See the "findingsdjango" directory in the github repository for an example Findings posting application.

Atom feed of the public timeline

A public Atom feed of the last 20 clips posted to Findings is available at


Clip: A clip is a user's clip from a document. It contains information about when and who created it. It will contain the document, and the publisher of the document.

Document: A document is what a user's clip refers to. It's a piece of text with additionally an url (for a web document) or a set of book metadata (for a book clipping).

Page: Contains the next and previous urls for the next and previous set of data about this resultset.


Older documents do not have creation times.


Requires: a valid application key.

Base Url:

Returns: json



  • start_after: the element id for the next link the next pagination starts after
  • start_before: the element id the link for previous pagination result starts before
  • num: the number of items to return in the resultset


Show this username's clips:

Show 10 of this username's clips using the previous link (and appending your key).


Requires: a valid application key and an OAuth call with valid access tokens.

Base Url: /api/v1/

Returns: json

Post: Create A Clipping

There are two kinds of clippings in Findings, book and web. To post a web clip you define the url, to post a book clip you must currently define the isbn (by title, author is coming soon).

Possible post parameters:

  • isbn: if present the clipping is assigned to 'book'
  • private: if not present, the private flag is set to false
  • content: required. this is the clipping content
  • url: if present, the clipping is assigned to 'web'
  • note: a note about the clipping

So the required items are "content" and one of either "url" or "isbn".

Jump to Line
Something went wrong with that request. Please try again.