Overview

Introduction

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

Versioning

• Current version: 2.1

• request token url: http://api.pownce.com/2.1/oauth/request_token
• user authorization url: http://api.pownce.com/2.1/oauth/authorize
• access token url: http://api.pownce.com/2.1/oauth/access_token
• signature methods: HMAC-SHA1
• request token expiration: 1 day
• access token expiration: never, may revoke an access token using the auth/revoke endpoint

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.

• url: http://api.pownce.com/2.1/note_lists.{format}
• request methods: GET
• authentication: None
• required url parameters:
• {format} The expected response format. Options are xml, or json.
  • optional url parameters:
• type={type} Filter the public notes by type. Options are messages, links, or events.
• limit={limit} Limit the number of notes returned. Default is 20 and max is 100.
• page={page} Page number. Starts at 0.
• since_id={since_id} Limit the notes returned to those greater than the specified note id.
  • example request: http://api.pownce.com/2.1/note_lists.xml?limit=10&page=2
  • notes:
• This endpoint replaces the public note list endpoint from previous versions.

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.

• url: http://api.pownce.com/2.1/note_lists/{username}.{format}
• request methods: GET
• authentication: None, HTTP basic, OAuth
• required url parameters:
• {username} Username of a Pownce user.
• {format} The expected response format. Options are xml, or json.
  • required parameters (HTTP basic authenticated user):
• {app_key} The application key assigned during registration. Optional, but recommended for non-authenticated requests.
  • optional url parameters:
• type={type} Filter the notes by type. Options are messages, links, or events. Authenticated users may also filter by files.
• limit={limit} Limit the number of notes returned. Default is 20 and max is 100.
• page={page} Page number. Starts at 0.
• since_id={since_id} Limit the notes returned to those greater than the specified note id.
  • optional url parameters (authenticated user):
• filter={filter} Get a subset of the authenticated user's note list. Options are notes (no replies), replies, sent, public, private, nonpublic (private and friends-only notes), and all. If no filter is specified, the notes will be returned according to the user's preferences.
• set={set_id} Filter the authenticated user's notes by a particular set. Only available for the authenticated user's own notes.
  • example requests:
• http://api.pownce.com/2.1/note_lists/dburka.json?type=links&page=2 Links for dburka, page 3.
• http://api.pownce.com/2.1/note_lists/ariel.xml?type=messages&filter=sent&limit=1 Latest message by ariel.
• http://api.pownce.com/2.1/note_lists/leahculver.json?set=13613 My notes, filtered by one of my sets.
  • notes:
• A list of public notes will be returned for any non-authenticated user. This endpoint replaces the user's public note list endpoint from previous versions. To get the authenticated user's public notes, use filter=public.
• For a friend of the authenticated user, this method will return notes sent by that friend including private and friends-only notes.

• url: http://api.pownce.com/2.1/notes/{note_id}.{format}
• request methods: GET
• authentication: None, HTTP basic, OAuth
• required url parameters:
• {note_id} ID of the desired note.
• {format} The expected response format. Options are xml, or json.
  • required url parameters (HTTP basic authenticated user):
• {app_key} The application key assigned during registration. Optional, but recommended for non-authenticated requests.
  • optional url parameters:
• show_replies={show_replies} By default the replies will not be included. To get the note with replies, use show_replies=true. Options are true or false.
• recipient_limit={recipient_limit} Number or recipients listed. Default is 0 and max is 100.
  • example request: http://api.pownce.com/2.1/notes/2155.xml
  • notes:
• If the note is not public or not viewable to the authenticated user, a 403 Response Forbidden error will be returned.

• url: http://api.pownce.com/2.1/notes/{note_id}/recipients.{format}
• request methods: GET
• authentication: None, HTTP basic, OAuth
• required url parameters:
• {note_id} ID of the desired note.
• {format} The expected response format. Options are xml, or json.
  • required url parameters (HTTP basic authenticated user):
• {app_key} The application key assigned during registration. Optional, but recommended for non-authenticated requests.
  • optional url parameters:
• limit={limit} Limit the number of recipients returned. Default is 20 and max is 100.
• page={page} Page number. Starts at 0.
  • example request: http://api.pownce.com/2.1/notes/2155/recipients.xml?limit=15
  • notes:
• This endpoint should only be used if you would like to display a separate page of note recipients (without a note).
• If the note is not public or not viewable to the authenticated user, a 403 Response Forbidden error will be returned.

• url: http://api.pownce.com/2.1/users/{username}.{format}
• request methods: GET
• authentication: None, HTTP basic, OAuth
• required url parameters:
• {username} Username of a Pownce user.
• {format} The expected response format. Options are xml, or json.
  • required url parameters (HTTP basic authenticated user):
