Plurk API 1.0 is deprecated.

Though we still support Plurk API 1.0, you're recommended to switch to Plurk API 2.0 for a better support.

Plurk API 1.0 (deprecated)

Plurk API provides a standard way of accessing and implementing applications on top of the Plurk platform. The API is a simple HTTP API that can be accessed from any language that supports creation of HTTP requests.

You can contact us if you have any problems or wish to report bugs.

The API returns JSON encoded data. You should use a JSON library to decode the data returned. Some good JSON libraries are simplejson (Python), JSON.simple (Java) or json (Ruby).

The current limit is 50.000 calls pr. day. If you need more than this contact us with a description of what you are making.

Useful resources

Tools:

Implementations:

Get an API key

Please login first before you can get an API key.

Table of contents

Python example

Example of using Plurk API from Python (using only Python standard library). In this example we login and plurk a hello world message :)

NOTE: In your real code you should do HTTPS requests to /API/Users/login and /API/Users/update. 

#--- Setup ----------------------------------------------
import urllib, urllib2, cookielib

opener = urllib2.build_opener(urllib2.HTTPCookieProcessor())
api_key = 'dKkIdUCoHo7vUDPjd3zE0bRvdm5a9sQi'
get_api_url = lambda x: 'http://www.plurk.com/API%s' % x
encode = urllib.urlencode


#--- Requests ----------------------------------------------
fp = opener.open(get_api_url('/Users/login'),
                 encode({'username': 'user_x',
                         'password': 'user_x_pw',
                         'api_key': api_key}))
print fp.read()

fp = opener.open(get_api_url('/Timeline/plurkAdd'),
                 encode({'content': 'hello world',
                         'qualifier': 'says',
                         'lang': 'en',
                         'api_key': api_key}))
print fp.read()

Java example

