API documentation

Kundo's API makes it possible to fetch all the data in your forum, and integrate it into your application or website.

All examples throughout this page are clickable, to help you explore the API. By specifying your slug below you can adapt all examples to your forum.

https://kundo.se/org/Update examples

That's not a valid slug. Please use a slug from an existing forum.

Table of contents

Basics

• Glossary
• Available return formats
• Response codes
• Best practices

Fetching data

• Dialogs in a forum
• Dialogs filtered by topic
• Popular dialogs
• A given dialog
• Comments for a given dialog
• Dialogs that match a search query
• Forum properties
• List of all editors

Working with tags

• Calls that require an API key
• Dialogs with a given tag(requires API key)
• Tags for a given dialog(requires API key)
• List of tags(requires API key)
• Search within a tag(requires API key)
• Using both topics and tags(requires API key)

Pagination and Sorting

• Pagination of results
• Sorting results

Statistics

• Register page views
• Statistics and popularity

Post data to the API

• Dialogs to a forum
• Comments to a dialog
• Subscribing to a dialog
• Report dialog as inappropriate
• Report comment as inappropriate
• Adding custom fields to a dialog
• Dialogs/Comments as an editor(requires API key)
• Auto archiving a dialog
• Uploading files

Methods of posting

• Post using JSON
• Post using a form

Glossary

slugA string that uniquely identifies your forum. It's part of the URL for your forum, so if your forum is located on https://kundo.se/org/your-forum/, then your-forum is your slug. Keep this in mind as it's used in all API calls.forumOne 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.dialogThe 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, praise, or a custom category.

Return format

The API uses JSON. A callback can be also specified, making JSONP possible. For example:

https://kundo.se/api/your-forum-slug.json?callback=your_own_methodAll public dialogs. "your_own_method" is the javascript call to wrap around the response.

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.1 400 BAD REQUEST
        Content-Type: text/plain
        ...

        BLOCKED
      `The specified ip address or user email is blocked by Kundo.`
        HTTP/1.1 400 BAD REQUEST
        Content-Type: text/plain
        ...

        BLOCKED EMAIL DOMAIN
      `The specified email's domain is blocked by Kundo.`
        HTTP/1.0 409 CONFLICT
        Content-Type: text/plain
        ...

        Conflict/Duplicate
      `HTTP response if the exact same dialog (title and text) already exists.`
        HTTP/1.1 201 CREATED
        Content-Type: text/plain
        ...

        SPAM
      `The dialog or comment was created but marked as spam and will not be visible.

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

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

        CREATED
      `The dialog or comment was created without problems.

Protocol

Use HTTPS, not HTTP

All API requests should be made using HTTPS. Using HTTP might work, but we reserve the right to redirect all HTTP requests to HTTPS at any time. Since this might break POST requests or requests from clients that don't follow redirects, the use of HTTP is not recommended.

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 can also benefit from caching, further improving the user experience. With server side parsing you don't have to worry about how search engines see your site - everthing just works.

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 the autocomplete functionality and 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.

Prepare for new data occuring

For compatibility reasons we never remove properties from the API without first sending out a message to the API mailing list and making sure no one uses that property. But we do reverve the right to add new properties to each of the calls below. To prepare for this, make sure your parsers can handle previously unseen data when we add a new feature to Kundo.

Fetching data

https://kundo.se/api/your-forum-slug.jsonAll dialogs in your forum. Limited to 50 dialogs per request - see pagination.https://kundo.se/api/your-forum-slug/questions.jsonAll dialogs with topic "questions". Available topics: questions, problems, suggestions, and praise, or in their abbreviated forms: Q, P, S, and B (Why B for praise? Because "P" was taken :).You may also have custom categories set up for your account. Use the category slug as the topic for this call.https://kundo.se/api/your-forum-slug/questions,problems.jsonIt's also possible to select dialogs from multiple topics. Just send in a comma separated lists of the topics you want.

You can also fetch just the most popular dialogs, including just the most popular dialogs in a specific category. Popularity is also available as a sorting parameter to all dialog queries.

https://kundo.se/api/popular/your-forum-slug.jsonThe most popular dialogs at the moment.https://kundo.se/api/popular/your-forum-slug/questions.jsonThe most popular dialogs in the questions category.

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.

https://kundo.se/api/dialog/your-forum-slug/1.jsonAll information we have on the dialog with id=1. Take statistics into concern - see register page views.

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