• {app_key} The application key assigned during registration. Optional, but recommended for non-authenticated requests.
  • optional url parameters:
• {email} Email address of a Pownce user. This will look up a Pownce user by email address if the user allows searching by email in their privacy settings.
  • example requests:
• By username: http://api.pownce.com/2.1/users/bradfitz.xml
• By email: http://api.pownce.com/2.1/users.xml?email=brad@danga.com
  • notes:
• Response fields may differ based on a member's privacy settings and if they are authenticated.

• url: http://api.pownce.com/2.1/users/{username}/{relationship}.{format}
• request methods: GET
• authentication: None, HTTP basic, OAuth
• required url parameters:
• {username} Username of a Pownce user.
• {relationship} Options are friends, fans, or fan_of.
  • friends Users who have a mutual relationship with this user.
  • fans Users who are fans of the user.
  • fan_of This user is a fan of these users.
• {format} The expected response format. Options are xml, or json.
  • required url parameters (HTTP basic authenticated user):
• {app_key} The application key assigned during registration. Optional, but recommended for non-authenticated requests.
  • optional url parameters:
• limit={limit} Limit the number of users returned. Default is 20 and max is 100.
• page={page} Page number. Starts at 0.
  • example request: http://api.pownce.com/2.1/users/dburka/friends.xml?page=2
  • notes:
• If the friends list is not public or not viewable by the authenticated user, a 403 Response Forbidden error will be returned. Applications should handle this gracefully.
• The list of friends is ordered alphabetically by first name. The fan list is unordered (for now).

• url: http://api.pownce.com/2.1/auth/verify.{format}
• request methods: GET
• authentication: HTTP basic, OAuth
• required url parameters:
• {format} The expected response format. Options are xml, or json.
• {app_key} The application key assigned during registration. Not required for OAuth.

• url: http://api.pownce.com/2.1/auth/revoke.{format}
• request methods: DELETE
• authentication: OAuth
• required url parameters:
• {format} The expected response format. Options are xml, or json.
  • notes:
• This will delete the token and it cannot be used for subsequent requests.
• Applications can use this to clean up when a user logs out, though it is not required.

Posting

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.

• url: http://api.pownce.com/2.1/send/send_to.{format}
• request methods: GET
• authentication: HTTP basic, OAuth
• required url parameters:
• {format} The expected response format. Options are xml, or json.
• {app_key} The application key assigned during registration. Not required for OAuth.
  • notes:
• The selected parameter that is returned is the user's preference for their default "send to" option and developers should respect this preference.
• The list of potential recipients is unordered.
• Files cannot be sent to "the public" so you should gracefully omit this option when the user goes to post a file.

• url: http://api.pownce.com/2.1/send/message.{format}
• request methods: POST
• authentication: HTTP basic, OAuth
• required url parameters:
• {format} The expected response format. Options are xml, or json.
• {app_key} The application key assigned during registration. Not required for OAuth.
  • required POST parameters:
• {note_to} The recipient(s) of the note. Options are public, all, friend_x, or set_x. Available options for the authenticated user can be found from the Send To List endpoint.
• {note_body} The main text body of the note.
  • notes:
• Returns the note that was posted in the requested response format.

• url: http://api.pownce.com/2.1/send/link.{format}
• request methods: POST
• authentication: HTTP basic, OAuth
• required url parameters:
• {format} The expected response format. Options are xml, or json.
• {app_key} The application key assigned during registration. Not required for OAuth.
  • required POST parameters:
• {note_to} The recipient(s) of the note. Options are public, all, friend_x, or set_x. Available options for the authenticated user can be found from the Send To List endpoint.
• {url} The full url for the link. Ex: http://pythong.org
  • optional POST parameters:
• {note_body} The main text body of the note.
  • notes:
• Returns the note that was posted in the requested response format.

Post an Event

Post a note that contains an event.

• url: http://api.pownce.com/2.1/send/event.{format}
• request methods: POST
• authentication: HTTP basic, OAuth
• required url parameters:
• {format} The expected response format. Options are xml, or json.
• {app_key} The application key assigned during registration. Not required for OAuth.
  • required POST parameters:
• {note_to} The recipient(s) of the note. Options are public, all, friend_x, or set_x. Available options for the authenticated user can be found from the Send To List endpoint.
• {event_name} Name of the event.
• {event_location} Location of the event.
• {event_date} Date of the event in the format YYYY-MM-DD hh:mm. Ex: 2008-01-16 20:00
  • optional POST parameters:
• {note_body} The main text body of the note.
  • notes:
• Returns the note that was posted in the requested response format.
• Event date seconds will be ignored.

