Table of contents

Glossary

slug

A string that uniquely identifies your forum. It's part of the URL for your forum, so if your forum is located on http://kundo.se/org/your-forum/, then your-forum is your slug. Keep this in mind as it's used in all API calls.

forum

One specific discussion forum. You can create several forums connected to one account, and each forum will behave as a independent entity. Each forum has its own slug.

dialog

The posting that started a new thread in the forum. Other users add comments to a dialog, but the dialog object in itself does not include the comments. The API call to fetch the comments is available in the comments_uri property on the dialog. A dialog always has a topic, a category that denotes what kind of dialog they posted. It can be either a question, a problem, a suggestion, or praise.

All examples below are clickable, to make it easier to explore the API. You can also adapt the examples to your own forum by simply inputting your slug (see explanation above) in the below form.

Available return formats

By specifying different file endings in your calls, the API can be made to return either JSON or XML. When using JSON, a callback can be specified, making JSONP possible.

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

All dialogs, in JSON format. Since this is the recommended format, all other examples use JSON.

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

All dialogs, in JSONP format. "your_own_method" is the javascript call to wrap around the response.

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

All dialogs, in XML format.

Response codes

Errors will be reported with the corresponding HTTP status code.

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

Bad Request

JSON data posted was incorrectly formatted.

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

{
    "useremail": [
        "Du m\u00e5ste fylla i din e-postadress."
    ]
}

Required data is missing. The key indicates which field is incorrect, and the error message can be shown to the user to help them correct their error.

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

Conflict/Duplicate

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

If everything went well a 201 CREATED response will be returned:

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

Created

The dialog, comment, or vote was created without problems.

Best practices

Prefer server side over client side

When working with the Kundo API you have the choice of accessing it from your server side code or via Javascript on the client side.

For static or semi static information, such as forum meta data, lists of dialogs, dialog pages and comment listings we strongly recommend using server side code. Client side implementations using Javascript to fetch large amounts of data tend to make the page load slowly or flicker.

Fetching and parsing data on the server side also has the benefits of faster load time through caching, further improving the user experience. With server side parsing your SEO is also improved - Google and other search engines will in most cases not be able to crawl information presented using Javascript.

If you are doing API calls that require an API key these must of course be done from your server side code to avoid publishing your API key.

For very dynamic information however, we do recommend that you use Javascript. Examples of this include autocomplete functionality and regular search results displayed on a separate page.

Use the client IP address

The IP address of the user posting a dialog or comment is used by Kundo in a number of ways, most notably to protect your forum from spam and other abuse. When posting content to Kundo from your server side code the IP address sent by your server is used. We strongly recommend that you post data with the IP address of the user rather than your server. This can be done by setting the X-Forwarded-For header on your request with the IP address of the user.

Fetching data

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

All dialogs in your forum. Limited to 50 dialogs per request - see pagination.

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

All dialogs with topic "question". Available topics: question, problem, suggestion, and praise, or in their abbreviated forms: Q, P, S, and B (Why B for praise? Because "P" was taken :).

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

It's also possible to select dialogs from multiple topics. Just send in a comma separated lists of the topics you want.

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

The most popular questions at the moment. Popularity is also available as a sorting parameter to all dialog queries.

Each element in an API response contains a property called "uri", with an URL that can be used to access details about that object. NOTE: We've tried hard to include as much data as possible in the listing calls, so you might not need to use the details view.

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

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

Using the "comments_uri" property you can fetch comments for a given dialog.

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

All comments for the dialog with id=1. Limited to 50 comments per request - see pagination.

You can also search for dialogs that contain one or more keywords. The search matches strings both in the title, body text, and comments. The title and body text contains a span with class "highlighted" where our search engine would highlight the matched query words.

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

Search through all the dialogs that contain "test". Limited to 10 dialogs per query.

When building a customized mirror of the forum start page, it can be helpful to be able the fetch the user customizable settings for a forum instead of hardcoding them.

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

Common user configurable properties of the forum.

Properties returned:

Calls that require an API key

It is also possible to fetch data that is normally only available to logged in editors. To fetch this kind of data do you need an API key, available to customers with an Medium, Large or Custom account. Contact us if you need an API key. A bad API key returns error code 401 "Authorization Required".

NOTE: Don't send the API key with Javascript, since that would reveal the key to your users.

Working with tags

Tags are great for building new views into your forum. You could for instance tag your dialogs with a product specific tag, and use that one to show a list dialogs on your product page. Tags are only settable by editors or when posting dialogs to the API with an API key, and can be made either private (default) or public. If they are private you need a API key to fetch them in the API.

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

Get dialogs tagged with "example".

http://kundo.se/api/tag/kundo/tag1,tag2.json?key=YOUR_API_KEY

Get dialogs tagged with both "tag1" and "tag2".

