To enable maximum ease of development for existing Twitter API users, Present.ly has an API that is fully compatible with the existing Twitter API structure.

Accessing the API

Just as with the Twitter API, the Present.ly API can be accessed via HTTP Basic authentication. The primary difference is that there is no data accessible without authentication in the Present.ly API, since the data is all private.

The URL structure works as follows:

https://<account_name>.presently.com/api/twitter/<twitter url>

So to access, for instance, the friends timeline, you could make a simple API call like so (note that you must have cURL with SSL support enabled):

curl -u <login>:<password> https://&lt;account_name&gt;.presently.com/api/twitter/statuses/fri...

Available Features

The entirety of the Twitter REST API is available except for the following:

• /statuses/featured
• /account/update_delivery_device
• /account/rate_limit_status
• /favorites/* - No favoriting at this time.
• /blocks/* - No blocking at this time.
• /help/test
• /help/downtime_status

Help/More Information

If you run into problems or need more details about the API's implementation, please contact support@presently.com.

Additions

The Present.ly Twitter API has been extended where appropriate to account for features of Present.ly that do not appear in Twitter. Documentation for these features is below.

Receiver

Because Present.ly offers an integrated home stream with direct messages and group messages, we have added a "receiver" attribute to statuses when a message is a) a direct message or b) a direct message to a group. This is implemented like so:

<status>
  ...
  <receiver>
    <type>group</type>
    <id>mygroup</id>
  </receiver>
  ...
</status>

Where type could be either "user" for a DM or "group" for a group message.

Attachments

Present.ly allows for users to attach files to updates. The following are the API methods related to attachments.

Sample XML Structure

<attachment>
  <created_at>2008-07-29 19:43:50 UTC</created_at>
  <id>6</id>
  <content_type>application/msword</content_type>
  <file_name>your_file.doc</file_name>
  <size>1150976</size>
  <url>https://url.of.your.file/&lt;/url&gt;
</attachment>

/attachments (coming soon)

Returns the 20 most recent files attached to updates for the authenticating user's account.

• URL: http://<account>.presently.com/api/twitter/attachments.format
• Formats: xml, json

Parameters:

• since: Retrieve only attachments that have been created since the time code specified here.
• since_id: Retrieve only attachments that have an id greater than this one.
• since_update_id: Retrieve only attachments that were attached to updates later than the specified update id.
• page: Optional.
• user: Retrieve only attachments that were uploaded by the specified user (login or id)
• group: Retrieve only attachments taht were uploaded by the specified group (login or id)

/attachments/destroy (coming soon)

Text Attachments

Updates may have additional text attached to them with a number of formatting options. If an update contains a text attachment a "paste" element will be included in the update. The format will be like so:

<paste>
  <format>ruby</format>
  <text>puts 'this is a text attachment'</text>
</paste>

For more information about the formats available, see Text Attachment Formats.

Groups

Present.ly allows users to create groups which may be referred to

/groups

Lists out all publicly visible groups for the authenticating user's account in the requested format.

/groups/show/<group_short_name>

Displays the details of the specified group in the requested format.

/groups/join/<group_short_name>

Causes the authenticating user to join the specified group. Returns the group that was joined in the requested format.

/groups/leave/<group_short_name>

Causes the authenticating user to leave the specified group. Returns the group that was left in the requested format.

/groups/create (coming soon)

Create a new group.

/groups/broadcast/<group_short_name>

Requires an authenticated POST with a status parameter that is the message to be broadcasted. If the authenticating user is the manager of the group or an administrator, creates a broadcast update from the group.

Account

Information about your Present.ly account.

/info (coming soon)

Information about the account (only accessible by account administrators).

/account/broadcast

Requires an authenticated POST with a status parameter that is the message to be broadcasted. If the authenticating user is an administrator of the account, it will send a broadcast update from the system.

Statuses

Additional methods to leverage the extra functionality provided in Present.ly for statuses.

/tags (coming soon)

A list of all of the tags and their counts for this account. Includes the latest update for a given tag.

/tags/show (coming soon)

Show all updates for a given tag.

Inline Attachments

If a user has attached a file to a Present.ly update, it will be inlined as "attachment" in XML or JSON. An update may only have a single attachment.