https://kundo.se/api/comment/your-forum-slug/1.jsonAll comments for the dialog with id=1. Limited to 50 comments per request - see pagination.https://kundo.se/api/search/your-forum-slug/test.jsonSearch through all the dialogs that contain "test". Limited to 10 dialogs per query. Make sure you clean your users search input from newlines and other invalid URL formating. Only the first 50 terms and a total query length of 500 will be considered in the search.https://kundo.se/api/search/your-forum-slug/test.json?livesearch=1If you are building an autocomplete-style search you might want to add livesearch=1 parameter to your searches. This ignores "quoted phrases" and returns a shorter text snippet length for use in a dropdown. We use this for Kundo's own autocomplete feature on our site.https://kundo.se/api/search/your-forum-slug/test.json?snippetlength=200You can control the length of the text snippet returned from the API. The maximum length is 300.https://kundo.se/api/search/your-forum-slug/test.json?category_slug=questionsSearch through all the dialogs that contain "test" in the category "questions". Limited to 10 dialogs per query.https://kundo.se/api/search/your-forum-slug/test.json?category_slug=questionsSearch through all the dialogs that contain "test" in the category "questions". Limited to 10 dialogs per query.https://kundo.se/api/search/your-forum-slug/test.json?category_slug=questions,problemsSearch through all the dialogs that contain "test" in the categories "questions" or "problems". Limited to 10 dialogs per query.

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

https://kundo.se/api/properties/your-forum-slug.jsonConfigurable properties of the forum.

Properties returned:

| name | The forum name | | formal_name | Formal company name. May be different from the forum name | | intro_message | A short description of the forum | | status_message | Information message displayed when the feedback form is opened
NOTE: For compatibility with old API clients, this property is called
"status_message", but it's configured with the "Information message" setting in your forum settings. | | status_url | URL where user can read more about the information message | | popup_header | Header text for the popup window | | default_topic | The topic that should be selected by default | | enabled_topic | List of all available topics | | language | The language setting of the forum |

https://kundo.se/api/editorlist/your-forum-slug.jsonList of all public editors in the forum with name, title and picture.

Calls that require an API key

It is also possible to fetch data that is normally only available to logged in editors. To do this you need an API key, contact us to get one.

To use your API key, simply add it as an URL query parameter called key. Using a bad API key will return error code 401 "Authorization Required".

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

When making requests with an API key the result might contain data only visible for authorized users, for example internal tags and dialogs that are archived. So make sure you clean the result on your side before showing it to the end user.

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.

https://kundo.se/api/tag/your-forum-slug/exempel.json?key=YOUR_API_KEYGet dialogs tagged with "example".https://kundo.se/api/tag/your-forum-slug/tag1,tag2.json?key=YOUR_API_KEYGet dialogs tagged with both "tag1" AND "tag2".https://kundo.se/api/tag/your-forum-slug/tag1,tag2.json?tag_mode=OR&key=YOUR_API_KEYGet dialogs tagged with both "tag1" OR "tag2".https://kundo.se/api/dialog/your-forum-slug/1.json?key=YOUR_API_KEYBy specifying an API key to the detail view you get the tags included in the response.https://kundo.se/api/taglist/your-forum-slug.json?key=YOUR_API_KEYGet all tags in a given forum. Included in the response are the number of dialogs tagged with each tag.https://kundo.se/api/search/your-forum-slug/test.json?key=YOUR_API_KEY&tags=tag1Search for dialogs including the word "test" and are tagged with "tag1". Note! If you provide the API-key the result will contain archived dialogs.https://kundo.se/api/search/your-forum-slug/test.json?key=YOUR_API_KEY&tags=tag1,tag2Search for dialogs including the word "test" and are tagged with both "tag1" and "tag2". https://kundo.se/api/search/your-forum-slug/test.json?tag_mode=AND&key=YOUR_API_KEY&tags=tag1,tag2Same as the default tags search. Search for dialogs including the word "test" and are tagged with both "tag1" and "tag2". https://kundo.se/api/search/your-forum-slug/test.json?tag_mode=OR&key=YOUR_API_KEY&tags=tag1,tag2Search for dialogs including the word "test" and are tagged with "tag1" or "tag2". https://kundo.se/api/your-forum-slug/questions.json?key=YOUR_API_KEY&tags=tag1All dialogs with topic "questions" and the tag "tag1".

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.

https://kundo.se/api/your-forum-slug.json?start=50Fetch the next 50 dialogs. When no more dialogs are available, an empty response is returned.https://kundo.se/api/your-forum-slug.json?limit=10Fetch 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:

https://kundo.se/api/your-forum-slug/questions.json?sort=num_commentsAll questions, sorted by number of comments. Ascending.

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

https://kundo.se/api/your-forum-slug/questions.json?sort=-num_commentsAll questions, sorted by number of comments. Descending.

To sort with multiple parameters, separate them with a comma. This is Useful if the values of the first sorting key is not always unique.

https://kundo.se/api/your-forum-slug/questions.json?sort=-pinned_at,-pub_dateAll questions, displaying the pinned questions first, and then the non-pinned questions sorted by publish date Descending

Available sort parameters are:

| pub_date | The date and time when the dialog was posted | | pinned_at | The date and time when the dialog was pinned | | popularity | The dialog popularity (based on comments and time decay) | | last_activity | The date and time when the dialog was last commented on. If there are no comments, the date the dialog was published. | | num_comments | The number of comments | | title | Title of dialog | | text | Dialog body text | | topic | The topic of the dialog |

Register page views

Fetching data through the API does not count as page views in the forums vistors statistics. So to keep statistics and popularity ranking accurate you must trigger a page view explicitly.

https://kundo.se/api/analytics/tracker/your-forum-slug/1.jsonRegister a page view on dialog with id=1. Returns no data, just the HTTP status code.

