Using Qaiku API

Using Qaiku API

Qaiku's API is based on the Twitter REST API so that clients can support both services with minimal overhead. API issues and ideas can be discussed on the #Qaiku-api channel.

Authentication

All Qaiku API requests must be authenticated. Qaiku's API commands can use three authentication methods:

  • Current Qaiku session: if you have a session open with Qaiku you can call the methods via your browser without additional authentication
  • HTTP Basic authentication: provide your Qaiku username and password via normal HTTP Basic authentication
  • API key: send your Qaiku API key as apikey HTTP GET parameter in the request

If authentication fails the API methods will return a HTTP error.

Posting new messages

New Qaiku messages and comments can be posted using the statuses/update method. It comes in two variants, both which must be called via HTTP POST:

The required POST parameters used for posting are following:

  • status: the actual status message. The message may be Markdown-formatted. If the message is not marked as being a reply using in_reply_to_status_id, then contents must be limited to 140 characters

In addition, following optional parameters may be used:

  • lang: language of the message, using ISO 639-1 two letter language codes (en, fi, etc)
  • in_reply_to_status_id: id of a status message this status is a comment to. If this parameter is used, the message status may exceed 140 characters
  • data: additional machine-readable Qaiku Data to be associated with the message. Qaiku Data is limited to 256 characters
  • external_url: external URL to link the item to
  • channel: name of channel to post the message to instead of user's stream

If successful, this call will return the created status message in the requested format (JSON or XML). Otherwise, a HTTP error will be returned.

Note: If the message begins with #channelname, then the message will be sent to that channel instead of user's Qaiku stream.

Reading a message

Individual Qaiku messages and comments can be read using the statuses/show method, which must be called via a HTTP GET, replacing ID with an actual message ID:

If successful, this call will return the requested status message in JSON format. Otherwise, a HTTP error will be returned.

Removing a message

Qaiku messages and comments can be removed using the statuses/destroy method, which must be called via a HTTP POST or HTTP DELETE, replacing ID with an actual message ID:

If successful, this call will return the removed status message in JSON format. Otherwise, a HTTP error will be returned.

Reading comments of a message

Comments to individual Qaiku messages can be read using the statuses/replies method, which must be called via a HTTP GET, replacing ID with an actual message ID:

When requesting the comments, some parameters may be used to control the results:

  • since: limit the stream to comments posted since a given time. The limitation must be given as ISO 8601 datetime
  • page: get results from given page number when requesting older Qaikus
  • lang: get results only in a given language, using ISO 639-1 two letter language codes (en, fi, etc)
  • external_url: in case of byurl.json you can get comments to an item linked to the given URL

If successful, this call will return list of comments to the requested status message in JSON format. Otherwise, a HTTP error will be returned.

Reading the Stream

Stream contains new Qaikus and comments from user's contacts and channels. The statuses/friends_timeline method must be called via HTTP GET:

Each request will be limited to 20 results. Older results can be requested through paging.

When requesting the stream, some parameters may be used to control the results:

  • user_id: get the stream of a given user identifier instead of user who authenticates the request. Returns only the Qaikus the current user is allowed to access
  • screen_name: get the stream of a given username instead of user who authenticates the request. Returns only the Qaikus the current user is allowed to access
  • since: limit the stream to messages posted since a given time. The limitation must be given as ISO 8601 datetime
  • page: get results from given page number when requesting older Qaikus
  • lang: get results only in a given language, using ISO 639-1 two letter language codes (en, fi, etc)

Response is a list of messages in JSON message list format, see below.

Reading user's Qaikus

Timeline contains new Qaikus and comments from a single user. The statuses/user_timeline method must be called via HTTP GET:

Each request will be limited to 20 results. Older results can be requested through paging.

When requesting the timeline, some parameters may be used to control the results:

  • user_id: get the timeline of a given user identifier instead of user who authenticates the request. Returns only the Qaikus the current user is allowed to access
  • screen_name: get the timeline of a given username instead of user who authenticates the request. Returns only the Qaikus the current user is allowed to access
  • since: limit the timeline to messages posted since a given time. The limitation must be given as ISO 8601 datetime
  • page: get results from given page number when requesting older Qaikus
  • lang: get results only in a given language, using ISO 639-1 two letter language codes (en, fi, etc)

Response is a list of messages in JSON message list format, see below.

Reading channel's Qaikus

Timeline contains new Qaikus and comments to a channel. The statuses/channel_timeline method must be called via HTTP GET, replacing CHANNEL with the name of a channel:

Each request will be limited to 20 results. Older results can be requested through paging.

When requesting the timeline, some parameters may be used to control the results:

  • since: limit the timeline to messages posted since a given time. The limitation must be given as ISO 8601 datetime
  • page: get results from given page number when requesting older Qaikus
  • lang: get results only in a given language, using ISO 639-1 two letter language codes (en, fi, etc)

Response is a list of messages in JSON message list format, see below.

Reading public Qaikus

Timeline contains new Qaikus and comments that the user can read. The statuses/public_timeline method must be called via HTTP GET:

