Skip to main content

 

MindTouch Success Center

Best Practice: Knowledge as a Service (KaaS) (MT4)

Written by Damien Howley
Former MindTouch Employee at MindTouch
This page applies to:MindTouch 4


KaaS stands for Knowledge as a Service which is  when your companies knowledge is available over a web services API.  KaaS provides your company with the ability to make your centralized knowledge available throughout your companies many customer and agent interaction points.  
 

MindTouch and KaaS?

MindTouch provides your knowledge creators with a centralized authoring and feedback environment that is 100% API accessible.   Every piece of knowledge in your MindTouch site can be searched, categorized and consumed over a REST API.  

Below you'll find  a beginners guide to the MindTouch API along with a selection of highlighted KaaS API calls that you'll need to setup your KaaS environment.

MindTouch API 101

Every MindTouch site comes equipped with 100% REST API coverage.  This means that everything you can do through the web User Interface (UI) can equally be accomplished through the API.  This includes everything from displaying knowledge to managing users, uploading files and more. 

Required Skills 

To get started using your MindTouch API you'll need to have some experience with web or application development.  If you have not used an API before, we highly recommend that you connect with a resource at your company that has.  This many include someone from engineering, support or product.

Sample API GET Call

Page ID:  7239

Page URI:  https://support.mindtouch.com/01Mind...t_in_MindTouch

API Path:  /@api/deki/pages/{pageid}/info

API URI:  https://support.mindtouch.com/@api/d...ages/7239/info

 

Returned XML

<page id="7239" href="https://support.mindtouch.com/@api/deki/pages/7239?redirects=0" deleted="false" revision="8">
    <uri.ui>https://support.mindtouch.com/01MindTouch_4/MindTouch_4_Tools/Structuring_Content_in_MindTouch</uri.ui>
    <title>Structuring Content in MindTouch</title>
    <path>01MindTouch_4/MindTouch_4_Tools/Structuring_Content_in_MindTouch</path>
    <namespace>main</namespace>
    <date.created>2012-12-20T20:48:15Z</date.created>
</page>

Tip:  For a quick way to find a page ID, simply go to a MindTouch page, view the page source through your browser and search for pageid.  

KaaS API Calls

The following API examples can be used to access knowledge from your MindTouch instance  These API example might be used to recommend articles based on a keyword, to enable agents to quickly find knowledge or to provide your customers with a consistent knowledge experience throughout all engagement channels. 

Search

API Path:  /@api/deki/site/query
 

Access a Page 

API Path:  /@api/deki/pages/{pageid}

 

Required Parameters

  • {pageid} = string : either an integer page ID, "home", or "=" followed by a double uri-encoded page title

 

Optional Parameters

  • mode = {edit, raw, view} : render content for different uses; default is 'view'
  • redirects = int? : If zero, do not follow page redirects.
  • includeDeleted = bool : When pageid is an integer page ID, and this parameter is set to true, we'll even return the page if it was deleted at some point
  • exclude = string? : Elements to exclude from response document (choice of "inbound", "outbound", "files"; default: exclude nothing)
  • revision = string? : Page revision to retrieve. 'head' by default will retrieve latest revision. Positive integer or a GUID will retrieve specific revision
  • format = {html, xhtml}? : Result format (default: html)
  • include = string? : Extra elements to include (choice of "contents","prevnext"; default: include nothing extra)
  • authenticate = bool? : Force authentication for request (default: false)

 

Returned XML

<page id="7239" href="https://support.mindtouch.com/@api/deki/pages/7239?redirects=0" deleted="false" revision="8">    
    <uri.ui>https://support.mindtouch.com/01MindTouch_4/MindTouch_4_Tools/Structuring_Content_in_MindTouch</uri.ui>    
    <title>Structuring Content in MindTouch</title>    
    <path>01MindTouch_4/MindTouch_4_Tools/Structuring_Content_in_MindTouch</path>
    <namespace>main</namespace>    
    <date.created>2012-12-20T20:48:15Z</date.created>
    <language>en-US</language>
    <language.effective>en-US</language.effective>    
    <metrics>        
        <metric.views>3296</metric.views>        
        <metric.charcount>7022</metric.charcount>
        </metrics>
        ....    
        ....
</page>

Tip:  For a quick way to find a page ID, simply go to a MindTouch page, view the page source through your browser and search for pageid.  

List all Tags

API Path:  /@api/deki/site/tags

API URI:  https://support.mindtouch.com/@api/deki/site/tags

 

Optional Parameters

  • authenticate = bool? : Force authentication for request (default: false)
  • type = string? : type of the tag (text | date | user | define) (default: all types)
  • pages = bool? : show pages with each tag (default: false)
  • q = string? : partial tag name to match (ex: tagprefix) (default none)
  • from = string? : start date for type=date (ex: 2008-01-30) (default: now)
  • to = string? : end date for type=date (ex: 2008-12-30) (default: now + 30 days)

 

Returned XML

<tags count="1">
    <tag value="access" id="326" href="https://support.mindtouch.com/@api/deki/site/tags/326" count="1">
    <uri>https://support.mindtouch.com/Special:Tags?tag=access</uri>
    <type>text</type>
    <title>access</title>
</tag>

List Pages with a Tag

API Path:  /@api/deki/site/tags//*

API URI:  https://support.mindtouch.com/@api/d.../tags/=access/

 

