Kundo API Documentation

Kundo provides an API that makes it possible to fetch and present information on your website or other external system.

The following data is currently available from the Kundo API:

• All topics in a forum
• Topics filtered by questions, problems, suggestions or praise
• Popular feedback
• Details of a given post
• All comments for a given post
• All dialoges with a certain keyword

It is also posible to post to your own forum at Kundo, e.g. if you wish to build your own custom feedback window. Two methods are supported:

• Post using JSON
• Post using an HTML form

Följande övriga metoder finns tillgängliga:

• Get and post private data with an API key
• Getting properties for a forum
• Report posts and comments as inappropriate

In these examples the "Kundo" forum is used. To fetch data from another forum, you need to replace "kundo" in the examples to the corresponding slug for that forum. http://kundo.se/org/slug/ - I.e. http://kundo.se/org/bokus/.

Our API is being developed continuously. If you have requests for new features, please contact us!

Fetch data using the API (All examples below are clickable)

http://kundo.se/api/kundo.json

All topics in your forum (maximum of 50 - see pagination below).

http://kundo.se/api/kundo/question.json

All questions in your forum (maximum 50 - se section about pagination below). You can also fetch problems ("problem"), suggestions ("suggestion") and praise ("praise").

http://kundo.se/api/popular/kundo/question.json

Your most popular questions at the moment (maximum of 50 - see pagination below).

Each API call returns an address (<uri>) that indicate which call is to be done to get more details about a given object.

http://kundo.se/api/dialog/kundo/1.json

All information we have on the post with id=1.

Similarly you can fetch comments on a particular topic.

http://kundo.se/api/comment/kundo/1.json

All comments for the topic with id=1 (maximum of 50 - see pagination below).

You can also search for one or more keywords.

http://kundo.se/api/search/kundo/hello%20world.json

Search through all the topics that contain "hello world". Returns a maximum of 10 posts.

Some information about the forum, such as the status message, greeting message and the forum name may be relevant to get from the API.

http://kundo.se/api/properties/kundo.json

Information about properties of the forum.

Here are the properties you can access:

Available return formats

The Kundo API can return XML, JSON, and JSONP. By customizing the respective calls, XML is returned instead. For example:

http://kundo.se/api/kundo.xml

All topics, in XML format.

http://kundo.se/api/kundo.json

All topics, in JSON format.

http://kundo.se/api/kundo.json?callback=your_own_method

All messages that you received, in JSONP format, where [your_own_method] is the javascript method to invoke.

Pagination

Each call returns a maximum of 50 posts based on the sort parameter you specified (see below). To fetch the next round of posts, add parameter start = 50, start = 100 etc.

http://kundo.se/api/kundo.json?start=50

Fetch next 50 posts

Sorting

By default, topics and comments are sorted in reverse chronological order, i.e. the most recent first. Specify any available parameter to sort by it. For example, you can sort the entries by number of comments:

http://kundo.se/api/kundo/q.json?sort=num_comments

All questions you received, sorted by number of comments. Ascending.

To reverse sort, add a minus sign ("-") in front.

http://kundo.se/api/kundo/q.json?sort=-num_comments

All questions, sorted by number of comments. Descending.

Available search parameters are:

Post data using the API

To enable advanced integrations of the feedback form, it is also posible to post entires, comments and votes using the API.

http://kundo.se/api/kundo

POST URL to add dialogs to your forum.

http://kundo.se/api/comment/kundo/1

URL to post comments to a specific dialogue.

http://kundo.se/api/vote/kundo/1

URL to post votes to a specific dialogue.

Data is sent as JSON with Content-Type application/json, or as a HTTP POST with all required data as form data.

Send data as JSON

Content-Type:application/json

{
    "name": "Name",
    "useremail": "name@example.com",
    "topic": "Q",
    "title": "Post title",
    "text": "Post contents..."
}

Example of posting a dialog using JSON

Content-Type:application/json

{
    "name": "Name",
    "useremail": "name@example.com",
    "text": "My comment goes here..."
}

Example of posting a comment using JSON

Content-Type:application/json

{
    "name": "Name",
    "useremail": "name@example.com",
}

Example of posting a vote using JSON

You may try your call using cURL like this:

curl -i -H 'Content-Type:application/json' -X POST -d '<Your JSON data here>' http://kundo.se/api/kundo

Test posting data to the API using cURL.

Response codes (HTTP)

Any error messages will be reported like this:

HTTP/1.1 400 BAD REQUEST
Content-Type: text/plain
...

Bad Request

HTTP response for incorrectly formated JSON data.

HTTP/1.1 400 BAD REQUEST
Content-Type: application/json
...

{
    "text": [
        "Du m\u00e5ste skriva in en beskrivning."
    ],
    "useremail": [
        "Du m\u00e5ste fylla i din e-postadress."
    ],
    "name": [
        "Du m\u00e5ste fylla i ditt namn."
    ],
    "title": [
        "Du m\u00e5ste skriva en rubrik."
    ]
}

Required data is missing. The key indicates which field is wrong, and the error message explains how.

HTTP/1.0 409 CONFLICT
Content-Type: text/plain
...

Conflict/Duplicate

HTTP response if the exact same post (title and text) already exists.

If everything went OK the following response is given:

HTTP/1.1 201 CREATED
Content-Type: text/plain
...

Created

The post was created without problems.

Send data using an HTML form

The API also support posting form form data directly.

<form action="http://kundo.se/api/kundo" method="POST">
    <p>
        Type of question:
        <select name="topic">
            <option value="Q">Question</option>
            <option value="P">Problem</option>
            <option value="S">Suggestion</option>
            <option value="B">Praise</option>
        </select>
    </p>
    <p>Title: <input name="title"></p>
    <p><textarea name="text"></textarea></p>
    <p>Your name: <input name="name"></p>
    <p>Your e-mail: <input name="useremail"></p>
    <p><button type="submit">Send</button></p>
    
    <input name="error_url" value="<URL to forward errors to>" type="hidden">
    <input name="success_url" value="<URL when successfully posted>" type="hidden">
</form>

Example of posting data using an HTML form.

The two last fields, error_url and success_url, is related to error handling:

• If all fields are correct the request is forwarded to success_url
• If no success_url was given, the request is forwarded directly to the post
• If any field has an error the request is forwarded to error_url and and the error message is added as a GET parameter to that URL. I.e:
  http://example.com/feedback?text=Du+måste+skriva+in+en+beskrivning.&
useremail=Du+måste+fylla+i+din+e-postadress.
• If any of error_url and success_url, are wrong, an error message will be shown.

Get and post private data with an API key

It is also possible to fetch data, that is normaly only available to logged in editors, using the API. To fetch this kind of data do you need an API key, available to customers with an account of the type Integrate or by special agreement. Contact us if you wish to have your own API key.

Retrieve posts with a particular tag

http://kundo.se/api/tag/kundo/exempel.json?key=fakekey123

URL to to get posts tagged with "example" for a given forum. A bad API key returns error code 401 "Authorization Required"

Getting properties for a forum

Some information about the forum, such as the status message, greeting message and the forum name may be relevant to get from the API.

http://kundo.se/api/properties/kundo.json

Properties of the forum

Report posts and comments as inappropriate

http://kundo.se/api/report-dialog/kundo/1

URL to report a post as inappropriate

http://kundo.se/api/report-comment/kundo/1

URL to report a comment as inappropriate

Content-Type:application/json

{
    "name": "Name",
    "useremail": "name@example.com",
    "report_reason": "Report reason goes here..."
}

Example report of a dialog or comment in JSON format

Our API is being developed continuously. If you have requests for new features, please contact us!