API Documentation2-0

This is the current version of the API. Older versions may be found here.


(Note: This page is currently locked from community editing.)






Pownce has an Application Programming Interface (API) for anyone to create fun projects with Pownce.




Previous Versions


The API request URL has a version parameter which ensures compatibility when a new version of the Pownce API is released. If the version number is omitted from the URL, Pownce will assume the latest version of the API.



To access private data or post a note via the Pownce API, developers will need to authenticate the Pownce user. There are currently two methods for authenticating users for the Pownce API: Http Basic Authentication and OAuth.


Registering an Application

First, developers must register their application via the Pownce website. It is possible to edit application information at any time, and the application won't appear in the application directory until published.


Register your application: http://pownce.com/api/apps/new/

View all your applications: http://pownce.com/api/apps/


Http Basic Authentication

Developers will need to construct and send the appropriate authorization header. To construct the header:

  • append the username and password like username:password
  • base-64 encode the username:password
  • send the "Authorization" header with the value "Basic x" where x is the base-64 encoded username:password


See: Http Basic Authentication


With each Http Basic authenticated request, the parameter app_key must also be included. The app_key is the application key assigned when the application was registered.


OAuth Authentication

OAuth is so hot right now and the Pownce API has it.



Your oauth_consumer_key and oauth_consumer_secret are your application key and application secret assigned when you registered your application. The app_key parameter is not required since each OAuth request must contain the oauth_consumer_key.


See: OAuth website, OAuth documentation


Authentication Help

If you are having trouble with authentication please post a message to the Google Group.



It is up to Pownce application developers to decide how to paginate lists of items by using the limit={limit} and page={page} parameters. The first page is page 0. For example, if I like 5 friends per page and I want the 3rd page of friends for Daniel Burka, I would use: http://api.pownce.com/2.0/users/dburka/friends.xml?limit=5&page=2


If a particular page does not exist, a HTTP 404 error is returned and applications should handle this gracefully.


Rate Limiting / Throttling


The API currently has no limit on the number of requests applications can make. Please be kind to the API so we can keep it that way and try to use the minimum number of requests to accomplish a task. If you need help figuring out how to efficiently perform a task, feel free to ask in the Google Group.


Posting notes does have a rate limit per user. Each user may post 20 notes every 10 minutes (average 2 per minute) and no more than 300 notes per day. This limit is to prevent spammers and friend-annoyers.


JSON Callback Parameter

Developers may include an optional JavaScript callback parameter callback={callback} for JSON requests. The response will then be wrapped in the callback function. For example if I include the parameter callback=testFunction the response will look like testFunction(...);


Callback function names must start with a letter and are restricted to letters, numbers and underscores.


Cross Domain XML

Adobe Flash applications have permission to access the Pownce API and the cross domain XML file can be found at http://api.pownce.com/crossdomain.xml


Try It Out


You can try all the API methods via a web browser or use the command-line tool, cURL. You probably already have cURL. Try getting Kevin Rose's public profile by typing the following into the command-line:



curl http://api.pownce.com/2.0/users/kevin.xml


Test out authentication by verifying the authorized user.


curl -H "Authorization: basic {encoded}" "http://api.pownce.com/2.0/auth/verify.xml?app_key={app_key}"



The easiest way to get help with the Pownce API is to check out our Google Group. Feel free to join and ask questions, suggest improvements, and collaborate on projects.


Is there something you want from the Pownce API that you can't seem to find? Try posting to the Google Group with the information you'd like from the API. More API endpoints WILL be added to the API depending on input from developers like you.


API Methods




Public Note List

Get a list of all recent public notes.


Note List

Get a list of notes for a user. To get your "inbox" of notes, the typical Pownce stream, you'll need to call this method with your own username and proper authentication. An authenticated call with a friend's username will return all the notes that they've sent you (public and private). Without authentication, this method returns a list of public notes sent by the user.



Get a particular note by id.


Note Recipient List

Get a list of recipients for a particular note.





Get an individual user's profile information.


Friends, Fans, and Fan Of

Get an individual user's relationship data.




Verify Auth

Check that authentication is successful. This endpoint can be used to either test if the Http Basic auth header is correct or if your request has a valid OAuth access token.




Send To List

Get a the list of potential recipients for the authenticated user. Includes options for the public, all friends, sets, and individual friends.


Post a Message

Post a note that contains only a message.


Post a Link

Post a note that contains a link.


Post an Event

Post a note that contains an event.


Post a File

Post a note that contains a file.


Post a Reply

Post a reply to a note.


API Error Responses


Errors are returned in the same format as the request.


The response contains:


The WWW-Authenticate header is returned for any endpoints which require authentication.


Pownce Integration


Send To Pownce

Post content to Pownce via a the Pownce website with a simple link.



Send a Message


Send a Link


Send an Event



Note Feed

Atom feeds are currently available for all recent public notes as well as a user's public notes.



Calendar Feed

There's an iCal feed for upcoming, attending, and all public events. This feed can be used with calendar applications such as Google calendar.