Kundo Knowledge API Documentation

Welcome to the Kundo Knowledge API documentation!

This API is a work in progress, so if you have any questions or feedback, please contact us at support@kundo.se.

Note that to start using the API, we must enable it for you, so send us an email and we will get you started.

JSON API

Kundo Knowledge API uses the JSON API format for all requests.

This means that all requests to the API should include the Accept: application/vnd.api+json HTTP header without any modifications, as specified under “Client responsibilities“ in the above link.

Calls that do not provide Accept: application/vnd.api+json will receive a 406 Not Acceptable response.

The api server will reply with Content-Type: application/vnd.api+json for all successful calls.

Data Types

This section lists and explains the different resources that Kundo Knowledge API handles.

Each data type has some attributes it exposes and a list of relationships.

NOTE: Relationships on a resource will only be populated if the related resource is specified as an included type (see “Included Types”).

KnowledgeBase

Attributes

• name - The name of the knowledge base
• host - The hostname at which the knowledge base can be reached (e.g. “kb.kundo.se”)
• organization_name - The name of the organization that owns the knowledge base.

Relations

• categories - All categories belonging to published guides in a knowledge base
• tags - All tags belonging to published guides in a knowledge base
• guides - All published guides in a knowledge base

Guide

Attributes

• title - The title of the Guide
• slug - Used for identifying a guide
• content_html - The actual guide text in HTML format

Relations

• knowledge_base - What knowledge base this guide belongs to
• categories - All categories this guide is placed in
• tags - All tags this guide has been tagged with

Category

Attributes

• name - The name of the category
• slug - Used for identifying a category
• multiple_guides_name - The pluralization of guides in this category
• position - The position for this category in the list of categories in the knowledge base that this category belongs to
• parent_category_id - An optional pointer to a parent category

Relations

• knowledge_base - What knowledge base this category belongs to
• guides - All guides in this category, ordered by the way they should appear
• child_categories - All categories that have this category as their parent category

Tag

Attributes

• name - The name of the tag
• slug - Used for identifying a tag

Relations

• knowledge_base - What knowledge base this tag belongs to
• guides - A list of guides tagged with this tag

Endpoints

Knowledge bases

Fetch information about a knowledge base

• GET https://api.kundo.se/knowledge/v1/:host

  :host is the host of your knowledge base, where it can be accessed on the web (e.g. “kb.kundo.se“)

  A full request using e.g. curl would then be curl -XGET https://api.kundo.se/knowledge/v1/kb.kundo.se

• Returns a JSON API response like this:

    {
      "jsonapi": {
        "version": "1.0"
      },
      "data": {
        "id": "1",
        "type": "knowledge_base",
        "links": {
          "self": "/knowledge/v1/kb.kundo.se"
        },
        "attributes": {
          "organization_name": "Kundo",
          "name": "Kunskapsbanken",
          "host": "kb.kundo.se"
        }
      }
    }

Guides

List guides

• GET /knowledge/v1/kb.kundo.se/guides

• Returns a JSON API response object something like this:

    {
      "jsonapi" : {
         "version" : "1.0"
      },
      "data" : [
         {
            "id" : "500",
            "type" : "guide",
            "links" : {
               "self" : "/knowledge/v1/kb.kundo.se/guides/500"
            },
            "attributes" : {
               "slug" : "komma-igang-med-kundo-mail",
               "title" : "Lägg till ny inkorg i Kundo Mail",
               "content_html": "..."
            },
            "relationships" : {
               "categories" : {},
               "tags" : {},
               "knowledge_base" : {}
            }
         },
         ... <more guide objects>
      ]
    }

Filtering guides

Lists of guides can be filtered by either a category or a tag.

Filtering is done by the filter query parameter, like so:

GET /knowledge/v1/kb.kundo.se/guides?filter[:filter_type]=:filter_value

NOTE: filtering by both category and tag is not supported. If a request specifies both tag and category filters, the API will use the first filter specified.

Given ?filter[tag]=foo&filter[category]=bar, the API will return the same result as if only given ?filter[tag]=foo.

Filtering by tag

Filtering a guide list by tag is done using the tag filter type:

GET /knowledge/v1/kb.kundo.se/guides?filter[tag]=foo

This request will return guides tagged with the “foo” tag.

Filtering by category

Filtering a guide list by category is done using the category filter type:

GET /knowledge/v1/kb.kundo.se/guides?filter[category]=foo

This request will return guides categorized with the “foo” category.

Search guides

It is possible to search in a knowledge base’s guides. This is done using the q query parameter:

GET /knowledge/v1/kb.kundo.se/guides?q=foo

This will return all guides matching the search query “foo”. That is all guides that has the search string “foo” anywhere in their title or content_html field.

The search engine uses some language analysis to make queries a bit smarter. For example, this means that if you search for “queries”, the result will match not only documents containing the word “queries” but also documents matching the base form “query”.

Vote for a guide