Required Parameters

  • {tagid} = string : either an integer tag ID or "=" followed by a double uri-encoded tag name

 

Optional Parameters

  • parentid = int? : only return pages that live under this page id. (default: all pages)
  • authenticate = bool? : Force authentication for request (default: false)
  • language = string? : filter pages by language (default: all languages)
  • include = string? : a comma separated list of elements to include, chose from 'tags' (default: none)

 

Returned XML

<tag value="access" id="326" href="https://support.mindtouch.com/@api/deki/site/tags/326" count="1">
    <uri>https://support.mindtouch.com/Special:Tags?tag=access</uri>
    <type>text</type>
    <title>access</title>
    <pages count="1" totalcount="2">
        <page id="7615" href="https://support.mindtouch.com/@api/deki/pages/7615?redirects=0" deleted="false">
            <uri.ui>
                https://support.mindtouch.com/01MindTouch_TCS/User_Guide/007_The_More_Menu/Restrict_Access
            </uri.ui>
            <title>Restricting Access</title>
            <path type="custom">
                01MindTouch_TCS/User_Guide/007_The_More_Menu/Restrict_Access
            </path>
            <namespace>main</namespace>
            <date.created>2013-03-21T19:37:14Z</date.created>
        </page>
    </pages>
</tag>

List SubPages

API Path:  /@api/deki/pages/{pageid}/subpages

API URI:  https://support.mindtouch.com/@api/d.../7795/subpages

 

​Required Parameters

  • {pageid} = string : An integer page ID of a deleted page

 

Optional Parameters

  • authenticate = bool? : Force authentication for request (default: false)

 

​Returned XML

<subpages totalcount="1" count="1" href="https://support.mindtouch.com/@api/deki/pages/7795/subpages">
    <page.subpage id="7706" href="https://support.mindtouch.com/@api/deki/pages/7706?redirects=0" deleted="false" terminal="true" subpages="false">
        <uri.ui>
            https://support.mindtouch.com/01MindTouch_4/MindTouch_4_Tools/API_FAQ
        </uri.ui>
        <title>API FAQ</title>
        <path>01MindTouch_4/MindTouch_4_Tools/API_FAQ</path>
        <namespace>main</namespace>
        <date.created>2013-04-03T05:17:09Z</date.created>
    </page.subpage>
</subpages>

List Files

API Path:  /@api/deki/pages/{pageid}/files​

API URI:  https://support.mindtouch.com/@api/d...ges/7239/files

 

Required Parameters

  • {pageid} = string : either an integer page ID, "home", or "=" followed by a double uri-encoded page title

 

Optional Parameters

  • authenticate = bool? : Force authentication for request (default: false)
  • redirects = int? : If zero, do not follow page redirects.
  • offset = int? : Number of items to skip. Must be a positive number or 0 to not skip any. (default: 0)
  • limit = string? : Maximum number of items to retrieve. Must be a positive number or 'all' to retrieve all items. (default: 100)

 

Returned XML

<files count="1" offset="0" totalcount="1" href="https://support.mindtouch.com/@api/deki/pages/7239/files">
    <file id="2183" revision="1" res-id="9912" href="https://support.mindtouch.com/@api/deki/files/2183/info" res-is-deleted="false" res-rev-is-deleted="false" res-contents-id="17235">
        <filename>wireframe_guide_page.png</filename>
        <description/>
        <contents type="image/png" size="39091" width="327" height="272" href="https://support.mindtouch.com/@api/deki/files/2183/wireframe_guide_page.png"/>
        <contents.preview rel="thumb" type="image/png" maxwidth="160" maxheight="160" href="https://support.mindtouch.com/@api/deki/files/2183/wireframe_guide_page.png?size=thumb"/>
        <contents.preview rel="webview" type="image/png" maxwidth="550" maxheight="550" href="https://support.mindtouch.com/@api/deki/files/2183/wireframe_guide_page.png?size=webview"/>
        <date.created>2013-07-30T21:13:11Z</date.created>
        <user.createdby id="17" href="https://support.mindtouch.com/@api/deki/users/17">
            <nick>damienh</nick>
            <username>damienh</username>
            <fullname/>
            <password exists="false"/>
            <license.seat>true</license.seat>
            <date.created>2012-08-15T18:12:37Z</date.created>
            <status>active</status>
            <date.lastlogin>2014-01-08T20:27:58Z</date.lastlogin>
            ....
            ....
</file>

Tip:  For a quick way to find a page ID, simply go to a MindTouch page, view the page source through your browser and search for pageid.  

List Tags

API Path:  /@api/deki/pages/{pageid}/tags​

API URI:  https://support.mindtouch.com/@api/d...ages/7239/tags

 

Required Parameters

  • {pageid} = string : either an integer page ID, "home", or "=" followed by a double uri-encoded page title

 

Optional Parameters

  • export = bool? : Strip tag xml of site specific information (default: false
  • authenticate = bool? : Force authentication for request (default: false)
  • redirects = int? : If zero, do not follow page redirects.

 

Returned XML

<tags count="1" href="https://support.mindtouch.com/@api/deki/pages/7239/tags">
    <tag value="article:howto" id="228" href="https://support.mindtouch.com/@api/deki/site/tags/228">
        <uri>
            https://support.mindtouch.com/Special:Tags?tag=article:howto
        </uri>
        <type>text</type>
        <title>article:howto</title>
    </tag>
</tags>