Each request will be limited to 20 results. Older results can be requested through paging.

When requesting the timeline, some parameters may be used to control the results:

  • since: limit the timeline to messages posted since a given time. The limitation must be given as ISO 8601 datetime
  • page: get results from given page number when requesting older Qaikus
  • lang: get results only in a given language, using ISO 639-1 two letter language codes (en, fi, etc)

Response is a list of messages in JSON message list format, see below.

Reading Qaikus where user is mentioned

Timeline contains new Qaikus and comments that the user can read and the user is mentioned in (same as Qaiku Radar). The statuses/mentions method must be called via HTTP GET:

Each request will be limited to 20 results. Older results can be requested through paging.

When requesting the timeline, some parameters may be used to control the results:

  • since: limit the timeline to messages posted since a given time. The limitation must be given as ISO 8601 datetime
  • page: get results from given page number when requesting older Qaikus
  • lang: get results only in a given language, using ISO 639-1 two letter language codes (en, fi, etc)

Response is a list of messages in JSON message list format, see below.

Listing friends and followers

There are methods for listing friends (users the user follows) and followers of a given user. The statuses/friends.json and statuses/followers.json methods must be called via HTTP GET:

When requesting user list, some parameters may be used to control the results:

  • user_id: get the contacts of user identifier instead of user who authenticates the request.
  • screen_name: get the contacts of a given username instead of user who authenticates the request.

Response is a list of users in JSON format.

Searching Qaikus

It is possible to search for Qaikus matching given text. The search.json method must be called via HTTP GET:

Each request will be limited to 20 results. Older results can be requested through paging. Only Qaikus user is allowed to access will be returned.

When requesting the search, the following HTTP GET parameters are required:

  • q: the text to search for. The Query string should be URL-encoded

Some additional parameters may be used to control the results:

  • since: limit the results to messages posted since a given time. The limitation must be given as ISO 8601 datetime
  • page: get results from given page number when requesting older Qaikus
  • lang: get results only in a given language, using ISO 639-1 two letter language codes (en, fi, etc)

Response is a list of messages in JSON message list format, see below.

JSON message list format

Message lists are formatted in the following way:

[
    {
        "created_at":"Tue Jun 02 09:36:54 +0000 2009",
        "id":"1de4f58e854cb924f5811de9272331f2b4e02ce02ce",
        "text":"@teroheiskanen we first want to prepare things a bit :-)",
        "lang":"en",
        "source":"Qaiku",
        "data":"",
        "truncated":false,
        "in_reply_to_status_id":"1de4f5127e1a9a44f5111dea79f31741b98a25aa25a",
        "in_reply_to_user_id":"1de04e7a425656e04e711de8b8b03b7a324e879e879",
        "favorited":false,
        "user":
        {
            "id":"1de04e7a425656e04e711de8b8b03b7a324e879e879",
            "name":"Henri Bergius",
            "screen_name":
            "bergie",
            "location":"Helsinki, Finland",
            "description":"",
            "profile_image_url":"http:\/\/static.qaiku.com\/blobs\/1\/D\/1de059f85d5d784-059f-11de-8bc6-552692129e8f\/smallsquare.jpeg",
            "url":"http:\/\/www.qaiku.com\/home\/bergie\/",
            "protected":false,
            "followers_count":93
        }
    },
    {
        "created_at":"Tue Jun 02 08:41:24 +0000 2009",
        "id":"1de4f5127e1a9a44f5111dea79f31741b98a25aa25a",
        "text":"discussing future plans for Qaiku",
        "lang":"en",
        "source":"Qaiku",
        "data":"$work development $hours 3",
        "external_url":"http:\/\/bergie.iki.fi\/blog\/we-re_joining_the_qaiku_project\/",
        "truncated":false,
        "in_reply_to_status_id":"",
        "in_reply_to_user_id":"",
        "favorited":false,
        "user":
        {
            "id":"1de04e7a425656e04e711de8b8b03b7a324e879e879",
            "name":"Henri Bergius",
            "screen_name":"bergie",
            "location":"Helsinki, Finland",
            "description":"",
            "profile_image_url":"http:\/\/static.qaiku.com\/blobs\/1\/D\/1de059f85d5d784-059f-11de-8bc6-552692129e8f\/smallsquare.jpeg",
            "url":"http:\/\/www.qaiku.com\/home\/bergie\/",
            "protected":false,
            "followers_count":93
        }
    },
    ...
]

Qaiku Data

Inspired by the Twitter Data initiative, Qaiku is starting to support machine-readable metadata in Qaiku messages. Unlike Twitter Data, Qaiku Data is stored as its own field alongside the message, in order not to clutter the actual message displayed on website and in Qaiku clients.

Qaiku Data is handled as key-value pairs marked by $key value. Multiple keys and values can be supplied by separating them with space, like in $key1 value1 $key2 value2.

In Qaiku JSON feeds, data is shown in the data field of the message. On website, they're shown in a qaiku:data attribute of the message <div />.

Qaiku data is limited to 256 characters per message.

API usage examples