To make it easier to trigger page views this call is also available as a javascript url. With the javascript url you can trigger a page view asynchronously with a script tag on the actual page.

<script type="text/javascript">     (function() {         function async_load(){             var s = document.createElement('script');             s.type = 'text/javascript';             s.async = true;             s.src = 'https://kundo.se/api/analytics/tracker/your-forum-slug/1.js';             var x = document.getElementsByTagName('script')[0];             x.parentNode.insertBefore(s, x);         }         if (window.attachEvent)             window.attachEvent('onload', async_load);         else             window.addEventListener('load', async_load, false);       })(); </script>Example of lazy loaded script for triggering a page view on dialog with id=1.

Statistics and popularity

The number of page views is used to calculate the popularity of posts in the forum. But if you register page views when the users click in lists of most popular posts you will just re-enforce their popularity, and the same posts will always be the most popular.

To avoid this scenario, you can trigger a page view that is excluded from popularity calculations and used for statistics only. This is done by adding a parameter to the request:

https://kundo.se/api/analytics/tracker/your-forum-slug/1.json?src=popularRegister a page view on dialog with id=1, without increasing its popularity rankning. Returns no data, just the HTTP status code.

Furthermore, visits from a particular user will only be added to the popularity count once in a certain time period. The client's IP address is used to roughly distinguish unique users for this purpose. If you have specified an X-Forwarded-For header in your call this value will be used, see the best practices section.

If you want to specify your own unique identifier rather than the user's IP address, you can pass the uid parameter like this:

https://kundo.se/api/analytics/tracker/your-forum-slug/1.json?uid=YOUR_UNIQUE_USER_IDRegister a page view on dialog with id=1, sending in your own unique user identifier.

Post data using the API

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

https://kundo.se/api/your-forum-slugPost new dialogs to your forum. If the dialog was marked as spam this wil be indicated in the response body with the word SPAM. Contact us to learn more about how to unspam content.https://kundo.se/api/comment/your-forum-slug/1Post comments to a given dialog. If the dialog was marked as spam this wil be indicated in the response body with the word SPAM. Contact us to learn more about how to unspam content.https://kundo.se/api/subscribe/your-forum-slug/1Subscribes the user to a given dialog. The user will be notified by e-mail on new comments.https://kundo.se/api/report-dialog/your-forum-slug/1Report a dialog as inappropriatehttps://kundo.se/api/report-comment/your-forum-slug/1Report a comment as inappropriate

Adding custom fields 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.

The following types are avaialable

| Type | Description | Options | | --- | --- | --- | | Text | A text string | Optional: max number of characters the string is allowed to be | | Integer | An integer value | Optional: max value for the number | | Coordinate | A string describing a coordinates for a position | None | | Choice | A string, limited to a list of choices | Required: Values allowed in the custom field. The values
must be strings. |

Custom fields can only be added if you have a Professional account at Kundo. To set up custom fields 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 custom fields, customer\_id and customer\_level, added.

The custom fields are then available in the dialog json under the keys extras, custom_fields_data. For example, the dialog above would look like:

` Content-Type:application/json

        {
            ...
            "extras": {
                "archived": false,
                "custom_fields_data": {
                    "customer_id": 1234,
                    "customer_level": "Gold"
                },
                "metadata": {
                    "customer_id": 1234,
                    "customer_level": "Gold"
                }
            },
            ...
        },
      `Partial response from fetching a dialog with custom fields

As shown in the above example, the same data is also returned in metadata. This is for historical reasons and is deprecated. New code should use custom_fields_data

Posting as editor

Posting a dialog or comment as an editor requires an API key, that an editor with that email exists and that the flag "written_by_editor" set to "true". For example this could look like:

` Content-Type:application/json

          {
              ...,
              "useremail": "name@example.com",
              "written_by_editor": "true",
          }
        `Partial example of posting an dialog or comment as editor.

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.

In Kundo this is done in two stesp

1. The file is uploaded to Kundo and an id is returned
2. The dialog och comment is created through the API with a reference to the files uploaded

https://kundo.se/api/file/your-forum-slug This is the call used to upload the 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”. {     "status": "CREATED",     "file_url": "http://kundo.se/attached-file/yourfile.txt",     "id": 123 } The response to this call includes the URL to the file and the file id

To actually attach the file to a comment or dialog, include a "attachment_id" attribute in the post to create the comment or dialog. This should be an array of attachment ids from the result from the above call.

` Content-Type:application/json

        {
            "name": "Name",
            "useremail": "name@example.com",
            "topic": "Q",
            "title": "Post title",
            "text": "Post contents...",
            "attachment_ids": [123],
        }
      `

Example call to create a dialog with attached file

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](#dialogs_by_tag).`
        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",
            "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>' https://kundo.se/api/kundoPost a new dialog using cURL.

Send data using an HTML form

The API also support posting data through a HTML form directly.

`

        Type of question:                      Question             Problem             Suggestion             Praise              

Title:

Your name:

Your e-mail:

Send

            <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:

https://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.

iframe