• url: http://api.pownce.com/2.1/send/file.{format}
• request methods: POST
• authentication: HTTP basic, OAuth
• required url parameters:
• {format} The expected response format. Options are xml, or json.
• {app_key} The application key assigned during registration. Not required for OAuth.
  • required POST parameters:
• {note_to} The recipient(s) of the note. Options are all, friend_x, or set_x. Available options for the authenticated user can be found from the Send To List endpoint.
• {media_file} The data of the file.
  • optional POST parameters:
• {note_body} The main text body of the note.
  • notes:
• Returns the note that was posted in the requested response format.
• Users with pro accounts may upload larger files, this endpoint works for both Pro and non-Pro users.
• The file size limit will be respected server-side, so please make the limit clear to users.
• For OAuth requests, put the OAuth-specific parameters in the header or url, not the post body. For now this is the best way to keep the file data separate from the url encoded parameters.

Post a Reply

Post a reply to a note.

• url: http://api.pownce.com/2.1/send/reply.{format}
• request methods: POST
• authentication: HTTP basic, OAuth
• required url parameters:
• {format} The expected response format. Options are xml, or json.
• {app_key} The application key assigned during registration. Not required for OAuth.
  • required POST parameters:
• {reply_to} The id of the note which this reply belongs to.
  • optional POST parameters:
• {note_body} The main text body of the note.
• {stars} (messages, links, and files) The star rating the user gave the original note. Options are 1, 2, 3, 4, or 5.
• {rsvp} (events) The rsvp reply for an event type note. Options are 1 Attending, 2 Busy Already, 3 Not Attending, 4 Running Late, 5 Bringing Friends, 6 Undecided, or 7 Wishing I Could Come!
  • notes:
• Returns the note that was posted in the requested response format with replies.
• If no stars or rsvp POST parameter is present, then the note_body is required.

• url: http://api.pownce.com/2.1/oembed.{format}?url={url}
• request methods: GET
• authentication: None, HTTP basic, OAuth
• required url parameters:
• {format} The expected response format. Options are xml, or json.
• {url} The url to the permalink page for the note.
  • required url parameters (HTTP basic authenticated user):
• {app_key} The application key assigned during registration. Optional, but recommended for non-authenticated requests.
  • optional url parameters:
• maxwidth={maxwidth} The maximum width of the embedded resource.
• maxheight={maxheight} The maximum height of the embedded resource.
  • example request: http://api.pownce.com/2.1/oembed.xml?url=http://pownce.com/laughingsquid/notes/2118420/
  • notes:
• Notes that contain embeddable content will also contain OEmbed data in the response (no additional API call is necessary).
• If there is no embeddable content for the note, this endpoint will return a 404 Not Found error.
• If the url is not public or not viewable to the authenticated user, a 403 Response Forbidden error will be returned.
• Pownce only provides one size for each thumbnail image or video, so if the maxwidth or maxheight requested is smaller than the available thumbnail, the OEmbed response will instead contain a URL.

• default simple url: http://pownce.com/send/

Send a Message

• url: http://pownce.com/send/message/
• optional url parameters:
• {note_body} The main text body of the note.
• {note_to} The recipient(s) of the note. Options are public, all, friend_x, or set_x.
  • example link: http://pownce.com/send/message/?note_body=Hello+world%21¬e_to=public

• url: http://pownce.com/send/link/
• optional url parameters:
• {url} The full url for the link.
• {note_body} The main text body of the note.
• {note_to} The recipient(s) of the note. Options are public, all, friend_x, or set_x.
  • example link: http://pownce.com/send/link/?url=http%3A%2F%2Fxkcd.com%2F388%2F¬e_body=Lemons+are+not+untasty%21

Send an Event

• url: http://pownce.com/send/event/
• optional url parameters:
• {event_name} Name of the event.
• {event_location} Location of the event.
• {event_date} Date of the event in the format YYYY-MM-DD. Ex: 2008-01-16
• {event_time} Time of the event in the format hh:mm. Ex: 20:00
• {note_body} The main text body of the note.
• {note_to} The recipient(s) of the note. Options are public, all, friend_x, or set_x.
  • example link: http://pownce.com/send/event/?event_name=Drinking%20at%20Fly%20Bar&event_location=62%20Divisadero%20St,%20San%20Francisco,%20CA&event_date=2008-03-27&event_time=10:00¬e_body=Let's%20celebrate%20something.

• recent public notes: http://pownce.com/feeds/public/
• user's notes: http://pownce.com/feeds/public/{username}/

• public events: webcal://pownce.com/ical/events/public/
• my upcoming events: webcal://pownce.com/ical/events/upcoming/{syndication_key}/
• events I'm attending: webcal://pownce.com/ical/events/attending/{syndication_key}/