Jaconda provides easy access to all your data via an XML and JSON-based, RESTful API.

This documentation describes how to manage Rooms, Members, Uploads and Messages on behalf of the authorized user.
If you only want to send notifications to your rooms, read Jaconda Notifications guide instead.

Requests

All API calls will be made against the domain that your account is accessed from. For instance, if you want to get a list of all rooms for the bigbang account, you should access https://bigbang.jaconda.im/api/v2/rooms.xml. The docs will only show the relative path starting from the first slash.

Jaconda API supports 2 formats: XML and JSON. That means that the URL in each request should be followed by .xml or .json.

Authentication

Every request to Jaconda API must be authenticated.

Jaconda allows three forms of authentication. The preferred method is to use HTTP Basic Authentication with API token as the username, and "X" (or some otherwise bogus text) as the password (only the API token is used). When logged in, your API token can be found on the "My Info" page.
Example:

$ curl -u J4c0nd4_p0w4hub3r4l13s:X https://bigbang.jaconda.im/api/v2/rooms.xml

The second form of authentication is appending a _token parameter to your requests.
Example:

$ curl https://bigbang.jaconda.im/api/v2/rooms.xml?_token=J4c0nd4_p0w4hub3r4l13s

Also Jaconda API supports HTTP Basic Authentication with email and password.
Example:

$ curl -u sheldon@bigbang.caltech.edu:secret https://bigbang.jaconda.im/api/v2/rooms.xml

Parameters

POST and PUT parameters can be transmitted in 3 ways: plain text, xml and json. For xml and json requests, you should specify appropriate Content-Type header. Regardless the format, parameters should be encapsulated in an appropriate array.

Example with plain parameters:

$ curl -u api_token:x -d 'message[text]=Hello+from+api' https://bigbang.jaconda.im/api/v2/rooms/support/messages.xml

Example with xml as a body:

$ curl -u api_token:x -H 'Content-Type: application/xml' -d '<message><text>Hello with xml</text></message>' https://bigbang.jaconda.im/api/v2/rooms/support/messages.xml

Example with json as a body:

$ curl -u api_token:x -H 'Content-Type: application/json' -d '{message: {text: "Hello with json"}}' https://bigbang.jaconda.im/api/v2/rooms/support/messages.xml

Note that responses in above examples will be in xml, because url is followed by .xml

Responses

Success responses

The server will respond with 200 OK response if there is no errors. The response body will contain requested resource or resources.

Failure responses

If request fails, the server will respond with failure code and message. There are several possible failure responses:
400 - the request can't be processed due to invalid format or auth type - supported response formats are XML and JSON, supported authentication methods are HTTP Basic and parameter-based
401 - unauthorized access - ensure that API key is correct
404 - the requested resource cannot be found - ensure that resource ID is correct
422 - the submitted data was invalid - check the corresponding error messages
500 - unexpected errors - submit a bug report at http://help.jaconda.im

The response body for 422 failure will contain description of the error.
The XML response will have a root element "errors" with one or more "error" children, describing each error that occurred.
The JSON response will have array of one or more errors, describing each error that occurred.

Methods

The API supports the following methods to send and receive data.

Rooms

• GET rooms - Retrieves a list of rooms where the authenticated (current) member has access.
• GET room - Shows the room info and it's available users.
• POST room - Creates a new room.
• PUT room - Updates the room info.
• DELETE room - Deletes the room.
• GET room's users - Retrieves a list of users of the room.
• POST room's user - Invites a user to the room.
• DELETE room's user - Kicks a user from the room.
• GET room's uploads - Retrieves a list of files of the room.
• POST room's upload - Uploads a file to the room.

Members

• GET members - Retrieves a list of members.
• GET member - Shows the member info and rooms where they are available.
• POST member - Invites a new member.
• PUT member - Updates the member's info.
• DELETE member - Deletes the member.
• GET member's rooms - Retrieves a list of rooms where the specified member has access.
• GET member's uploads - Retrieves a list of files of the member.

Messages

• GET recent messages - Retrieves a list of recent messages of the room.
• GET messages by date - Retrieves a list of messages of the room on specific date.
• GET messages by search - Searches for the phrase in the room.
• POST message - Says something in the room.

Rate limiting

There is no rate limiting yet, but this may change in the future. Please check the API Changelog for further changes.