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.