http://kundo.se/api/dialog/kundo/1.json?key=YOUR_API_KEY

By specifying an API key to the detail view you get the tags included in the response.

http://kundo.se/api/taglist/kundo.json?key=YOUR_API_KEY

Get all tags in a given forum. Included in the response are the number of dialogs tagged with each tag.

http://kundo.se/api/search/kundo/test.json?key=YOUR_API_KEY&tags=tag1

Search for dialogs including the word "test" and are tagged with "tag1".

http://kundo.se/api/search/kundo/test.json?key=YOUR_API_KEY&tags=tag1,tag2

Search for dialogs including the word "test" and are tagged with either "tag1" and "tag2".

Pagination

Pagination can be controlled through the start and limit parameters. The start parameter sets the first index to fetch (NOTE: zero indexed, default: 0), the limit parameter sets the number of results to return (default: 50). These parameters works with all kinds of requests, including search.

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

Fetch the next 50 dialogs. When no more dialogs are available, an empty response is returned.

http://kundo.se/api/kundo.json?limit=10

Fetch a maximum of 10 results.

All queries returning a list of dialogs also has a HTTP header called X-TotalResults that contains the total number of dialogs that are available, no matter what the limit and start parameters are set to. This makes it possible to calculate the number of page links to show after your partial list of results.

Sorting

By default, dialogs and comments are sorted in reverse chronological order, i.e. the most recent first. By specifying the sort parameter you can select a different sorting order:

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

All questions, sorted by number of comments. Ascending.

To reverse the sort order, add a minus sign ("-") in front of your sort parameter:

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

All questions, sorted by number of comments. Descending.

Available sort parameters are:

Post data using the API

To enable advanced customizations, it is also possible to post dialogs, comments and votes using the API. Posts can be done both using JSON and a HTML form, but the URL:s used are the same.

http://kundo.se/api/kundo

Post new dialogs to your forum.

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

Post comments to a given dialog.

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

Post votes to a given dialog.

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

Report a dialog as inappropriate

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

Report a comment as inappropriate

Adding metadata to a dialog

It can be useful to append other data to a dialog, e.g. customer id or social security number, that is only available to logged in editors. Such data can be added as regular parameters to a dialog post. However, before doing so Kundo must set up the accepted parameters for you. Each parameter has a type (integer or text) and a max length or max value. Metadata can only be added if you have an Medium account at Kundo. To set up accepted metadata parameters for your account, please contact us.

Once parameters are set up, just add them to your regular dialog post:

Content-Type:application/json

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

Post a new dialog using JSON with two metadata fields, customer_id and customer_level, added.

Auto archiving a dialog

Kundo support the concept of “archiving” dialogs. This means that the dialog is still available on Kundo for editors and anyone with the URL to the post. However, the dialog will not show up in lists or in search for regular users. This is a good way to keep personal posts away from the public forum.

If you for some reason want to archive a post immediately after it's posted you can add the "archived" parameter to your post. Since archiving is only available to editors the call requires an API key if this parameter is included.

Content-Type:application/json

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

Post a new dialog that will be immediately archived.

Uploading files

To highlight a problem or add more details to a reply, users sometimes want to add images, PDF files and other types of documents to a dialog or comment. Kundo handles such attachments in a loosely coupled way: Each link found in the text of a dialog or comment will be replaced by a corresponding embed code for that particular file type.

Files that are uploaded to Kundo are handled in the same manner: Once the file is uploaded you simply add the link to that file info the text of your dialog or comment before you post it to Kundo.

http://kundo.se/api/file/kundo?key=YOUR_API_KEY

A successful call returns the URL of the uploaded file. The content type of your post needs to be “multipart/form-data” and the attached file should be added to a POST variable named “file”.

This call requires an API key.

Send data as JSON

All posts require structured data, and JSON works well for that purpose. To specify that you are using JSON you need to set the "Content-Type" header to "application/json".

Content-Type:application/json

{
    "name": "Name",
    "useremail": "name@example.com",
    "topic": "Q",
    "title": "Post title",
    "text": "Post contents..."
    "tags": "tag one, tag two, tag three"
}

Post a new dialog using JSON. If you add tags to the dialog as in the example above you need to supply an API key in the URL. See working with tags.

Content-Type:application/json

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

Post a new comment using JSON

Content-Type:application/json

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

Post a new vote using JSON

Content-Type:application/json

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

Report a dialog or comment using JSON

To use cURL to test the API, use these command flags:

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

Post a new dialog using cURL.

Send data using an HTML form

The API also support posting data through a HTML form 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>

Post data using an HTML form.

The two last fields, error_url and success_url, are 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 dialog in the forum.
• 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-dialogadress.
  These query parameters can be used to generate a new form on the server side, and display the errors to the user
• If any of error_url and success_url, are incorrect, an error message will be shown.