Here's how to login and plurk a message using Java and Apache's HttpClient library (which we recommend, since it offers a higher abstractions than Java's standard library).

NOTE: In your real code you should do HTTPS requests to /API/Users/login and /API/Users/update. 

import org.apache.http.impl.client.BasicResponseHandler;
import org.apache.http.impl.client.DefaultHttpClient;
import org.apache.http.client.ResponseHandler;
import org.apache.http.client.HttpClient;
import org.apache.http.client.methods.HttpGet;

public class TestClass {

    private static String API_KEY = "dKkIdUCoHo7vUDPjd3zE0bRvdm5a9sQi";

    public static String getApiUri(String uri) {
        return "http://www.plurk.com/API" + uri;
    }

    public final static void main(String[] args) throws Exception {
        HttpClient httpclient = new DefaultHttpClient();

        HttpGet httpget = new HttpGet(getApiUri("/Users/login?"+
                            "api_key=" + API_KEY + "&" +
                            "username=" + "user_x" + "&" +
                            "password=" + "user_x_pw"
                          ));

        ResponseHandler responseHandler = new BasicResponseHandler();
        System.out.println(httpclient.execute(httpget, responseHandler));

        httpget = new HttpGet(getApiUri("/Timeline/plurkAdd?"+
                "api_key=" + API_KEY + "&" +
                "content=" + "Hello+nasty" + "&" +
                "qualifier=" + "says" + "&" +
                "lang=en"
        ));

        responseHandler = new BasicResponseHandler();
        System.out.println(httpclient.execute(httpget, responseHandler));

        httpclient.getConnectionManager().shutdown();
    }
}

Plurk data

A plurk and it's data

A plurk is encoded as a JSON object. The dates used will be UTC and you are expected to post UTC to the Plurk server as well. You should render the time in user's local time. Typically it will be returned as following:

{"responses_seen": 0, "qualifier": "thinks", "plurk_id": 90812, "response_count": 0, "limited_to": null, "no_comments": 0, "is_unread": 1, "lang": "en", "content_raw": "test me out", "user_id": 1, "plurk_type": 0, "content": "test me out", "qualifier_translated": "thinks", "posted": "Fri, 05 Jun 2009 23:07:13 GMT", "owner_id": 1}

If &minimal_data=1 is sent as an argument to the request, then some of this data will be removed (this is recommended if you want to optimize bandwidth usage). content_raw and any null attribute will be removed. The above example will look like:

{"lang": "en", "posted": "Fri, 05 Jun 2009 23:07:13 GMT", "qualifier": "thinks", "plurk_id": 90812, "owner_id": 1, "content": "test me out", "user_id": 1, "is_unread": 1, "no_comments": 0, "plurk_type": 0}

Plurk attributes:
plurk_id: The unique Plurk id, used for identification of the plurk.
qualifier: The English qualifier, can be "says", show all:
qualifier_translated: Only set if the language is not English, will be the translated qualifier. Can be "siger" if plurk.lang is "da" (Danish).
is_unread: Specifies if the plurk is read, unread or muted.
plurk_type: Specifies what type of plurk it is and if the plurk has been responded by the user. The value of plurk_type is only correct when calling getPlurks with only_responded filter (this is done for perfomance and caching reasons).
user_id: Which timeline does this Plurk belong to.
owner_id: Who is the owner/poster of this plurk.
posted: The date this plurk was posted.
no_comments: If set to 1, then responses are disabled for this plurk.
If set to 2, then only friends can respond to this plurk.
content: The formatted content, emoticons and images will be turned into IMG tags etc.
content_raw: The raw content as user entered it, useful when editing plurks or if you want to format the content differently.
response_count: How many responses does the plurk have.
responses_seen: How many of the responses have the user read. This is automatically updated when fetching responses or marking a plurk as read.
limited_to: If the Plurk is public limited_to is null. If the Plurk is posted to a user's friends then limited_to is [0]. If limited_to is [1,2,6,3] then it's posted only to these user ids.

User data

A user and the data

Depending on what kind of request it is the data returned varies. For responses and plurks, the data returned is minimal and will look like this:

{"display_name": "amix3", "gender": 0, "nick_name": "amix", "has_profile_image": 1, "id": 1, "avatar": null}

This can be used to render minimal info about a user.

For other type of requests, such as viewing a friend list or a profile, the data returned will be larger:

{"display_name": "Alexey", "is_channel": 0, "nick_name": "Scoundrel", "has_profile_image": 1, "location": "Canada", "date_of_birth": "Sat, 19 Mar 1983 00:00:00 GMT", "relationship": "not_saying", "avatar": 3, "full_name": "Alexey Kovyrin", "gender": 1, "page_title": "", "recruited": 6, "id": 5, "karma": 33.5}

User attributes:
id: The unique user id.
nick_name: The unique nick_name of the user, for example amix.
display_name: The non-unique display name of the user, for example Amir S. Only set if it's non empty.
has_profile_image: If 1 then the user has a profile picture, otherwise the user should use the default.
avatar: Specifies what the latest avatar (profile picture) version is.
location: The user's location, a text string, for example Aarhus Denmark.
date_of_birth: The user's birthday.
bday_privacy: 0: hide birthday, 1: show birth date but not birth year, 2: show all
full_name: The user's full name, like Amir Salihefendic.
gender: 1 is male, 0 is female, 2 is not stating/other.
page_title: The profile title of the user.
karma: User's karma value.
recruited: How many friends has the user recruited.
relationship: Can be not_saying, single, married, divorced, engaged, in_relationship, complicated, widowed, unstable_relationship, open_relationship

About birth date privacy

If user selects to hide his birthday (bday_privacy=0), the returned date_of_birth will be null. If user selects to hide his age (bday_privacy=1), the returned date_of_birth will be altered by updating the birth year to 1904.

How to render the avatar

One needs to construct the avatar URL. user_id specifies user's id while avatar specifies the profile image version.

If has_profile_image == 1 and avatar == null then the avatar is:

http://avatars.plurk.com/{user_id}-small.gif
http://avatars.plurk.com/{user_id}-medium.gif
http://avatars.plurk.com/{user_id}-big.jpg

If has_profile_image == 1 and avatar != null:

http://avatars.plurk.com/{user_id}-small{avatar}.gif
http://avatars.plurk.com/{user_id}-medium{avatar}.gif
http://avatars.plurk.com/{user_id}-big{avatar}.jpg

If has_profile_image == 0:

http://www.plurk.com/static/default_small.gif
http://www.plurk.com/static/default_medium.gif
http://www.plurk.com/static/default_big.gif

Users

/API/Users/login

Login an already created user. Login creates a session cookie, which can be used to access the other methods. On success it returns the data returned by /API/Profile/getOwnProfile. Should be HTTPS.
Required parameters:
api_key: Your Plurk API key.
username: The user's nick name or email.
password: The user's password.
Optional parameters:
no_data: If it's set to "1" then the common data is not returned. Use this if you only want to login the user and don't plan to use the data that's supplied by /API/Profile/getOwnProfile.
Successful return:
HTTP 200 OK with the data of /API/Profile/getOwnProfile if no_data isn't set.
If no_data is set to "1" then {"success_text": "ok"} is returned.
Error returns:
HTTP 400 BAD REQUEST with {"error_text": "Invalid login"} as body
HTTP 400 BAD REQUEST with {"error_text": "Too many logins"} as body

/API/Users/logout

Required parameters:
api_key: Your Plurk API key.
Successful return:
{"success_text": "ok"} if the user is logged out.

/API/Users/update requires login

Update a user's information (such as email, password or privacy). Should be HTTPS.
Required parameters:
api_key: Your Plurk API key.
current_password: User's current password.
Optional parameters:
full_name: Change full name.
new_password: Change password.
email: Change email.
display_name: User's display name, can be empty and full unicode. Must be shorter than 15 characters.
privacy: User's privacy settings. The option can be world (whole world can view the profile) or only_friends (only friends can view the profile)
date_of_birth: Should be YYYY-MM-DD, example 1985-05-13.
Successful return:
HTTP 200 OK with a JSON object with updated user info {"id": 42, "nick_name": "frodo_b", ...}
Error returns:
HTTP 400 BAD REQUEST with {"error_text": "Invalid current password"} as body
HTTP 400 BAD REQUEST with {"error_text": "Email invalid"} as body
HTTP 400 BAD REQUEST with {"error_text": "Email already found"} as body
HTTP 400 BAD REQUEST with {"error_text": "Password too small"} as body
HTTP 400 BAD REQUEST with {"error_text": "Display name too long, should be less than 15 characters long"} as body
HTTP 400 BAD REQUEST with {"error_text": "Internal service error. Please, try later"} as body

/API/Users/updatePicture requires login

Update a user's profile picture. You can read more about how to render an avatar via user data. You should do a multipart/form-data POST request to /API/Users/updatePicture. The picture will be scaled down to 3 versions: big, medium and small. The optimal size of profile_image should be 195x195 pixels.
Required parameters:
api_key: Your Plurk API key.
profile_image: The new profile image.
Successful return:
HTTP 200 OK with a JSON object with updated user info {"id": 42, "nick_name": "frodo_b", ...}
Error returns:
HTTP 400 BAD REQUEST with {"error_text": "Requires login"} as body
HTTP 400 BAD REQUEST with {"error_text": "Not supported image format or image too big"} as body

/API/Users/getKarmaStats

Returns info about a user's karma, including current karma, karma growth, karma graph and the latest reason why the karma has dropped.
Required parameters:
api_key: Your Plurk API key.
Successful return:
HTTP 200 OK with a JSON object with karma stats {'karma_trend': ['1282046402-97.85', '1282060802-97.86', '1282075202-97.87', '1282089602-97.88', ...], 'karma_fall_reason': '', 'current_karma': 97.88, 'karma_graph': 'http://chart.apis.google.com/...'}
karma_trend:
Returns a list of 30 recent karma updates. Each update is a string '[[unixtimestamp]]-[[karma_value]]', e.g. a valid entry is '1282046402-97.85'
karma_fall_reason:
Why did karma drop? This value is a string and can be: friends_rejections, inactivity, too_short_responses

Profile

/API/Profile/getOwnProfile requires login

Returns data that's private for the currently logged in user. This can be used to construct a profile and render a timeline of the latest plurks.
Required parameters:
api_key: Your Plurk API key.
Successful return:
Returns a JSON object with a lot of information that can be used to construct a user's own profile and timeline.
Error returns:
HTTP 400 BAD REQUEST with {"error_text": "Requires login"} as body

/API/Profile/getPublicProfile

Fetches public information such as a user's public plurks and basic information. Fetches also if the current logged in user is following the user, are friends with or is a fan.
Required parameters:
api_key: Your Plurk API key.
user_id: The user_id of the public profile. Can be integer (like 34) or nick name (like amix).
Successful return:
Returns a JSON object with a lot of information that can be used to construct a user's public profile and timeline.
Error returns:
HTTP 400 BAD REQUEST with {"error_text": "Invalid user_id"} as body
HTTP 400 BAD REQUEST with {"error_text": "User not found"} as body

Real time notifications

Get instant notifications when there are new plurks and responses on a user's timeline. This is much more efficient and faster than polling so please use it!

This API works like this:

/API/Realtime/getUserChannel requires login

Required parameters:
api_key: Your Plurk API key.
Successful return:
Return's a JSON object with an URL that you should listen to, e.g.
{"comet_server": "http://comet03.plurk.com/comet/1235515351741/?channel=generic-4-f733d8522327edf87b4d1651e6395a6cca0807a0",
"channel_name": "generic-4-f733d8522327edf87b4d1651e6395a6cca0807a0"}

Comet channel specification

You'll get an URL from /API/Realtime/getUserChannel and you do GET requests to this URL to get new data. Your request will sleep for about 50 seconds before returning a response if there is no new data added to your channel. You won't get notifications on responses that the logged in user adds, but you will get notifications for new plurks.

Required parameters:
channel: You get this from /API/Realtime/getUserChannel channel_name parameter.
Optional parameters:
offset: Only fetch new messages from a given offset. You'll get offset when a response is returned, it's returned as new_offset.
Successful returns, but no new data:

Successful returns, with data:
Error returns:

Polling

/API/Polling/getPlurks requires login

You should use this call to find out if there any new plurks posted to the user's timeline.
It's much more efficient than doing it with /API/Timeline/getPlurks, so please use it :)

Required parameters:
api_key: Your Plurk API key.
offset: Return plurks newer than offset, formatted as 2009-6-20T21:55:34.
Optional parameters:
limit: The max number of plurks to be returned (default 50).
Successful return:
Returns a JSON object of plurks and their users, e.g. {"plurks": [{"plurk_id": 3, "content": "Test", "qualifier_translated": "says", "qualifier": "says", "lang": "en" ...}, ...], "plurk_users": {"3": {"id": 3, "nick_name": "alvin", ...}}
Error returns:
HTTP 400 BAD REQUEST with {"error_text": "Requires login"} as body

/API/Polling/getUnreadCount requires login

Use this call to find out if there are unread plurks on a user's timeline.

Required parameters:
api_key: Your Plurk API key.
Successful return:
Returns a JSON object of counts, e.g. {"all": 2, "my": 1, "private": 1, "responded": 0}
Error returns:
HTTP 400 BAD REQUEST with {"error_text": "Requires login"} as body

Timeline

/API/Timeline/getPlurk requires login

Required parameters:
api_key: Your Plurk API key.
plurk_id: The unique id of the plurk. Should be passed as a number, and not base 36 encoded.
Successful return:
Returns a JSON object of the plurk and the owner, e.g. {"plurks": {"plurk_id": 3, "content": "Test", "qualifier_translated": "says", "qualifier": "says", "lang": "en" ...}, ...], "user": {"id": 3, "nick_name": "alvin", ...}}
Error returns:
HTTP 400 BAD REQUEST with {"error_text": "Plurk owner not found"} as body
HTTP 400 BAD REQUEST with {"error_text": "Plurk not found"} as body
HTTP 400 BAD REQUEST with {"error_text": "No permissions"} as body

/API/Timeline/getPlurks requires login

Required parameters:
api_key: Your Plurk API key.
Optional parameters:
offset: Return plurks older than offset, formatted as 2009-6-20T21:55:34.
limit: How many plurks should be returned? Default is 20.
filter: Can be only_user, only_responded, only_private or only_favorite.
Successful return:
Returns a JSON object of plurks and their users, e.g. {"plurks": [{"plurk_id": 3, "content": "Test", "qualifier_translated": "says", "qualifier": "says", "lang": "en" ...}, ...], "plurk_users": {"3": {"id": 3, "nick_name": "alvin", ...}}
Error returns:
HTTP 400 BAD REQUEST with {"error_text": "Requires login"} as body

/API/Timeline/getUnreadPlurks requires login

Required parameters:
api_key: Your Plurk API key.
Optional parameters:
offset: Return plurks older than offset, formatted as 2009-6-20T21:55:34.
limit: Limit the number of plurks that is retunred.
filter: Limit the plurks returned, could be 'my', 'responded', 'private' or 'favorite' (default: 'all')
Successful return:
Returns a JSON object of unread plurks and their users, e.g. {"plurks": [{"plurk_id": 3, "content": "Test", "qualifier_translated": "says", "qualifier": "says", "lang": "en" ...}, ...], "plurk_users": {"3": {"id": 3, "nick_name": "alvin", ...}}
Error returns:
HTTP 400 BAD REQUEST with {"error_text": "Requires login"} as body

/API/Timeline/getPublicPlurks requires login

Required parameters:
api_key: Your Plurk API key.
user_id: The user_id of the public plurks owner to get. Can be integer (like 34) or nick name (like amix).
Optional parameters:
offset: Return plurks older than offset, formatted as 2009-6-20T21:55:34.
limit: Limit the number of plurks that is retunred.
Successful return:
Returns a JSON object of public plurks and user information, e.g. {"plurks": [{"plurk_id": 3, "content": "Test", "qualifier_translated": "says", "qualifier": "says", "lang": "en" ...}, ...], "plurk_users": {"3": {"id": 3, "nick_name": "alvin", ...}}
Error returns:
HTTP 400 BAD REQUEST with {"error_text": "Requires login"} as body

/API/Timeline/plurkAdd requires login

Required parameters:
api_key: Your Plurk API key.
content: The Plurk's text.
qualifier: The Plurk's qualifier, must be in English. Can be following:
Optional parameters:
limited_to: Limit the plurk only to some users (also known as private plurking). limited_to should be a JSON list of friend ids, e.g. limited_to of [3,4,66,34] will only be plurked to these user ids. If limited_to is [0] then the Plurk is privatley posted to the poster's friends.
no_comments: If set to 1, then responses are disabled for this plurk.
If set to 2, then only friends can respond to this plurk.
location: Should contain two coordinates be in decimal notation separated by a comma, example 52.2296756,21.0122287. Should specify the place where plurk has been finished and posted to servers.
lang: The plurk's language. Can be following:
Successful return:
Returns a JSON object of the new plurk, e.g. {"plurk_id": 3, "content": "Test", "qualifier_translated": "says", "qualifier": "says", "lang": "en" ...}
Error returns:
HTTP 400 BAD REQUEST with {"error_text": "Requires login"} as body
HTTP 400 BAD REQUEST with {"error_text": "Invalid data"} as body
HTTP 400 BAD REQUEST with {"error_text": "Must be friends"} as body
HTTP 400 BAD REQUEST with {"error_text": "Content is empty"} as body
HTTP 400 BAD REQUEST with {"error_text": "anti-flood-same-content"} as body
HTTP 400 BAD REQUEST with {"error_text": "anti-flood-spam-domain"} as body
HTTP 400 BAD REQUEST with {"error_text": "anti-flood-too-many-new"} as body

/API/Timeline/plurkDelete requires login

Required parameters:
api_key: Your Plurk API key.
plurk_id: The id of the plurk.
Successful return:
{"success_text": "ok"} if the plurk is deleted
Error returns:
HTTP 400 BAD REQUEST with {"error_text": "Requires login"} as body
HTTP 400 BAD REQUEST with {"error_text": "Plurk not found"} as body
HTTP 400 BAD REQUEST with {"error_text": "No permissions"} as body

/API/Timeline/plurkEdit requires login

Required parameters:
api_key: Your Plurk API key.
plurk_id: The id of the plurk.
content: The content of plurk.
Successful return:
Returns a JSON object of the updated plurk, e.g. {"plurk_id": 3, "content": "Test", "qualifier_translated": "says", "qualifier": "says", "lang": "en" ...}
Error returns:
HTTP 400 BAD REQUEST with {"error_text": "Requires login"} as body
HTTP 400 BAD REQUEST with {"error_text": "Plurk not found"} as body
HTTP 400 BAD REQUEST with {"error_text": "No permissions"} as body

/API/Timeline/mutePlurks requires login

Required parameters:
api_key: Your Plurk API key.
ids: The plurk ids, formated as JSON, e.g. [342,23242,2323]
Successful return:
{"success_text": "ok"} if the plurks are muted
Error returns:
HTTP 400 BAD REQUEST with {"error_text": "Requires login"} as body

/API/Timeline/unmutePlurks requires login

Required parameters:
api_key: Your Plurk API key.
ids: The plurk ids, formated as JSON, e.g. [342,23242,2323]
Successful return:
{"success_text": "ok"} if the plurks are unmuted
Error returns:
HTTP 400 BAD REQUEST with {"error_text": "Requires login"} as body

/API/Timeline/favoritePlurks requires login

Required parameters:
api_key: Your Plurk API key.
ids: The plurk ids, formated as JSON, e.g. [342,23242,2323]
Successful return:
{"success_text": "ok"} if the plurks are favorited
Error returns:
HTTP 400 BAD REQUEST with {"error_text": "Requires login"} as body

/API/Timeline/unfavoritePlurks requires login

Required parameters:
api_key: Your Plurk API key.
ids: The plurk ids, formated as JSON, e.g. [342,23242,2323]
Successful return:
{"success_text": "ok"} if the plurks are unfavorited
Error returns:
HTTP 400 BAD REQUEST with {"error_text": "Requires login"} as body

/API/Timeline/replurk requires login

Required parameters:
api_key: Your Plurk API key.
ids: The plurk ids, formated as JSON, e.g. [342,23242,2323]
Returns:
{"success": true, "results": {342: {"success": true, "error":""}}}where top-level success is true if all plurks has been replurked
Error returns:
HTTP 400 BAD REQUEST with {"error_text": "Requires login"} as body

/API/Timeline/unreplurk requires login

Required parameters:
api_key: Your Plurk API key.
ids: The plurk ids, formated as JSON, e.g. [342,23242,2323]
Returns:
{"success": true, "results": {342: {"success": true, "error":""}}}where top-level success is true if all plurks has been unreplurked
Error returns:
HTTP 400 BAD REQUEST with {"error_text": "Requires login"} as body

/API/Timeline/markAsRead requires login

Required parameters:
api_key: Your Plurk API key.
ids: The plurk ids, formated as JSON, e.g. [342,23242,2323]
Optional parameters:
note_position: If true responses_seen of the plurks will be updated as well (to match response_count).
Successful return:
{"success_text": "ok"} if the plurks are marked as read
Error returns:
HTTP 400 BAD REQUEST with {"error_text": "Requires login"} as body

/API/Timeline/uploadPicture requires login

To upload a picture to Plurk, you should do a multipart/form-data POST request to /API/Timeline/uploadPicture. This will add the picture to Plurk's CDN network and return a image link that you can add to /API/Timeline/plurkAdd

Plurk will automatically scale down the image and create a thumbnail.

Required parameters:
api_key: Your Plurk API key.
image: The image file.
Successful return:
Returns a JSON object of the links, e.g. like this {"full": "http://images.plurk.com/3466076_9b41abf90c623ba18f6ada5c1d37156f.jpg", "thumbnail": "http://images.plurk.com/tn_3466076_9b41abf90c623ba18f6ada5c1d37156f.gif"}.
Error returns:
HTTP 400 BAD REQUEST with {"error_text": "Requires login"} as body
HTTP 400 BAD REQUEST with {"error_text": "Invalid file"} as body

Responses

/API/Responses/get

Fetches responses for plurk with plurk_id and some basic info about the users.
Required parameters:
api_key: Your Plurk API key.
plurk_id: The plurk that the responses belong to.
from_response: Only fetch responses from an offset - could be 5, 10 or 15.
Successful return:
Returns a JSON object of responses, friends (users that has posted responses) and responses_seen (the last response that the logged in user has seen) e.g. {"friends": {"3": ...}, "responses_seen": 2, "responses": [{"lang": "en", "content_raw": "Reforms...}}
Error returns:
HTTP 400 BAD REQUEST with {"error_text": "Requires login"} as body
HTTP 400 BAD REQUEST with {"error_text": "Invalid data"} as body
HTTP 400 BAD REQUEST with {"error_text": "Plurk not found"} as body
HTTP 400 BAD REQUEST with {"error_text": "No permissions"} as body

/API/Responses/responseAdd requires login

Adds a responses to plurk_id. Language is inherited from the plurk.
Required parameters:
api_key: Your Plurk API key.
plurk_id: The plurk that the responses should be added to.
content: The response's text.
qualifier: The Plurk's qualifier, must be in English. Can be following:
Successful return:
Returns a JSON object of the new responses, e.g. {"id": 3, "content": "Test", "qualifier_translated": "says", "qualifier": "says", ...}
Error returns:
HTTP 400 BAD REQUEST with {"error_text": "Requires login"} as body
HTTP 400 BAD REQUEST with {"error_text": "Invalid data"} as body
HTTP 400 BAD REQUEST with {"error_text": "Content is empty"} as body
HTTP 400 BAD REQUEST with {"error_text": "Plurk not found"} as body
HTTP 400 BAD REQUEST with {"error_text": "No permissions"} as body
HTTP 400 BAD REQUEST with {"error_text": "anti-flood-same-content"} as body
HTTP 400 BAD REQUEST with {"error_text": "anti-flood-too-many-new"} as body

/API/Responses/responseDelete requires login

Deletes a response. A user can delete own responses or responses that are posted to own plurks.
Required parameters:
api_key: Your Plurk API key.
response_id: The id of the response to delete.
plurk_id: The plurk that the response belongs to.
Successful return:
{"success_text": "ok"} if the response has been deleted.
Error returns:
HTTP 400 BAD REQUEST with {"error_text": "Requires login"} as body
HTTP 400 BAD REQUEST with {"error_text": "Invalid data"} as body
HTTP 400 BAD REQUEST with {"error_text": "No permissions"} as body

Friends and fans

/API/FriendsFans/getFriendsByOffset

Returns user_id's friend list in chucks of 10 friends at a time.
Required parameters:
api_key: Your Plurk API key.
user_id
Optional parameters:
offset: The offset, can be 10, 20, 30 etc.
limit: The max number of friends to be returned (default 10).
Successful return:
Returns a list of JSON objects users, e.g. [{"id": 3, "nick_name": "alvin", ...}, ...]

/API/FriendsFans/getFansByOffset

Returns user_id's fans list in chucks of 10 fans at a time.
Required parameters:
api_key: Your Plurk API key.
user_id
Optional parameters:
offset: The offset, can be 10, 20, 30 etc.
limit: The max number of fans to be returned (default 10).
Successful return:
Returns a list of JSON objects users, e.g. [{"id": 3, "nick_name": "alvin", ...}, ...]

/API/FriendsFans/getFollowingByOffset requires login

Returns users that the current logged in user follows as fan - in chucks of 10 fans at a time.
Required parameters:
api_key: Your Plurk API key.
Optional parameters:
offset: The offset, can be 10, 20, 30 etc.
limit: The max number of followings to be returned (default 10).
Successful return:
Returns a list of JSON objects users, e.g. [{"id": 3, "nick_name": "alvin", ...}, ...]

/API/FriendsFans/becomeFriend requires login

Create a friend request to friend_id. User with friend_id has to accept a friendship.
Required parameters:
api_key: Your Plurk API key.
friend_id: The ID of the user you want to befriend.
Successful return:
{"success_text": "ok"} if a friend request has been made.
Error returns:
HTTP 400 BAD REQUEST with {"error_text": "User can't be befriended"} as body
HTTP 400 BAD REQUEST with {"error_text": "User already befriended"} as body

/API/FriendsFans/removeAsFriend requires login

Remove friend with ID friend_id. friend_id won't be notified.
Required parameters:
api_key: Your Plurk API key.
friend_id: The ID of the user you want to remove
Successful return:
{"success_text": "ok"} if friend_id has been removed as friend.

/API/FriendsFans/becomeFan requires login

Become fan of fan_id. To stop being a fan of someone, user /API/FriendsFans/setFollowing?fan_id=FAN_ID&follow=false.
Required parameters:
api_key: Your Plurk API key.
fan_id: The ID of the user you want to become fan of
Successful return:
{"success_text": "ok"} if the current logged in user is a fan of fan_id.

/API/FriendsFans/setFollowing requires login

Update following of user_id. A user can befriend someone, but can unfollow them. This request is also used to stop following someone as a fan.
Required parameters:
api_key: Your Plurk API key.
user_id: The ID of the user you want to follow/unfollow
follow: true if the user should be followed, and false if the user should be unfollowed.
Successful return:
{"success_text": "ok"} if following information is updated.
Error returns:
HTTP 400 BAD REQUEST with {"error_text": "User must be befriended before you can follow them"} as body

/API/FriendsFans/getCompletion requires login

Returns a JSON object of the logged in users friends (nick name and full name). This information can be used to construct auto-completion for private plurking. Notice that a friend list can be big, depending on how many friends a user has, so this list should be lazy-loaded in your application.
Required parameters:
api_key: Your Plurk API key.
Successful return:
{"2": {"nick_name": "kan", "full_name": "Kan Kan"}, "4": {"nick_name": "mitsuhiko", ...}, ...}

Alerts

General data structures

The data returned by getActive and getHistory can be of following nature:

Friendship request:
{"type": "friendship_request", "from_user": {"nick_name": ...}, "posted": ...}

Friendship pending:
{"type": "friendship_pending", "to_user": {"nick_name": ...}, "posted": ...}

New fan notification: (does not require actions from the user)
{"type": "new_fan", "new_fan": {"nick_name": ...}, "posted": ...}

Friendship accepted notification: (does not require actions from the user)
{"type": "friendship_accepted", "friend_info": {"nick_name": ...}, "posted": ...}

New friend notification: (does not require actions from the user)
{"type": "new_friend", "new_friend": {"nick_name": ...}, "posted": ...}

/API/Alerts/getActive requires login

Return a JSON list of current active alerts.
Required parameters:
api_key: Your Plurk API key.
Successful return:
[{"id": 42, "nick_name": "frodo_b", ...}, ...] JSON object of all the active alerts
Error returns:
HTTP 400 BAD REQUEST with {"error_text": "Requires login"} as body

/API/Alerts/getHistory requires login

Return a JSON list of past 30 alerts.
Required parameters:
api_key: Your Plurk API key.
Successful return:
[{"nick_name": "frodo_b", ...}, ...] JSON object of all the history alerts
Error returns:
HTTP 400 BAD REQUEST with {"error_text": "Requires login"} as body

/API/Alerts/addAsFan requires login

Accept user_id as fan.
Required parameters:
api_key: Your Plurk API key.
user_id: The user_id that has asked for friendship.
Successful return:
{"success_text": "ok"}
Error returns:
HTTP 400 BAD REQUEST with {"error_text": "Requires login"} as body

/API/Alerts/addAllAsFan requires login

Accept all friendship requests as fans.
Required parameters:
api_key: Your Plurk API key.
Successful return:
{"success_text": "ok"}
Error returns:
HTTP 400 BAD REQUEST with {"error_text": "Requires login"} as body

/API/Alerts/addAllAsFriends requires login

Accept all friendship requests as friends.
Required parameters:
api_key: Your Plurk API key.
Successful return:
{"success_text": "ok"}
Error returns:
HTTP 400 BAD REQUEST with {"error_text": "Requires login"} as body

/API/Alerts/addAsFriend requires login

Accept user_id as friend.
Required parameters:
api_key: Your Plurk API key.
user_id: The user_id that has asked for friendship.
Successful return:
{"success_text": "ok"}
Error returns:
HTTP 400 BAD REQUEST with {"error_text": "Requires login"} as body

/API/Alerts/denyFriendship requires login

Deny friendship to user_id.
Required parameters:
api_key: Your Plurk API key.
user_id: The user_id that has asked for friendship.
Successful return:
{"success_text": "ok"}
Error returns:
HTTP 400 BAD REQUEST with {"error_text": "Requires login"} as body

/API/Alerts/removeNotification requires login

Remove notification to user with id user_id.
Required parameters:
api_key: Your Plurk API key.
user_id: The user_id that the current user has requested friendship for.
Successful return:
{"success_text": "ok"}
Error returns:
HTTP 400 BAD REQUEST with {"error_text": "Requires login"} as body

Search

/API/PlurkSearch/search

Returns the latest 20 plurks on a search term.
Required parameters:
api_key: Your Plurk API key.
query: The query after Plurks.
Optional parameters:
offset: A plurk_id of the oldest Plurk in the last search result.
Successful return:
A JSON list of plurks that the user have permissions to see: [{"id": 3, "content": "Test", "qualifier_translated": "says", "qualifier": "says", ...}, ...]

/API/UserSearch/search

Returns 10 users that match query, users are sorted by karma.
Required parameters:
api_key: Your Plurk API key.
query: The query after users.
Optional parameters:
offset: Page offset, like 10, 20, 30 etc.
Successful return:
A JSON list of plurks that the user have permissions to see: [{"id": 3, "content": "Test", "qualifier_translated": "says", "qualifier": "says", ...}, ...]

Emoticons

/API/Emoticons/get

Emoticons are a big part of Plurk since they make it easy to express feelings. Check out current Plurk emoticons. This call returns a JSON object that looks like:

{"karma": {"0": [[":-))", "http:\/\/statics.plurk.com\/XXX.gif"], ...], ...},
"recuited": {"10": [["(bigeyes)", "http:\/\/statics.plurk.com\/XXX.gif"], ...], ...} }

emoticons["karma"][25] denotes that the user has to have karma over 25 to use these emoticons. emoticons["recuited"][10] means that the user has to have user.recuited >= 10 to use these emoticons. It's important to check for these things on the client as well, since the emoticon levels are checked in the models.

Blocks

/API/Blocks/get requires login

Required parameters:
api_key: Your Plurk API key.
Optional parameters:
offset: What page should be shown, e.g. 0, 10, 20.
Successful return:
A JSON list of users that are blocked by the current user, e.g. {"total": 12, "users": {"display_name": "amix3", "gender": 0, "nick_name": "amix", "has_profile_image": 1, "id": 1, "avatar": null}, ...]}

/API/Blocks/block requires login

Required parameters:
api_key: Your Plurk API key.
user_id: The id of the user that should be blocked.
Successful return:
{"success_text": "ok"}

/API/Blocks/unblock requires login

Required parameters:
api_key: Your Plurk API key.
user_id: The id of the user that should be unblocked.
Successful return:
{"success_text": "ok"}

Cliques

/API/Cliques/getCliques requires login

Required parameters:
api_key: Your Plurk API key.
Successful return:
Returns a JSON list of users current cliques, e.g. ["Homies", "Coders", ...]

/API/Cliques/getClique requires login

Required parameters:
api_key: Your Plurk API key.
clique_name: The name of the new clique
Successful return:
Returns the users in the clique, e.g. [{"display_name": "amix3", "gender": 0, "nick_name": "amix", "has_profile_image": 1, "id": 1, "avatar": null}, ...]

/API/Cliques/createClique requires login

Required parameters:
api_key: Your Plurk API key.
clique_name: The name of the new clique
Successful return:
{"success_text": "ok"}

/API/Cliques/renameClique requires login

Required parameters:
api_key: Your Plurk API key.
clique_name: The name of the clique to rename
new_name: The name of the new clique
Successful return:
{"success_text": "ok"}

/API/Cliques/add requires login

Required parameters:
api_key: Your Plurk API key.
clique_name: The name of the clique
user_id: The user to add to the clique
Successful return:
{"success_text": "ok"}
Error returns:
HTTP 400 BAD REQUEST with {"error_text": "Clique not created"} as body

/API/Cliques/remove requires login

Required parameters:
api_key: Your Plurk API key.
clique_name: The name of the clique
user_id: The user to remove from the clique
Successful return:
{"success_text": "ok"}
Error returns:
HTTP 400 BAD REQUEST with {"error_text": "Clique not created"} as body

PlurkTop

/API/PlurkTop/getCollections

Required parameters:
api_key: Your Plurk API key.
Successful return:
Returns a JSON list of PlurkTop collections, e.g. [ [u'Taiwan', u'cn,tr_ch,en', u'\u53f0\u7063'], [u'English', u'en', u'English'], [u'Philippines', u'en,en_fo,ta_fp', u'Pilipinas'], ... [u'Educators', u'en,es', u'Educators']] ]

/API/PlurkTop/getDefaultCollection

Required parameters:
api_key: Your Plurk API key.
Successful return:
Returns a JSON string of default name of collection for current user, e.g. 'English'

/API/PlurkTop/getPlurks

Required parameters:
api_key: Your Plurk API key.
Optional parameters:
offset: offset of Plurks in PlurkTop, should be an float, e.g. 0.99.
sorting: the way to sort plurks in PlurkTop, can be "hot" for sorting by popularity or "new" for posted time.
Successful return:
Returns a JSON object of plurks and their users. The offset in result is the offset value of last plurk in the result. e.g. {"offset": 0.8, "plurks": [{"plurk_id": 3, "content": "Test", "qualifier_translated": "says", "qualifier": "says", "lang": "en" ...}, ...], "plurk_users": {"3": {"id": 3, "nick_name": "alvin", ...}}