It is possible to give feedback to a guide, either positive or negative feedback, by voting on it. You can either upvote a guide, or downvote it. These requests are done like so:

• Upvote a guide

    POST /knowledge/v1/kb.kundo.se/guides/some-guide/upvote

• Downvote a guide

    POST /knowledge/v1/kb.kundo.se/guides/some-guide/downvote

Fetch a guide

GET /knowledge/v1/kb.kundo.se/guides/2
GET /knowledge/v1/kb.kundo.se/guides/slug/komma-igang-med-kundo-mail

Returns:

{
  "data": {
    "attributes": {
      "content_html": "...",
      "slug": "komma-igang-med-kundo-mail",
      "title": "Lägg till ny inkorg i Kundo Mail"
    },
    "id": "2",
    "type": "guide",
    "links": {
      "public": "https://www.kundo.se/hjalp-support?path=%2Fguide%2Fkomma-igang-med-kundo-mail",
      "self": "/knowledge/v1/kb.kundo.se/guides/2"
    }
  },
  "jsonapi": {
    "version": "1.0"
  }
}

Category

List categories

GET /knowledge/v1/kb.kundo.se/categories

Returns:

{
  "data": [
    {
        "attributes": {
            "name": "Kundo Forum",
            "multiple_guides_name": "Fler forumguider",
            "parent_category_id": null,
            "position": 1,
            "slug": "forum"
        },
        "id": "1",
        "type": "knowledge_base_category",
        "links": {
            "public": "https://www.kundo.se/category/forum",
            "self": "/knowledge/v1/kb.kundo.se/categories/1"
        }
    },
    {
        "attributes": {
            "name": "Kundo Mail",
            "multiple_guides_name": "Fler mailguider",
            "parent_category_id": null,
            "position": 2,
            "slug": "mail"
        },
        "id": "2",
        "type": "knowledge_base_category",
        "links": {
            "public": "https://www.kundo.se/category/mail",
            "self": "/knowledge/v1/kb.kundo.se/categories/2"
        }
    }
  ],
  "jsonapi": {
    "version": "1.0"
  }
}

fetch a category

GET /knowledge/v1/kb.kundo.se/categories/1

Returns:

{
  "data": {
    "attributes": {
      "name": "Kundo Forum",
      "multiple_guides_name": "Fler forumguider",
      "parent_category_id": null,
      "position": 1,
      "slug": "forum"
    },
    "id": "1",
    "type": "knowledge_base_category",
    "links": {
      "public": "https://www.kundo.se/category/forum",
      "self": "/knowledge/v1/kb.kundo.se/categories/1"
    }
  },
  "jsonapi": {
    "version": "1.0"
  }
}

Sparse fieldsets

If you don’t want to retrieve all fields on a resource when fetching data from the API, you can use the “Sparse fieldset” feature of JSON API to specify which fields you are interested in.

Example: Fetch the title and slug of all guides

GET /knowledge/v1/kb.kundo.se/guides?fields[guide]=title,slug

This will return a list of guides with only the title and slug fields populated. This specific example can be used to get a list of guides without having to send all guide content data.

Included types

It is possible to retrieve a resource along with related resources.

Included resources will be returned under the included key in the response.

This is done by specifying the include query parameter, like so:

GET /knowledge/v1/kb.kundo.se/guides?include=knowledge_base

{
  "jsonapi" : {
    "version" : "1.0"
  },
  "data" : [
    {
        "type" : "guide",
        "links" : {
          "self" : "/knowledge/v1/kb.kundo.se/guides/500"
        },
        "attributes" : {
          "slug" : "komma-igang-med-kundo-mail",
          "title" : "Lägg till ny inkorg i Kundo Mail",
          "content_html": "..."
        },
        "id" : "500",
        "relationships" : {
          "categories" : {},
          "tags" : {},
          "knowledge_base" : {}
        }
    },
    ... <more guide objects>
  ],
  "included": [
    {
      "data" : {
        "relationships" : {
          "tags" : {},
          "guides" : {},
          "categories" : {}
        },
        "type" : "knowledge_base",
        "attributes" : {
          "host" : "kb.kundo.se",
          "name" : "Kunskapsbanken",
          "organization_name" : "Kundo"
        },
        "id" : "1",
        "links" : {
          "self" : "/knowledge/v1/kb.kundo.se"
        }
      }
    }
  ]
}

Caching

Kundo Knowledge API uses HTTP Etags for caching. This means that for every request sent to the API, the response will come with an etag header that can be used when performing that same request again.

For clients who want to cache the data received from the API, they should make sure to also cache the etag response header, so that they can send that as the if-none-match request header when making subsequent calls to those resources.

If you request /knowledge/v1/kb.kundo.se, you will receive an etag response header with some value, e.g. “ABCDEFGHI123456789”.

When making subsequent requests to that same resource, you can (should) send that etag value as the if-none-match request header. If the resource has not been modified since your last request, you will receive a “304 Not Modified” response and no data.