Skip to main content
NICE CXone Expert
Expert Success Center

API Reference

Welcome to the CXone Expert API reference documentation! This guide is your starting point to begin leveraging the CXone Expert API to create advanced content integrations, automate workflows, and download analytics data. The migration of API documentation from the previous guide to this location is an ongoing effort. You are welcome to browse the old API Calls guide, in the event that the API endpoints or use cases you are looking for are not yet migrated.

Introduction

CXone Expert provides out of the box, easily configurable, integrations in the form of Touchpoints. Touchpoints extend your content into other web applications, CRM's, or websites. However, the Expert API can integrate with applications and systems without a web presentation, such as voice assistants and IoT devices. In addition, integrations with publishing automation systems, user management, and translation management systems can be desirable when CXone Expert becomes a critical piece of your organization's business. 

These types of integrations typically require more complexity and application programming skills. While the API can be easily used to quickly fetch or update content on the fly, it's value is realized when integrations unlock the ability to extend functionality into key parts of an organization.

Do you have further questions? Try consulting the API FAQ.

Getting Started

The API is organized around REST, and is located at the /@api/deki relative URL on an Expert site.

https://example.com/@api/deki

Every resource on the site (pages, users, groups, etc.) is available through the API. Authenticated site users can access the API, through the web browser, once they have signed into the site. System and application integrations require the use of API Tokens to access the API.

HTTPS

API communication is secured with HTTPS. It can be accessed privately and securely by HTTPS compatible clients such as a web browser. The API domain (an Expert site domain) and any additional domains that are required for integrations must be trusted by the HTTPS compatible client or integration. In order to avoid disruptions when SSL/TLS certificates are rotated for these domains, it is highly recommended to trust certificate authority (CA) root and intermediate certificates, as opposed to the domain's server certificate.

In addition to the site domain, integrations with the API rely on HTTPS communication with the following domains:

  • *.cloudfront.net
  • files.mtstatic.com

Responses

The default HTTP response content type is application/xml; charset=utf-8, but an application/json; charset=utf-8 response is possible if API requests include a dream.out.format=json HTTP query parameter.

// XML-encoded response
https://example.com/@api/deki/pages/{id}/info

// JSON-encoded response
https://example.com/@api/deki/pages/{id}/info?dream.out.format=json

Some API endpoints may, by default, respond with a application/json; charset=utf-8 media type or an alternative media type. These defaults are noted in the documentation for those specific API endpoints.

Status Codes

CXone Expert uses conventional HTTP response status codes to indicate the success or failure of an API request. Status codes in the 2xx range indicate successful requests. Status codes in the 4xx range indicate a problem with the request such as a missing URL query parameter or invalid HTTP body format. Status codes in the 5xx range indicate an unexpected, internal problem with the API and can be reported to the CXone Expert Support Team.

On rare occasions, an API endpoint is deprecated and removed. If it is replaced with a new endpoint, under most circumstances, the old endpoint will redirect to the new endpoint. In order for backward compatibility to be maintained, it is important that API clients follow the Location HTTP Header, if a 3xx range status code is returned in an HTTP response.

Name Value Description
OK 200 The request was processed and completed successfully
Accepted 201 The request was accepted successfully and will be processed in a queue
Non-Authoritative Information 203 The request was accepted, however, due to processing errors, the response contains partially complete data 
Moved Permanently 301 The API endpoint was deprecated and replaced with a new location
Found 302 After processing the request, the resource to be returned is located at different URL
Bad Request 400 Invalid or missing request URL query parameter, invalid HTTP body format, or invalid or missing HTTP body parameter value
Unauthorized 401 A request to the authentication API endpoint failed
Forbidden 403 The requested resource is not accessible to due to a permission check or invalid authorization
Not Found 404 The requested resource could not be found
Not Allowed 405 The API endpoint does not support the HTTP method in the request.
Gone 410 The API endpoint was deprecated and was not replaced with a new location

Errors

There are two possible error response formats that can be received from the API. The use of these formats varies between errors and API endpoints, therefore your API integration must be developed to handle both formats. Some response fields have been removed from these examples, as they contain internal metadata that is irrelevant to API integrations.

Default Error Format

<error>
    <exception>{exception}</exception>
    <message>{message}</message>
</error>

Legacy Error Format (Deprecated) 

<error>
    <status>{status}</status>
    <title>{title}</title>
    <message>{message}</message>
    <uri>{uri}</uri>
</error> 
Name Type Description
{exception} string A unique, namespaced key that identifies the error
{message} string The description of the error or explanation of the problem
{status} int The HTTP status code (ex: 400)
{title} string The HTTP status name (ex: Bad Request)
{uri} string The API endpoint URL

Authorization

The API can receive three types of tokens to allow access to site data.

  • All tokens are scoped to and unique to a site
  • Can be a single string value or multiple string values, such as key / secret pairs
  • Token string values can be up to 255 characters long

Auth Token

Auth Tokens (often stylized as authtoken) are set as HTTP cookies in a user's web browser after authentication. Auth Tokens are generated by a site and are cryptographically signed to prevent tampering.

Browser API Token

Browser API Tokens are sent from a website, web application, or simply anything that runs in a web browser to the API. Implementations with Browser API Tokens are written in web browser executable languages such as JavaScript.

Normally, web browsers such as Google Chrome or Mozilla Firefox do not allow JavaScript applications running on one website to access data from another. Browsers block cross-origin requests and responses due to the security issues it can cause, especially if one website's JavaScript application uses the cookies of another website to impersonate a user's identity for nefarious purposes. However, a website can declare which third party websites can securely access its data using Cross Origin Resource Sharing (CORS). Browser API Tokens allow developers to implement CORS in a safe and secure manner. In addition to CORS, Browser API Tokens also allow same origin API access from JavaScript executed in content on a site to the same site's API.

A Browser API Token has no specific user permissions for the API to determine which operations are or are not allowed. User permissions are determined by the web browser session's authtoken HTTP cookie. If the user accessing the integration has not signed in to the site, then the API considers the user to be an anonymous user

Authorizing web browser integrations with the MindTouch API
Authorize integrations between the MindTouch API and websites, web applications, Google Chrome apps, or simply anything that runs in a web browser.
Pages: 2

Server API Token

Server API Tokens are used to create integrations between a server application, IoT, bots, or anything that can communicate over HTTPS, and the API. Implementations with Server API Tokens are typically written in server executed languages such as C#, Java, JavaScript (Node.js), Python, Go, and PHP. The token consists of a key and a secret which are used to sign API requests, allowing valid requests through and rejecting invalid or expired requests. The token secret is meant to be kept in a secure place, and should never be shared or sent across the internet in plain text.

Authorizing server integrations with the MindTouch API
Authorize integrations between the MindTouch API and server applications, IoT devices, bots, or anything that can communicate over HTTPS.
Pages: 2

OAuth API Token

While Server API Tokens provide a developer with the ability to connect applications and devices to the API with unlimited permissions, under some scenarios this level of access control is inappropriate for a developer. Examples include integrations between the API and a third-party service, on behalf of the organization deploying CXone Expert. By implementing OAuth 2.0 authorization flows, OAuth API Tokens allow users to authorize which applications or devices can access their user identities and allowed operations such as reading and writing content. OAuth API Tokens can be safely given to third-party developers, without the concern of handing over site administrator access.

Authorizing OAuth 2.0 integrations with the MindTouch API
Integrate MindTouch users with server applications, IoT devices, bots, or anything that can communicate over HTTPS using an industry-standard authorization framework .
Pages: 2

Core Resources

Expert API core resources are very common platform objects such as pages, files, users, and groups. These core resources appear in request and response HTTP messages across many different API endpoints. Consistent XML and JSON data representations of these resources allow for API integrations to contain reusable code to handle this data.

Not every possible API resource is considered a core resource. Some API endpoints accept and return resource data that are not common across the broader API endpoint collection.

Page

Page resources are the most common resource in the Expert API.

Page Types

Existing Page

Existing pages, including unpublished pages with content under preparation as drafts and deleted pages that have not yet been purged from the archive, are pages that are found in the page hierarchy. Pages include all Guided Content Framework page types such as Categories, Guides, Topics, and References.

<page id="{id}"
      guid="{guid}"
      draft.state="{draft.state}"
      href="https://{hostname}/@api/deki/pages/{id}?redirects=0"
      deleted="{deleted}"
      revision="{revision">
    <uri.ui>https://{hostname}/{path}</uri.ui>
    <title>{title}</title>   
    <path seo="{seo}" type="{path/@type}">{path}</path>
    <namespace>{namespace}</namespace>
    <date.created>{date.created}</date.created>
    <language>{language}</language>
</page> 
Virtual Page

Virtual pages are placeholder locations in the page hierarchy where a page has not yet been created.

<page id="0"
      guid="00000000000000000000000000000000"
      virtual="true"
      draft.state="inactive"
      href="https://{hostname}/@api/deki/pages/0?redirects=0"
      deleted="false">
    <uri.ui>https://{hostname}/{path}</uri.ui>
    <title>{title}</title>
    <path seo="{seo}">{path}</path>
    <namespace>{namespace}</namespace>
    <date.created>1970-01-01T00:00:00Z</date.created>
    <language>{language}</language>
    {security}
    {page.parent}
</page>
Redirect Page

Redirect pages are existing pages that point to a different page in the page hierarchy or an external URL.

<page id="{id}"
      guid="00000000000000000000000000000000"
      redirect="true"
      draft.state="inactive"
      href="https://{hostname}/@api/deki/pages/{id}?redirects=0"
      deleted="false"
      revision="{revision}"
      type="{page/@type}">
    <uri.ui>https://{hostname}/{path}</uri.ui>
    <title>{title}</title>
    <path seo="{seo}">{path}</path>
    <namespace>{namespace}</namespace>
    <date.created>1970-01-01T00:00:00Z</date.created>
    <language>{language}</language>
    
    <!-- page.redirectedto is available when page/@type = "internal-redirect" -->
    {page.redirectedto}
    
    <!-- uri.redirectedto is available when page/@type = "external-redirect" -->
    <uri.redirectedto>{uri.redirectedto}</uri.redirectedto>
</page>

Page Data

Name Type Description
{id} int Local page id - if the page is exported and imported into a different Expert site, a new local page id will be assigned
{guid} string Global page id - if the page is exported and imported into a different Expert site, the same global page id will be preserved
{draft.state} {active, inactive, unpublished} Does the page have an active or unpublished draft?
{hostname} string The Expert site hostname
{deleted} bool Is the page deleted and in the archive?
{revision} int The page revision
{page/@type} {internal-redirect, external-redirect} Does the page redirect to an external URL or an existing page in the page hierarchy
{title} string The page display title
{seo} bool Is the page URL search engine optimized?
{path} string The page URL path
{namespace} {main, template} Is the page in the template directory or a child of the home page in the page hierarchy?
{date.created} datetime ISO 8601 representation of the page's creation timestamp
{language} string The page (site) language
{page.parent} Page The page that is the direct parent in the page hierarchy - the {page.parent} may also contain its own {page.parent} resource, depending upon its position in the page hierarchy
{security} Security The allowed operations and assigned permissions for the page
{page.redirectedto} Page The existing page that the page URL will redirect to
{uri.redirectedto} uri The external URL that the page URL will redirect to

Retrieving Pages

A local page id or global page id (guid) can be used to retrieve page resource data from the Expert API. They can also be used to create links that resolve and redirect to the page content in the Expert user interface.

This example HTML will create contextual help links to the KCS Methodology guide. Hover over the links to view the target page id or guid.

Follow this page id

Follow this page guid

<!-- resolve and redirect to a page using a local page id -->
<a class="F1" href="https://{hostname}/@go/page/{id}">Follow this page id</a>

<!-- resolve and redirect to a page using a page guid -->
<a class="F1" href="https://{hostname}/@go/page/:{guid}">Follow this page guid</a>

Page Content

A known custom header starting with X-Deki is always required for retrieving and updating content with the content type of text/plain.  An opaque header X-Deki-CSRFcan also be used.

Retrieve
$ curl --header 'X-Deki-Token: {signature}' https://{hostname}/@api/deki/site/pages/{id}/contents
Response

The body of the response is html encoded and needs to be decoded for a page content for content type text/plain.  Alternatively, a content type of application/xml could be used on the POST request with this response.

<content revision="56" type="text/html" title="X-15"><body> &lt;p&gt;test&lt;/p&gt; </body><body target="toc">&lt;em&gt;No headers&lt;/em&gt;</body></content>
Updating
$ curl --request POST --header 'X-Deki-Token: {signature}' --header 'Content-Type: text/plain; charset=utf-8' https://{hostname}/@api/deki/site/pages/{id}/contents?edittime=now --data {body}

Security

Security resources represent the permissions, privacy, and roles that manage security for pages, users, files, and other resources.

Further details regarding the management of security, permissions, privacy, and roles can be found in content and site administration topics:

Security Types

Page Security 
<security href="https://{hostname}/@api/deki/pages/{pageid}/security">
    {permissions.effective}
    {permissions.page}        
    <grants>
        <grant>
            {permissions}
            <date.modified>{date.modified}</date.modified>
            {user.modifiedby}
            
            <!-- group is available if a group has been assigned a role on the resource managed by this security node -->
            {group}
           
            <!-- user is available if a user has been assigned a role on the resource managed by this security node -->
            {user}
        </grant>
        
        <!-- multiple user or group permissions (grant nodes) are supported -->
        ...
    </grants>
    {permissions.revoked}
</security>
Permissions
<permissions>
    <operations mask="{mask}">{operations}</operations>
    
    <!-- restriction is available if permissions are calculated by page privacy -->
    <restriction id="{restriction/@id}">{restriction}</restriction>
    
    <!-- role is available if permissions are calculated by assigning a role to a user or group on the resource -->
    <role id="{role/@id}" href="https://{hostname}/@api/deki/site/roles/{role/@id}">{role}</role>
</permissions>

Security Data

Name Type Description
{hostname} string The Expert site hostname
{pageid} int Local page id - if the page is exported and imported into a different Expert site, a new local page id will be assigned
{permissions.effective} Permissions The effective permissions, computed from the page, user, and group permissions
{permissions.page} Permissions The page permissions, computed from the assigned restriction (page privacy)
{permissions} Permissions User and group permissions, computed from roles assigned to users and groups on the resource
{mask} long The operations that are allowed or revoked, represented by a sequence of bits
{operations} string The operations that are allowed or revoked
{restriction/@id} int The restriction (page privacy) id
{restriction} {Public, Private, Semi-Public, Semi-Private} The restriction (page privacy) type
{role/@id} int The role id
{role} string The role name
{date.modified} datetime ISO 8601 representation of the last security modification timestamp
{user} User The user that is assigned a role on the resource
{group} Group The group that is assigned a role on the resource

User

User resources represent users in Expert including community members, authors, and administrators.
<user anonymous="{anonymous}" id="{id}" href="https://{hostname}/@api/deki/users/{id}" guid="{guid}">
    <nick>{username}</nick>
    <username>{username}</username>
    <fullname>{fullname}</fullname>
    <email>{email}</email>
    <password exists="{password/@exists}"/>
    <license.seat owner="{license.seat/@owner}">{license.seat}</license.seat>
    <date.created>{date.created}</date.created>
    <status>{status}</status>
    <date.lastlogin>{date.lastlogin}</date.lastlogin>
    <hash.email>{hash.email}</hash.email>
    <uri.gravatar>{uri.avatar}</uri.gravatar>
    <uri.avatar>{uri.avatar}</uri.avatar>
</user>
Name Type Description
{id} int Local user id
{guid} string Global user id
{hostname} string The Expert site hostname
{anonymous} bool Is the user an anonymous user (not signed in)?
{username} string User's sign-in name
{fullname} string User's display name
{email} string User's email address
{password/@exists} bool Does the user have a password set?
{license.seat/@owner} bool Is the user a site owner?
{license.seat} bool Is the user a pro member?
{date.created} datetime ISO 8601 representation of the user account's creation timestamp
{date.lastlogin} datetime ISO 8601 representation of the last time the user signed in
{status} bool Is the user active and able to sign in?
{hash.email} string An MD5 representation of the user's email address
{uri.avatar} uri A URL to a Gravatar, mapped to the user's email address

 

Group

Group resources represent collections of users for reporting needs or content access controls.
<group id="{id}" href="https://{hostname}/@api/deki/groups/{id}" guid="{guid}">
    <groupname>{name}</groupname>
    <service.authentication id="{authid}" href="https://{hostname}/@api/deki/site/services/{authid}"/>
    <users count="{users.count}" href="https://{hostname}/@api/deki/groups/{id}/users"/>
    {permissions.group}
</group>
Name Type Description
{id} int Local group id
{guid} string Global group id
{hostname} string The Expert site hostname
{name} string Group name
{authid} int The identity provider service id
{users.count} int The total count of users that belong to the group
{permissions.group} Permissions The role assigned to the group

 

Property

<property revision="{revision}" resid="{id}" name="{name}" href="https://{hostname}/@api/deki/{resource}/info" etag="{etag}" resource-is-deleted="{deleted}" resource-rev-is-deleted="{rev-deleted}">
    <contents type="{mimetype}" size="{size}" href="https://{hostname}/@api/deki/{resource}">
        {contents}
    </contents>
    <date.modified>{date.modified}</date.modified>
    {user.modified}
</property>
Name Type Description
{revision} int The property revision
{id} int Local property id - if the property is exported and imported into a different Expert site, a new local property id will be assigned
{name} string The property name (ex: urn:custom.mindtouch.com#css) Required properties that the Expert platform relies on are often prefixed with namespaces ending with a # symbol (ex: urn:ui.deki.mindtouch.com#)
{hostname} string The Expert site hostname
{resource} string The parent resource that this property is assigned to (available: User, Page, Site)
{etag} string A checksum of the last property modification. The etag can be provided when modifying the property to prevent out-of-sync revision editing collisions
{deleted} bool Was this property deleted?
{rev-deleted} bool Was this specific property revision deleted?
{mimetype} string Property content type (default: text/plain)
{size} int Property content size in bytes
{contents} string A preview of the textual representation of the property content. If the property is larger than 2048 bytes, then the property content must be loaded using the contents/@href URI
{date.modified} datetime ISO 8601 representation of the property's creation or last modification timestamp
{user.modified} User The user that created or last modified the property

 


Behavioral and Content Analytics

API endpoints for integrating user behavioral and content health data into reporting systems

Search Analytics Data

The analytics data that powers the Search Insights Report and Search Terms and Queries Report is available through API endpoints to export the data for further analysis.

Endpoints

Site Structure Analysis Data

The analytics data that powers the Site Structure Analysis Report provides the insight to maintain a healthy site content structure.

Endpoints

Retrieve search terms and queries

Applies to:
All MindTouch Versions
Role required:
Admin
GET /@api/deki/site/query/log
cURL
$ curl --request GET --header 'X-Deki-Token: {signature}' https://{hostname}/@api/deki/site/query/log
JavaScript
fetch('https://{hostname}/@api/deki/site/query/log?dream.out.format=json', {
    method: 'GET',
    headers: {
        'X-Deki-Token': '{signature}'
    }
}).then((response) => {
    return response.json();
});

Request

► Expand / Collapse
Parameters
The parameters that are required or accepted by this endpoint (optional parameters can be appended to the endpoint query string)
NameTypeDescription
{hostname}stringThe MindTouch site hostname
{signature}stringThe API Token key or signature
{query} (optional)string?Find searches using the given query term string (overrides 'term')
{term} (optional)string?Find searches containing a specific term
{groupby} (optional){query}?Aggregate by query
{userid} (optional)string?Return only results for user (allowed: integer user id or 'current' to filter by the current user) (default: results for all users)
{lowquality} (optional)bool?Find searches that have 0 or more than 3 result
{since} (optional)string?Start date for result set (format: 'yyyyMMddHHmmss') (default: one month ago)
{before} (optional)string?End date for result set (format: 'yyyyMMddHHmmss') (default: now)
{limit} (optional)int?Maximum number of items to retrieve. Must be a positive number (default: 25)
{offset} (optional)int?Number of items to skip (allowed: a positive number or 0 to not skip any) (default: 0)
{count} (optional)int?Number of items to skip (allowed: a positive number or 0 to not skip any) (default: 0)
{getcount} (optional)bool?Adds total count (default: true)

Response

The response body is alternatively available in JSON format by appending dream.out.format=json to the request URL
<queries count="{count}" querycount="{querycount}">
    
    <!-- multiple tracked search queries are supported -->
    {query}
    ...
</queries> 
Name Type Description
{querycount} int The total count of tracked search queries
{count} int The count of tracked search queries in response
{query} Search Query A tracked search query

 


Retrieve all available search query log names

Applies to:
MindTouch (current)
Role required:
Admin
GET /@api/deki/site/query/logs
cURL
$ curl --request GET --header 'X-Deki-Token: {signature}' https://{hostname}/@api/deki/site/query/logs
JavaScript
fetch('https://{hostname}/@api/deki/site/query/logs?dream.out.format=json', {
    method: 'GET',
    headers: {
        'X-Deki-Token': '{signature}'
    }
}).then((response) => {
    return response.json();
});

Request

► Expand / Collapse
Parameters
The parameters that are required or accepted by this endpoint (optional parameters can be appended to the endpoint query string)
NameTypeDescription
{hostname}stringThe MindTouch site hostname
{signature}stringThe API Token key or signature

Response

The response body is alternatively available in JSON format by appending dream.out.format=json to the request URL
<logs>

    <!-- multiple search query logs are supported -->
    <log complete="{complete}">
        <name>{logname}</name>
        <modified>{modified}</modified>
        <month>{month}</month>
    </log>
    ...
</logs>
Name Type Description
{complete} bool Is the search query log data complete for the current month
{logname} string The log name (included when retrieving search query log download URL)
{modified} datetime ISO 8601 representation of the search query log's last modification timestamp
{month} datetime ISO 8601 representation of the search query log's month

 

 


Retrieve search query log download URL

Applies to:
MindTouch (current)
Role required:
Admin
GET /@api/deki/site/query/logs/{logname}/url
cURL
$ curl --request GET --header 'X-Deki-Token: {signature}' https://{hostname}/@api/deki/site/query/logs/{logname}/url
JavaScript
fetch('https://{hostname}/@api/deki/site/query/logs/{logname}/url?dream.out.format=json', {
    method: 'GET',
    headers: {
        'X-Deki-Token': '{signature}'
    }
}).then((response) => {
    return response.json();
});

Request

► Expand / Collapse
Parameters
The parameters that are required or accepted by this endpoint (optional parameters can be appended to the endpoint query string)
NameTypeDescription
{hostname}stringThe MindTouch site hostname
{signature}stringThe API Token key or signature
{logname}stringName of the log to retrieve a url for

Response

The response body is alternatively available in JSON format by appending dream.out.format=json to the request URL
<log>
    <url>{url}</url>
</log>
Name Type Description
{url} uri A URL to download a search query log in CSV format. The downloaded file may require decompression.
Search Query Log
Field Type Description
Date time stamp

Format: yyyy-mm-dd hh:mm:ss 
Clock: 24 hrs
Time Zone: UTC

Sorted Terms string All words within the Raw Query sorted by alphabetical order.
Raw Query string The search query as entered by the user.
User ID number Unique user identifier associated with the user who entered the query.
Result Count number Number of results returned for the specified query.
Position Clicked number Location of the item clicked within the list of search results.
Result Type string Type of result (for example page, file).
Result Page Path string Path of of the result clicked, in the format xxx/xxx/xxx/...
Result Page ID number Unique page identifier.

 


Retrieve search term and query detail

Applies to:
All MindTouch Versions
Role required:
Admin
GET /@api/deki/site/query/log/{queryid}
cURL
$ curl --request GET --header 'X-Deki-Token: {signature}' https://{hostname}/@api/deki/site/query/log/{queryid}?queryid={queryid}
JavaScript
fetch('https://{hostname}/@api/deki/site/query/log/{queryid}?dream.out.format=json&queryid={queryid}', {
    method: 'GET',
    headers: {
        'X-Deki-Token': '{signature}'
    }
}).then((response) => {
    return response.json();
});

Request

► Expand / Collapse
Parameters
The parameters that are required or accepted by this endpoint (optional parameters can be appended to the endpoint query string)
NameTypeDescription
{hostname}stringThe MindTouch site hostname
{signature}stringThe API Token key or signature
{queryid}stringEither the unique query id, or the aggregated, sorted querystring prefixed with an =
{since} (optional)string?Start date for querystring based aggregation (format: 'yyyyMMddHHmmss') (default: one month ago)
{before} (optional)string?End date for querystring based aggregation (format: 'yyyyMMddHHmmss') (default: now)
{getcount} (optional)bool?Adds total count (default: true)

Response

The response body is alternatively available in JSON format by appending dream.out.format=json to the request URL
Search Query
<query id="{queryid}" href="https://{hostname}/@api/deki/site/query/log/{queryid}">
    <date.searched>{date.searched}</date.searched>
    <sorted-terms>{sorted-terms}</sorted-terms>
    <raw>{raw}</raw>
    <count.results>{count.results}</count.results>
    <terms>
    
        <!-- multiple search terms are supported --> 
        <term>{term}</term>
        ...
    </terms>
    <selected-results count="{selected-results/@count}">
    
        <!-- multiple selected results are supported -->
        <result type="{result/@type}">
            <position>{result/position}</position>
            <rank>{result/rank}</rank>
            <date.selected>{result/date.selected}</date.selected>
            <page id="{result/page/@id}" href="https://{hostname}/@api/deki/pages/{result/page/@id}"/>
        </result>
        ...
    </selected-results>
</query>
Name Type Description
{queryid} int Unique search query id for tracking
{hostname} string The Expert site hostname
{date.searched} datetime ISO 8601 representation of when the search query was executed
{sorted-terms} string A list of search terms normalized and ordered alphabetically
{raw} string The raw search query with no processing applied
{count.results} int Total count of matching results
{term} string A single search term
{selected-results/@count} int Count of search results that were selected as a result of the search query
{result/@type} {page, recommended, file} The search result type
{result/position} int The search result's position within all results including recommended search results
{result/rank} int The search engine's weighted ranking of the search result (between 0 and 1)
{result/page/@id} int Local page id - if the page is exported and imported into a different Expert site, a new local page id will be assigned

 


Retrieve search terms

Applies to:
All MindTouch Versions
Role required:
Admin
GET /@api/deki/site/query/log/terms
cURL
$ curl --request GET --header 'X-Deki-Token: {signature}' https://{hostname}/@api/deki/site/query/log/terms
JavaScript
fetch('https://{hostname}/@api/deki/site/query/log/terms?dream.out.format=json', {
    method: 'GET',
    headers: {
        'X-Deki-Token': '{signature}'
    }
}).then((response) => {
    return response.json();
});

Request

► Expand / Collapse
Parameters
The parameters that are required or accepted by this endpoint (optional parameters can be appended to the endpoint query string)
NameTypeDescription
{hostname}stringThe MindTouch site hostname
{signature}stringThe API Token key or signature
{lowquality} (optional)bool?Find searches that have 0 or more than 1 result
{since} (optional)string?Start date for result set (format: 'yyyyMMddHHmmss') (default: one month ago)
{before} (optional)string?End date for result set (format: 'yyyyMMddHHmmss') (default: now)
{limit} (optional)int?Maximum number of items to retrieve (allowed: a positive number) (default: 25)
{offset} (optional)int?Number of items to skip (allowed: a positive number or 0 to not skip any) (default: 0)

Response

The response body is alternatively available in JSON format by appending dream.out.format=json to the request URL
<terms count="{count}" querycount="{querycount}">
    
    <!-- multiple search terms are supported -->
    <term count="{hits}">{term}</term>
    ...
</terms>
Name Type Description
{querycount} int The total count of search terms
{count} int The count of search terms in response
{term} string A single search term
{hits} int The total count of matches to a result 

 


Retrieve search analytics

Applies to:
MindTouch (current)
Role required:
Admin
GET /@api/deki/site/search/analytics
cURL
$ curl --request GET --header 'X-Deki-Token: {signature}' https://{hostname}/@api/deki/site/search/analytics?dream.out.format=json
JavaScript
fetch('https://{hostname}/@api/deki/site/search/analytics?dream.out.format=json', {
    method: 'GET',
    headers: {
        'X-Deki-Token': '{signature}'
    }
}).then((response) => {
    return response.json();
});

Request

► Expand / Collapse
Parameters
The parameters that are required or accepted by this endpoint (optional parameters can be appended to the endpoint query string)
NameTypeDescription
{hostname}stringThe MindTouch site hostname
{signature}stringThe API Token key or signature
{start} (optional)string?Start range date (format: 'yyyyMMddHHmmss') (default: one month ago)
{end} (optional)string?End range date (format: 'yyyyMMddHHmmss') (default: now)
{bucket} (optional)string?Time period bucket size (allowed: hour, day, week, month, quarter, year) (default: month)
{userfilter} (optional)string?User filter to apply to data (allowed: none, pro, anonymous, community, anonymousorcommunity, communityorpro) (default: none)
{queryfilters} (optional)string?Comma separated list of search term filters to apply to data (ex: foo,bar) (default: none)
{web_widget_embed_id} (optional)string?Filter data by a web widget embed code id
{originfilter} (optional)string?Filter data by an origin (allowed: mt-web, mt-sfdc, mt-zendesk)
{sortby} (optional)string?Sort data (allowed: searches, clicks, results, date, position, clickspersearch) (default: searches)
{sortorder} (optional)string?Sort direction to be used with sortby (allowed: asc, desc) (default: desc)
{recommendedfocusfilter} (optional)bool?Apply a negative sentiment analysis filter to data (default: false)
{limit} (optional)int?Number of results to return (allowed: 1 - 1000) (default: 100)
{groupids} (optional)string?Comma separated list of group id filters to apply to data (ex: 100,101,202)

Response

The response body media type is application/json; charset=utf-8
{
    "popular": {
        "search": [
            
            // multiple search queries are supported
            {
                "averageClicksPerSearch": "{average-clicks}",
                "averagePosition": "{average-position}",
                "hits" "{hits}",
                "mostRecent": "{most-recent}",
                "query": "{query}",
                "results": "{count.results}",
                "total": "{count.total}",
                "topresult": {
                    "@type": "{top-result/@type}",
                    "@hits" "{top-result/@hits}",                 
                    "page": {top-result/page}                                        
                }                
            }
            ...
        ]
    },
    "volume": {volume}
}
Name Type Description
{average-clicks} double The average count of clicks for the search query
{average-position} double The average position of the clicked search result whenever it matches provided search terms
{hits} int Total count of search result clicks
{most-recent} datetime RFC 1123 representation of the most recent click timestamp
{query} string The search query
{count.results} int The total count of matching results
{count.total} int The total count of times the search query was executed
{top-result/@type} {page, recommended, file} The most clicked search result type
{top-result/@hits} int The most clicked search result total count of clicks
{top-result/page} Page The most clicked search result
{volume} Search Analytics Volume The historical volume of search analytics data
Search Analytics Volume
{
    "clickTotal": "{clicks}",
    "clickthroughRate": "{click-through-rate}",
    "point": [
            
        // multiple points (clicks grouped by day) are supported
        {
            "clicks": "{point/clicks}",
            "date": "{point/date}",
            "searchesClicked": "{point/searchesClicked}",
            "total": "{point/total}"
        }
        ...
    ],
    "searchTotal": "{searches}",
    "searchesClickedTotal": "{searches-clicked}"
}
Name Type Description
{clicks} int The total count of clicked search results
{click-through-rate} double The average click through rate
{searches} int The total count of search queries
{searches-clicked} int The total count of times that a result result was clicked
{point/clicks} int The total count of clicked search results for a day
{point/date} datetime RFC 1123 representation of the day clicks are grouped by
{point/searchesClicked} int The total count of times for a day that a search result was clicked
{point/total} int The total count of search queries for a day

 


Retrieve detailed search analytics for search terms

Applies to:
MindTouch (current)
Role required:
Admin
GET /@api/deki/site/search/analytics/query
cURL
$ curl --request GET --header 'X-Deki-Token: {signature}' https://{hostname}/@api/deki/site/search/analytics/query?dream.out.format=json&query={query}
JavaScript
fetch('https://{hostname}/@api/deki/site/search/analytics/query?dream.out.format=json&query={query}', {
    method: 'GET',
    headers: {
        'X-Deki-Token': '{signature}'
    }
}).then((response) => {
    return response.json();
});

Request

► Expand / Collapse
Parameters
The parameters that are required or accepted by this endpoint (optional parameters can be appended to the endpoint query string)
NameTypeDescription
{hostname}stringThe MindTouch site hostname
{signature}stringThe API Token key or signature
{start} (optional)string?Start range date (format: 'yyyyMMddHHmmss') (default: one month ago)
{end} (optional)string?End range date (format: 'yyyyMMddHHmmss') (default: now)
{query}stringSearch terms to generate analytics for
{bucket} (optional)string?Time period bucket size (allowed: hour, day, week, month, quarter, year) (default: month)
{userfilter} (optional)string?User filter to apply to data (allowed: none, pro, anonymous, community, anonymousorcommunity, communityorpro) (default: none)
{web_widget_embed_id} (optional)string?Filter data by a web widget embed code id
{originfilter} (optional)string?Filter data by an origin (allowed: mt-web, mt-sfdc, mt-zendesk)
{sortby} (optional)string?Sort data (allowed: searches, clicks, results, date, position, clickspersearch) (default: searches)
{sortorder} (optional)string?Sort direction to be used with sortby (allowed: asc, desc) (default: desc)
{recommendedfocusfilter} (optional)bool?Apply a negative sentiment analysis filter to data (default: false)
{limit} (optional)int?Number of results to return (allowed: 1 - 1000) (default: 100)
{groupids} (optional)string?Comma separated list of group id filters to apply to data (ex: 100,101,202)

Response

The response body media type is application/json; charset=utf-8
{
    // "clicks" is an empty string type if no search result clicks are recorded
    "clicks": [
    
        // multiple search result clicks are supported
        "click": {
            "averagePosition": "{average-position}",
            "hits": "{hits}",
            "mostRecent": "{most-recent}",
            "page": {page},
            "type": "{type}"
        }
        ...
    },
    "volume": {volume}
}
Name Type Description
{average-position} double The average position of the clicked search result whenever it matches provided search query
{hits} int Total count of search result clicks
{most-recent} datetime RFC 1123 representation of the most recent click timestamp
{page} Page The search result
{type} {page, recommended, file} The search result type
{volume} Search Analytics Volume The historical volume of search analytics data for provided search query

 


Retrieve page health inspections

Applies to:
MindTouch (current)
Role required:
Author
GET /@api/deki/pages/{pageid}/health
cURL
$ curl --request GET --header 'X-Deki-Token: {signature}' https://{hostname}/@api/deki/pages/{pageid}/health?dream.out.format=json&limit={limit}&offset={offset}
JavaScript
fetch('https://{hostname}/@api/deki/pages/{pageid}/health?dream.out.format=json&limit={limit}&offset={offset}', {
    method: 'GET',
    headers: {
        'X-Deki-Token': '{signature}'
    }
}).then((response) => {
    return response.json();
});

Request

► Expand / Collapse
Parameters
The parameters that are required or accepted by this endpoint (optional parameters can be appended to the endpoint query string)
NameTypeDescription
{hostname}stringThe MindTouch site hostname
{signature}stringThe API Token key or signature
{analyzers} (optional)string?A comma-delimited list of analyzers to include (default: all analyzers)
{severity} (optional)string?A comma-delimited list of the severity level to include in the report (allowed: warning, info, error) (default: all error levels)
{subpages} (optional)bool?Include subpages (default: false)
{limit}intMaximum number of results to return (default: 100)
{offset}intNumber of items to skip (default: 0)

Response

The response body media type is application/json; charset=utf-8
{
    "count": "{count}",
    
    // "inspections" is a list, if multiple inspections returned, or a single inspection object
    "inspections": [
        
        // multiple inspections are supported
        {inspection}
        ...
    ],
    "querycount": "{querycount}"
}
Name Type Description
{querycount} int The total count of fetched inspections
{count} int The count of inspections in response
{inspection} Inspection One inspection in a collection of inspections
Inspection
{
    "@severity": "{severity}",
    "@type": "{type}",
    "message": "{message}",
    "page": {
        "@uri": "{uri}",
        "@id": "{id}",
        "article": "{article}"
    }
}
Name Type Description
{severity} Severity The severity level of the inspection
{analyzer} Analyzer The inspection analyzer
{message} string A description of the inspection and potential corrective actions to take
{uri} uri The page location URI
{id} int Local page id - if the page is exported and imported into a different Expert site, a new local page id will be assigned
{article} (optional) string? Page type
Severity
Name Description
Error The inspection located an issue with the page that is resulting in broken experience
Info The inspection is strictly informational or has located an opportunity within the page to provide a better experience
Warning The inspection located an issue with the page that is resulting in a poor experience
Analyzer
Name Description
Conditional content Lists instances of conditional content on a page
DekiScript Checks for DekiScript programming errors on a page
HTTP reference Checks for insecure links (non-HTTPS) on a page
Permissions Lists user-specific permissions set on a page (group permissions are preferred)
Structure Validates the page for Guided Content Framework page hierarchy compatibility
Template Validates the page for Guided Content Framework page content compatibility

 


Download conditional content report

Applies to:
MindTouch (current)
Role required:
Admin
GET /@api/deki/site/reports/conditionalcontent.csv
cURL
$ curl --request GET --header 'X-Deki-Token: {signature}' https://{hostname}/@api/deki/site/reports/conditionalcontent.csv
JavaScript
fetch('https://{hostname}/@api/deki/site/reports/conditionalcontent.csv?dream.out.format=json', {
    method: 'GET',
    headers: {
        'X-Deki-Token': '{signature}'
    }
}).then((response) => {
    return response.json();
});

Request

► Expand / Collapse
Parameters
The parameters that are required or accepted by this endpoint (optional parameters can be appended to the endpoint query string)
NameTypeDescription
{hostname}stringThe MindTouch site hostname
{signature}stringThe API Token key or signature
{severity} (optional)string?A comma-delimited list of the severity level to include in the report (allowed: warning, info, error) (default: all error levels)

Response

The response body media type is text/csv; charset=utf-8
Field Type Description
Status string Is there a problem with the conditional content at the page location?
  • Info: The conditional content is working as expected
  • Warning: There is a problem with the conditional content block and it needs attention
Location string The page location URL
Message string A description that provides context for the Status field
Expression string The DekiScript or Editor Toolbar code that is powering the conditional content
Details string Detailed explanation of any conditional content warning

 


Download site health inspections

Applies to:
MindTouch (current)
Role required:
Admin
GET /@api/deki/site/reports/health.csv
cURL
$ curl --request GET --header 'X-Deki-Token: {signature}' https://{hostname}/@api/deki/site/reports/health.csv
JavaScript
fetch('https://{hostname}/@api/deki/site/reports/health.csv?dream.out.format=json', {
    method: 'GET',
    headers: {
        'X-Deki-Token': '{signature}'
    }
}).then((response) => {
    return response.json();
});

Request

► Expand / Collapse
Parameters
The parameters that are required or accepted by this endpoint (optional parameters can be appended to the endpoint query string)
NameTypeDescription
{hostname}stringThe MindTouch site hostname
{signature}stringThe API Token key or signature
{analyzers} (optional)string?A comma-delimited list of analyzers to include (default: all analyzers)
{severity} (optional)string?A comma-delimited list of the severity level to include in the report (allowed: warning, info, error) (default: all error levels)

Response

The response body media type is text/csv; charset=utf-8
Field Type Description
Status Severity The severity level of the inspection
Location uri The page location URI
Message string A description of the inspection and potential corrective actions to take
Analyzer Analyzer The inspection analyzer

 


Retrieve site health inspections

Applies to:
MindTouch (current)
Role required:
Admin
GET /@api/deki/site/reports/sitehealth
cURL
$ curl --request GET --header 'X-Deki-Token: {signature}' https://{hostname}/@api/deki/site/reports/sitehealth?dream.out.format=json&limit={limit}&offset={offset}
JavaScript
fetch('https://{hostname}/@api/deki/site/reports/sitehealth?dream.out.format=json&limit={limit}&offset={offset}', {
    method: 'GET',
    headers: {
        'X-Deki-Token': '{signature}'
    }
}).then((response) => {
    return response.json();
});

Request

► Expand / Collapse
Parameters
The parameters that are required or accepted by this endpoint (optional parameters can be appended to the endpoint query string)
NameTypeDescription
{hostname}stringThe MindTouch site hostname
{signature}stringThe API Token key or signature
{analyzers} (optional)string?A comma-delimited list of analyzers to include (default: all analyzers)
{severity} (optional)string?A comma-delimited list of the severity level to include in the report (allowed: warning, info, error) (default: all error levels)
{limit}intMaximum number of results to return (default: 100)
{offset}intNumber of items to skip (default: 0)

Response

The response body media type is application/json; charset=utf-8
{
    "count": "{count}",
    
    // "inspections" is a list, if multiple inspections returned, or a single inspection object
    "inspections": [
        
        // multiple inspections are supported
        {inspection}
        ...
    ],
    "querycount": "{querycount}"
}
Name Type Description
{querycount} int The total count of  inspections
{count} int The count of inspections in response
{inspection} Inspection One inspection in a collection of inspections

 


Knowledge Management

API endpoints for content creation, management, and retrieval.

Export and Import Content

Many knowledge management use cases, such as Content Translation, can be automated through the use of Job API endpoints to export and import content. These endpoints can start content import and export jobs, cancel jobs, and check the status of in-progress jobs. Content import and export requests are sent to a background queue to be processed when resources are available to handle the job. Since concurrent content imports and exports can be stressful on systems during high load, the job queue handles tasks with the following rules:

  • There are no limits on the number of concurrent export jobs that can run per site. However, an export cannot start if an import is in progress.
  • Only one content import job can run concurrently per site.

Completed, failed, or canceled jobs can optionally trigger a notification to be sent to either an email address or a webhook.

Endpoints

Paths

Improve customer experience and learning by integrating guided Paths into any stage of the customer journey.

Endpoints

Retrieve list of site jobs

Applies to:
MindTouch (current)
Role required:
Admin
GET /@api/deki/site/jobs
cURL
$ curl --request GET --header 'X-Deki-Token: {signature}' https://{hostname}/@api/deki/site/jobs
JavaScript
fetch('https://{hostname}/@api/deki/site/jobs?dream.out.format=json', {
    method: 'GET',
    headers: {
        'X-Deki-Token': '{signature}'
    }
}).then((response) => {
    return response.json();
});

Request

► Expand / Collapse
Parameters
The parameters that are required or accepted by this endpoint (optional parameters can be appended to the endpoint query string)
NameTypeDescription
{hostname}stringThe MindTouch site hostname
{signature}stringThe API Token key or signature

Response

The response body is alternatively available in JSON format by appending dream.out.format=json to the request URL
<jobs>

    <!-- multiple jobs are supported -->
    {job}
    ...
</jobs>    
Name Type Description
{job} Job A site job

Retrieve site job

Applies to:
MindTouch (current)
Role required:
Admin
GET /@api/deki/site/jobs/{id}
cURL
$ curl --request GET --header 'X-Deki-Token: {signature}' https://{hostname}/@api/deki/site/jobs/{id}
JavaScript
fetch('https://{hostname}/@api/deki/site/jobs/{id}?dream.out.format=json', {
    method: 'GET',
    headers: {
        'X-Deki-Token': '{signature}'
    }
}).then((response) => {
    return response.json();
});

Request

► Expand / Collapse
Parameters
The parameters that are required or accepted by this endpoint (optional parameters can be appended to the endpoint query string)
NameTypeDescription
{hostname}stringThe MindTouch site hostname
{signature}stringThe API Token key or signature

Response

The response body is alternatively available in JSON format by appending dream.out.format=json to the request URL
Job
<job id="{id}" type="{type}" status="{status}">
    <submitted>{submitted}</submitted>
    <lastmodified>{lastmodified}</lastmodified>
    <data>{data}</data>
    
    <!-- optionally available when job resource is the result of a job submission -->
    {user}
</job>
Name Type Description
{id} string The unique id for this job in UUID v4 format
{type} {export, import, import_test} The type of job
{status} {submitted, in_progress, completed, failed, cancelled} The status of the job
{submitted} datetime ISO 8601 representation for the job submission event timestamp
{lastmodified} datetime ISO 8601 representation for the last time the job status was updated timestamp
{data} xml Structured data (presently not documented in API specification)
{user} (optional) User The user who submitted the job
 Job Types
Job Type Description
export A content export job
import A content import job
import_test A dry run content import job that will only process import manifest and content for warnings and errors, not create or update content
Job Statuses
Job Status Description
submitted Job is in the queue and is not in progress. While the time to begin the job cannot be accurately predicted, under normal system operation we expect the job to begin in under five (5) minutes
in_progress Job is in progress. Once in progress, an export type job can be cancelled, however an import or import_test type job cannot be cancelled
completed Job is complete and system sends notification and optional logs to the configured email address or webhook
failed Job has failed and system sends notification and error logs to the configured email address or webhook
cancelled Job has been cancelled and system sends notification and optional logs to the configured email address or webhook

Cancel submitted site job

Applies to:
MindTouch (current)
Role required:
Admin
POST /@api/deki/site/jobs/{id}/cancel
cURL
$ curl --request POST --header 'X-Deki-Token: {signature}' https://{hostname}/@api/deki/site/jobs/{id}/cancel --data {body}
JavaScript
fetch('https://{hostname}/@api/deki/site/jobs/{id}/cancel?dream.out.format=json', {
    method: 'POST',
    headers: {
        'X-Deki-Token': '{signature}'
    },
    body: '{body}'
}).then((response) => {
    return response.json();
});

Request

► Expand / Collapse
Parameters
The parameters that are required or accepted by this endpoint (optional parameters can be appended to the endpoint query string)
NameTypeDescription
{hostname}stringThe MindTouch site hostname
{signature}stringThe API Token key or signature
{body}application/xml; charset=utf-8The request payload that is required by this endpoint
Body
The request body media type is application/xml; charset=utf-8

Response

The response body is alternatively available in JSON format by appending dream.out.format=json to the request URL
{job}
Name Type Description
{job} Job A site job

Schedule a site export job

Applies to:
MindTouch (current)
Role required:
Admin
POST /@api/deki/site/jobs/export
cURL
$ curl --request POST --header 'X-Deki-Token: {signature}' https://{hostname}/@api/deki/site/jobs/export --data {body}
JavaScript
fetch('https://{hostname}/@api/deki/site/jobs/export?dream.out.format=json', {
    method: 'POST',
    headers: {
        'X-Deki-Token': '{signature}'
    },
    body: '{body}'
}).then((response) => {
    return response.json();
});

Request

► Expand / Collapse
Parameters
The parameters that are required or accepted by this endpoint (optional parameters can be appended to the endpoint query string)
NameTypeDescription
{hostname}stringThe MindTouch site hostname
{signature}stringThe API Token key or signature
{body}application/xml; charset=utf-8The request payload that is required by this endpoint
Body
The request body media type is application/xml; charset=utf-8
<job>
    <notification>
    
        <!-- only one notification value is required: email or url -->
        <email>{email}</email>
        <url>{url}</url>
    </notification>
    <pages>
        <!-- only one page is required, but multiple pages are allowed in order to export more than one page hierarchy -->
        <page includesubpages="{includesubpages}">
            <path>{page/path}</path>
        </page>   
        <page includesubpages="{includesubpages}">
            <path>{page/path}</path>
        </page>
        ...
    </pages>
</job>
Name Type Description
{email} (optional) string? The email address to receive notifications
{url} (optional) string? The webhook URL to receive HTTP POST notifications
{includesubpages} (optional) bool? Should the entire sub-page hierarchy of the exported page location be exported? (default: false)
{page/path} string The relative page URL to export (ex: foo/bar/baz)

Response

The response body is alternatively available in JSON format by appending dream.out.format=json to the request URL
{job}
Name Type Description
{job} Job A site job

Schedule a site import job

Applies to:
MindTouch (current)
Role required:
Admin
POST /@api/deki/site/jobs/import
cURL
$ curl --request POST --header 'X-Deki-Token: {signature}' https://{hostname}/@api/deki/site/jobs/import --data {body}
JavaScript
fetch('https://{hostname}/@api/deki/site/jobs/import?dream.out.format=json', {
    method: 'POST',
    headers: {
        'X-Deki-Token': '{signature}'
    },
    body: '{body}'
}).then((response) => {
    return response.json();
});

Request

► Expand / Collapse
Parameters
The parameters that are required or accepted by this endpoint (optional parameters can be appended to the endpoint query string)
NameTypeDescription
{hostname}stringThe MindTouch site hostname
{signature}stringThe API Token key or signature
{dryrun} (optional)bool?Perform a dry run of the import to diagnose potential content problems (default: false)
{body}application/xml; charset=utf-8The request payload that is required by this endpoint
Body
The request body media type is application/xml; charset=utf-8
<job>
    <notification>
    
        <!-- only one notification value is required: email or url -->
        <email>{email}</email>
        <url>{url}</url>
    </notification>
    <archive>
        <url>{archive}</url>
    </archive>
    
    <!-- optional configurations -->
    <options>
        <option name="dryrun">{dryrun}</option>
    </options>
</job>
Name Type Description
{email} (optional) string? The email address to receive notifications
{url} (optional) string? The webhook URL to receive HTTP POST notifications
{archive} string Public URL to content import archive
{dryrun} (optional) bool? Perform a dry run of the import to diagnose potential content problems (default: false)

Response

The response body is alternatively available in JSON format by appending dream.out.format=json to the request URL
{job}
Name Type Description
{job} Job A site job

Set site job status

Applies to:
MindTouch (current)
Role required:
Admin
PUT /@api/deki/site/jobs/{id}/status/{status}
cURL
$ curl --request PUT --header 'X-Deki-Token: {signature}' https://{hostname}/@api/deki/site/jobs/{id}/status/{status} --data {body}
JavaScript
fetch('https://{hostname}/@api/deki/site/jobs/{id}/status/{status}?dream.out.format=json', {
    method: 'PUT',
    headers: {
        'X-Deki-Token': '{signature}'
    },
    body: '{body}'
}).then((response) => {
    return response.json();
});

Request

► Expand / Collapse
Parameters
The parameters that are required or accepted by this endpoint (optional parameters can be appended to the endpoint query string)
NameTypeDescription
{hostname}stringThe MindTouch site hostname
{signature}stringThe API Token key or signature
{data} (optional)string?Optional: data object
{body}application/xml; charset=utf-8The request payload that is required by this endpoint
Body
The request body media type is application/xml; charset=utf-8

Response

The response body is alternatively available in JSON format by appending dream.out.format=json to the request URL
{job}
Name Type Description
{job} Job A site job

Job notifications

Completed, failed, or canceled jobs can optionally trigger a notification to be sent to either an email address or a webhook.

Email

The email notification will contain the following information in the received message:

Webhook

A public webhook (without any authorization requirements) can be configured to receive an HTTP POST message from Expert with the following JSON-formatted payload:

{
    "@id": "{id}",
    "@type": "{type}",
    "@status": "{status}",
    "site": "{hostname}",
    "log": {
        "csv": "{log}"
    },
    "uri": "{archive}"
}
Name Type Description
{id} string The unique id for this job in UUID v4 format
{type} {export, import} The type of job
{status} {completed, failed, cancelled} The status of the job
{hostname} string The Expert site hostname where the job was queued
{log} (optional) string A URL to download any generated error or warning logs
{archive} (optional) string If a successful content export job, a URL to the exported content archive to download 

Error and Warning Logs

Error logs are available if a content import or export job fails or is canceled. Warning logs may be available if the job is successful but non-critical issues were detected during processing. The log format is CSV with the following columns in the header row:

Header Description
DataId A unique, deterministic id for the piece of data, referenced in the package.xml file, that triggered the warning or error (pages, attachments, page permissions, etc)
PagePath The relative page URL that the data is associated with
WarningType The type of error or warning message 
Message An explanation of the error or warning
Message Types

The message type value is available in the WarningType header row column.

Message Type (WarningType) Job Type Description
UserGrantsPresent export Page permissions granted to users will not be exported or imported
DekiScriptErrorDetected export Page content contains invalid DekiScript source
NonPortableLinkDetected export Page content contains link to local file id (without filename)
AnalyzerFailedToRun export Page content could not be analyzed in order to prepare content for export
ContentParsingErrorDetected export Page content resulted in a parsing error that is described further in log message
PageOverviewWithScriptedContentDetected export Page summary can only be plain text and cannot contain DekiScript source 
IgnoredSearchRecommendation export Page that is associated with an exported search recommendation was not part of the content export manifest
IgnoredContextMapping export Page that is mapped to an exported content id was not part of the content export manifest
FailedToImportItem import See message for import exception details
PageDraftDetected export The draft for this page will not be exported
IgnoredInvalidLearningPathName export Invalid guided path name (path names can only contain letters, dashes, and hyphens)
IgnoredLearningPathPage export Page that is associated with a guided path was not part of the content export manifest
IgnoredLearningPathPages export Pages that are associated with a guided path were not part of the content export manifest
PageCreationConflictsWithExistingPage import The page guid between a page location in the export manifest and the same location in the destination Expert site do not match
PageMoveConflictsWithExistingPage import Could not move page because a page with the same title already exists
PageMoveConflictsWithExistingPageOutsideSubHierarchy import In order to sync page hierarchies, a page from outside the destination Expert site page hierarchy needs to be moved to a location inside the destination Expert site page hierarchy and the page location already exists
PageMoveTargetParentFailedToImport import Parent page of move destination failed so move cannot proceed
SkippingPageCreationBecauseParentPagePreviouslySkipped import Page cannot be imported because the parent page was not imported
SkippingPageCreationBecauseItWasPreviouslyDeleted import Page to be created upon import was previously deleted in the destination Expert site
SkippingPageTagsBecausePagePreviouslySkipped import Page was skipped so any associated resources were also skipped
SkippingPageFileBecausePagePreviouslySkipped import Page was skipped so any associated resources were also skipped
SkippingPagePropertyBecausePagePreviouslySkipped import Page was skipped so any associated resources were also skipped
SkippingFilePropertyBecausePagePreviouslySkipped import Page was skipped so any associated resources were also skipped
SkippingPagePermissionsBecausePagePreviouslySkipped import Page was skipped so any associated resources were also skipped
MissingPageInImport import Page is defined in export manifest but is missing from the archive

Retrieve list of learning paths

Applies to:
MindTouch (current)
Role required:
N/A
GET /@api/deki/learning-paths
cURL
$ curl --request GET --header 'X-Deki-Token: {signature}' https://{hostname}/@api/deki/learning-paths
JavaScript
fetch('https://{hostname}/@api/deki/learning-paths?dream.out.format=json', {
    method: 'GET',
    headers: {
        'X-Deki-Token': '{signature}'
    }
}).then((response) => {
    return response.json();
});

Request

► Expand / Collapse
Parameters
The parameters that are required or accepted by this endpoint (optional parameters can be appended to the endpoint query string)
NameTypeDescription
{hostname}stringThe MindTouch site hostname
{signature}stringThe API Token key or signature

Response

The response body is alternatively available in JSON format by appending dream.out.format=json to the request URL
<learning-paths count="{count}" href="https://{hostname}/@api/deki/learning-paths">

    <!-- multiple learning paths are supported -->
    {learning-path}
    ...
</learning-paths>
Name Type Description
{hostname} string The Expert site hostname
{count} int The total number of site learning paths
{learning-path} Learning Path One of a collection of site learning paths

 


Retrieve learning path

Applies to:
MindTouch (current)
Role required:
N/A
GET /@api/deki/learning-paths/{pathid}
cURL
$ curl --request GET --header 'X-Deki-Token: {signature}' https://{hostname}/@api/deki/learning-paths/{pathid}
JavaScript
fetch('https://{hostname}/@api/deki/learning-paths/{pathid}?dream.out.format=json', {
    method: 'GET',
    headers: {
        'X-Deki-Token': '{signature}'
    }
}).then((response) => {
    return response.json();
});

Request

► Expand / Collapse
Parameters
The parameters that are required or accepted by this endpoint (optional parameters can be appended to the endpoint query string)
NameTypeDescription
{hostname}stringThe MindTouch site hostname
{signature}stringThe API Token key or signature
{pathid}stringThe learning path id prefixed with "="

Response

The response body is alternatively available in JSON format by appending dream.out.format=json to the request URL
Learning Path
<learning-path id="{pathid}" revision="{revision}" href="https://{hostname}/@api/deki/learning-paths/{pathid}">
    <title>{title}</title>
    <summary>{summary}</summary>
    <category>{category}</category>
    <date.modified>{date.modified}</date.modified>
    <uri.ui>https://success.mindtouch.com/@go/path/{id}</uri.ui>
    <pages count="{pages.count}" href="https://{hostname}/@api/deki/learning-paths/{pathid}/pages">
        {page}
    </pages>
</learning-path>
Name Type Description
{hostname} string The Expert site hostname
{pathid} string The learning path id
{revision} int The learning path revision
{summary} string A description of the learning path and what it's used for
{category} string The learning path category used for filtering or grouping learning paths for organizational needs
{date.modified} datetime ISO 8601 representation of the learning path's last updated timestamp
{pages.count} int The total number of pages in this learning path
{page} Page One of a collection of pages, ordered sequentially in the learning path

 


Retrieve learning path pages

Applies to:
MindTouch (current)
Role required:
N/A
GET /@api/deki/learning-paths/{pathid}/pages
cURL
$ curl --request GET --header 'X-Deki-Token: {signature}' https://{hostname}/@api/deki/learning-paths/{pathid}/pages
JavaScript
fetch('https://{hostname}/@api/deki/learning-paths/{pathid}/pages?dream.out.format=json', {
    method: 'GET',
    headers: {
        'X-Deki-Token': '{signature}'
    }
}).then((response) => {
    return response.json();
});

Request

► Expand / Collapse
Parameters
The parameters that are required or accepted by this endpoint (optional parameters can be appended to the endpoint query string)
NameTypeDescription
{hostname}stringThe MindTouch site hostname
{signature}stringThe API Token key or signature
{pathid}stringThe learning path id prefixed with "="

Response

The response body is alternatively available in JSON format by appending dream.out.format=json to the request URL
<pages count="{pages.count}" href="https://{hostname}/@api/deki/learning-paths/{pathid}/pages">

    <!-- multiple pages are supported -->
    {page}
    ...
</pages> 
Name Type Description
{hostname} string The Expert site hostname
{pathid} int The learning path id
{page} Page One of a collection of pages, ordered sequentially in the learning path

 


Retrieve learning path page

Applies to:
MindTouch (current)
Role required:
N/A
GET /@api/deki/learning-paths/{pathid}/pages/{pageid}
cURL
$ curl --request GET --header 'X-Deki-Token: {signature}' https://{hostname}/@api/deki/learning-paths/{pathid}/pages/{pageid}
JavaScript
fetch('https://{hostname}/@api/deki/learning-paths/{pathid}/pages/{pageid}?dream.out.format=json', {
    method: 'GET',
    headers: {
        'X-Deki-Token': '{signature}'
    }
}).then((response) => {
    return response.json();
});

Request

► Expand / Collapse
Parameters
The parameters that are required or accepted by this endpoint (optional parameters can be appended to the endpoint query string)
NameTypeDescription
{hostname}stringThe MindTouch site hostname
{signature}stringThe API Token key or signature
{pathid}stringThe learning path id prefixed with "="
{pageid}stringEither an integer page id, "home", ":" followed by a page guid, or "=" followed by a double uri-encoded page title

Response

The response body is alternatively available in JSON format by appending dream.out.format=json to the request URL
{page}
Name Type Description
{page} Page A learning path page

 


Search

API endpoints for leveraging the MindTouch search engine.

Intelligent Search

Intelligent Search API endpoints extend the search experience, and search analytics tracking, into new content delivery channels such as chatbots, CRM's, and IoT devices.

Endpoints

Enterprise and Federated Search

OpenSearch provides the capability to publish and consume search results in a format commonly supported by Enterprise and Federated Search technologies.

Endpoints

Search Recommendations

Search Recommendation API endpoints can be leveraged to automate the creation, modification, and removal of search results, positioned as top results when exact search terms are matched.

Endpoints

Search the site index with analytical tracking

Applies to:
All MindTouch Versions
Role required:
N/A
GET /@api/deki/site/query
cURL
$ curl --request GET --header 'X-Deki-Token: {signature}' https://{hostname}/@api/deki/site/query?q={q}
JavaScript
fetch('https://{hostname}/@api/deki/site/query?dream.out.format=json&q={q}', {
    method: 'GET',
    headers: {
        'X-Deki-Token': '{signature}'
    }
}).then((response) => {
    return response.json();
});

Request

► Expand / Collapse
Parameters
The parameters that are required or accepted by this endpoint (optional parameters can be appended to the endpoint query string)
NameTypeDescription
{hostname}stringThe MindTouch site hostname
{signature}stringThe API Token key or signature
{q}stringSearch query (search terms or advanced syntax)
{parser} (optional){bestguess|term|lucene}?The parser to use for the query (default: bestguess)
{notrack} (optional)bool?Disable analytics query tracking (default: false)
{queryid} (optional)ulong?Query tracking id returned by original query result (used for paging/changing sort order)
{sessionid} (optional)string?Query tracking session id
{previousqueryid} (optional)ulong?Query tracking id of previous query, if this is a follow-up query
{limit} (optional)int?Maximum number of items to retrieve (allowed: a positive number) (default: 25)
{offset} (optional)int?Number of items to skip (allowed: a positive number or 0 to not skip any) (default: 0)
{sortby} (optional){rank, title, modified}?Sort field. Prefix value with '-' to sort descending (default: -rank)
{constraint} (optional)string?Additional search constraints (ex: language:en-us AND type:wiki) (default: none)
{pathancestors} (optional)string?Comma separated list of path ancestors to filter search results. Non-delimiting commas in path must be encoded (default: none)
{tags} (optional)string?Comma separated list of tags to filter search results (default: none)
{classifications} (optional)string?Comma separated list of classifications to filter search results (default: none)
{types} (optional)string?Comma separated list of document types to filter search results (default: none)
{namespaces} (optional)string?Namespace for filtering search results (default: none)
{explain} (optional)bool?Include ranking details (default: false)
{includeaggs} (optional)bool?Include aggregations (default: false)
{recommendations} (optional)bool?Include recommendations (default: true)
{recommendedids} (optional)string?Comma separated list of page ids for recommended results (default: none)
{summarypath} (optional)string?Path to calculate result count summary (default: none)
{aggpath} (optional)string?Path to calculate result count summary (default: none)
{metrics} (optional)bool?Include view count and word count metrics in results (default false)

Response

The response body is alternatively available in JSON format by appending dream.out.format=json to the request URL
Intelligent Search Results

This API endpoint response, along with the API endpoint request parameters, contains the necessary information to provide a filtered and faceted search experience with search analytics tracking.

<search ranking="adaptive" queryid="{queryid}" sessionid="{sessionid}" querycount="{querycount}" count.recommendations="{count.recommendations}" count="{count}">

    <!-- multiple search recommendations can be returned depending on site search recommendation configuration -->
    <recommendations id="{recommendations/@id}"/>
    ...
    
    <!-- search results represent pages, recommended pages, or files -->
    <result>
        <id>{id}</id>
        <uri>{uri}</uri>
        <uri.track>{uri.track}</uri.track>
        <rank>{rank}</rank>
        <title>{title}</title>
        
        <!-- if {type} = page: page is the location of content that best matches search terms based on the search algorithim -->
        <!-- if {type} = recommended: page is the configured location that matches exact search terms -->
        <!-- if {type} = file: page is the location of the file attachment that contains content that best matches search terms based on the search algorithim -->
        <page>
            <rating score="{page/rating/@score}" count="{page/rating/@count}"/>
            <title>{page/title}</title>
            <path>{page/path}</path>
            <uri.ui>{page/uri.ui}</path>
        </page>
        <author>{author}</author>
        
        <!-- if {type} = page / recommended: {preview} is the provided page summary or extracted page summary from page content -->
        <!-- if {type} = file: {preview} is extracted from file attachment content -->
        <preview>{preview}</preview>
        <content>{preview}</content>
        <date.modified>{date.modified}</date.modified>   
        <type>{type}</type>
        <mime>{mime}</mime>
        <tag>{tag}</tag>
        
        <!-- if {metrics} = true -->
        <metric.views>{metric.views}</metric.views>
        <metric.charcount>{metric.charcount}</metric.charcount>
    </result>
    ...
        
    <!-- if {includeaggs} = true -->
    <!-- aggregates are used to build filters and facets on the Intelligent Search UI (ex: https://example.com/Special:Search) -->
    <aggs>
        <pages>
            <pages count="{aggs/pages/@count}" id="{aggs/pages/@id}">
                <value>{aggs/pages/value}</value>
                <title>{aggs/pages/title}</title>
            </pages>
            ...
        </pages>
        <articles>
            <articles count="{aggs/articles/@count}">
                <value>{aggs/articles/value}</value>
            </articles>
            ...
        </articles>            
        <custom_classifications>
            <custom_classifications count="{aggs/custom_classifications/@id}">
                <value>{aggs/custom_classifications/classification}</value>
                <custom_classifications>
                    <custom_classifications count="{aggs/custom_classifications/@count}">
                    <value>{aggs/custom_classifications/value}</value>
                </custom_classifications>
            </custom_classifications>
            ...
        </custom_classifications>
    </aggs>
</search>
Name Type Description
{queryid} string Unique search query id for tracking or refining search results for a query (included in search analytics tracking URL)
{sessionid} string Unique search session id (included in search analytics tracking URL)
{querycount} int Total count of resources matched by search query (ignoring limit and offset)
{count.recommendations} int Total count of recommended search results
{count} int Count of resources matched by search query with requested limit and offset
{recommendations/@id} int A page id of a recommended search result
{id} int The id of the resource content that matched the search query
{uri} uri The resource location URL that matched the search query
{uri.track} uri The search analytics tracking beacon URL to request when the search result is selected or clicked
{rank} float Relative search ranking to order search results from most relevant to least
{title} string The search result display title (contextual to resource: page display title or filename)
{page/rating/@score} int The current rating score of the search result page
{page/rating/@count} int The number of times the search result page has been rated
{page/title} string The search result page display title
{page/path} string The search result page hierarchy location
{page/uri.ui} string The search result page location URL
{author} string Username of the author who last modified the resource that matched the search query
{preview} string Search result preview content
{date.modified} datetime ISO 8601 representation of the resource's last modification timestamp
{type} {page, recommended, file} The search result type
{mime} string The resource media type
{tag} string Whitespace separated listed of search result page tags, classifications, and page type
{metric.views} int The total count of resource views
{metric.charcount} int The total count of characters in resource content
{aggs/pages/@count} int The number of search results under the location filter option
{aggs/pages/@id} int The page id of the location filter option
{aggs/pages/value} string The name of the location filter option
{aggs/pages/title} string The display title of the location filter option
{aggs/articles/@count} int The number of search results under the page type filter option
{aggs/articles/value} string The name of the page type filter option
{aggs/custom_classifications/classification} string The custom classification filter option classification name
{aggs/custom_classifications/@count} int The number of search results under the custom classification filter option
{aggs/custom_classifications/value} string The custom classification filter option classification value

Search the site index with OpenSearch

Applies to:
All MindTouch Versions
Role required:
N/A
GET /@api/deki/site/opensearch
cURL
$ curl --request GET --header 'X-Deki-Token: {signature}' https://{hostname}/@api/deki/site/opensearch?q={q}
JavaScript
fetch('https://{hostname}/@api/deki/site/opensearch?dream.out.format=json&q={q}', {
    method: 'GET',
    headers: {
        'X-Deki-Token': '{signature}'
    }
}).then((response) => {
    return response.json();
});

Request

► Expand / Collapse
Parameters
The parameters that are required or accepted by this endpoint (optional parameters can be appended to the endpoint query string)
NameTypeDescription
{hostname}stringThe MindTouch site hostname
{signature}stringThe API Token key or signature
{format} (optional){rss | atom}?Search output format (rss | atom) default: atom
{q}stringSearch terms
{limit} (optional)string?Maximum number of items to retrieve (allowed: a positive number or 'all' to retrieve all items) (default: 100)
{offset} (optional)int?Number of items to skip (allowed: a positive number or 0 to not skip any) (default: 0)
{sortby} (optional){score, title, date, size, wordcount, rating.score, rating.count}?Sort field. Prefix value with '-' to sort descending. default: -score
{constraint} (optional)string?Additional search constraint (ex: language:en-us AND type:wiki) default: none
{pathancestors} (optional)string?Comma separated list of path ancestors to filter search results (default: none)
{tags} (optional)string?Comma separated list of tags to filter search results (default: none)
{classifications} (optional)string?Comma separated list of classifications to filter search results (default: none)
{types} (optional)string?Comma separated list of document types to filter search results (default: none)
{namespaces} (optional)string?Namespace for filtering search results (default: none)
{parser} (optional){bestguess|term|filename|lucene}?The parser to use for the query (default: bestguess)
{nocache} (optional)bool?Use caching search path (better for paging results) (default: false)
{engine} (optional){lucene | es}?Search engine (lucene | es) default: lucene

Response

The response body is alternatively available in JSON format by appending dream.out.format=json to the request URL
OpenSearch 1.1 Response

The Expert API returns OpenSearch data in standard OpenSearch 1.1 RSS 2.0 or Atom 1.0 schema, depending on the value of the {format} request parameter. In addition to standard schema, the response includes custom XML elements (xmlns:mt="http://services.mindtouch.com/deki/draft/2007/06/luceneindex").

<{root} xmlns:mt="http://services.mindtouch.com/deki/draft/2007/06/luceneindex">
    <{result}>
        <mt:path>{path}</mt:path>
        <mt:id.{type}>{id}</mt:id.{type}>
        
        <!-- if {type} = page: page is the location of content that best matches search terms based on the search algorithim -->
        <!-- if {type} = file: page is the location of the file attachment that contains content that best matches search terms based on the search algorithim -->
        <mt:page id="{page/@id}" href="https://{hostname}/@api/deki/pages/{page/@id}" path="{path}" title="{title}" />
    </{result}>
    ...
</{root}>
Name Type Description
{root} {feed, rss}
  • If {format} = atom, then {root} = feed
  • If {format} = rss, then {root} = rss
{result} {entry, item}
  • If {format} = atom, then {result} = entry
  • If {format} = rss, then {result} = item
{hostname} string The Expert site hostname
{path} string The search result page hierarchy location
{type} {page, file} The search result type
{id} int The id of the resource content that matched the search query
{page/@id} int The page id of the page hierarchy location
{title} string The search result page display title

Retrieve the OpenSearch description document

Applies to:
All MindTouch Versions
Role required:
N/A
GET /@api/deki/site/opensearch/description
cURL
$ curl --request GET --header 'X-Deki-Token: {signature}' https://{hostname}/@api/deki/site/opensearch/description
JavaScript
fetch('https://{hostname}/@api/deki/site/opensearch/description?dream.out.format=json', {
    method: 'GET',
    headers: {
        'X-Deki-Token': '{signature}'
    }
}).then((response) => {
    return response.json();
});

Request

► Expand / Collapse
Parameters
The parameters that are required or accepted by this endpoint (optional parameters can be appended to the endpoint query string)
NameTypeDescription
{hostname}stringThe MindTouch site hostname
{signature}stringThe API Token key or signature

Response

The response body is alternatively available in JSON format by appending dream.out.format=json to the request URL
OpenSearch 1.1 Description

The Expert API returns OpenSearch description data in the standard OpenSearch 1.1 Description XML schema. In addition to the standard schema, the API endpoint response also includes a reference to the OpenSearch 1.1 Suggestions extension.

<OpenSearchDescription xmlns="http://a9.com/-/spec/opensearch/1.1/">
    <Url type="application/x-suggestions+json" template="{uri}" />
</OpenSearchDescription>
Name Type Description
{uri} uri The API endpoint location to return OpenSearch 1.1 Suggestions extension data

Search the site index for suggestions with OpenSearch

Applies to:
All MindTouch Versions
Role required:
N/A
GET /@api/deki/site/opensearch/suggestions
cURL
$ curl --request GET --header 'X-Deki-Token: {signature}' https://{hostname}/@api/deki/site/opensearch/suggestions?dream.out.format=json&q={q}
JavaScript
fetch('https://{hostname}/@api/deki/site/opensearch/suggestions?dream.out.format=json&q={q}', {
    method: 'GET',
    headers: {
        'X-Deki-Token': '{signature}'
    }
}).then((response) => {
    return response.json();
});

Request

► Expand / Collapse
Parameters
The parameters that are required or accepted by this endpoint (optional parameters can be appended to the endpoint query string)
NameTypeDescription
{hostname}stringThe MindTouch site hostname
{signature}stringThe API Token key or signature
{q}stringSearch terms
{sortby} (optional){score, title, date, size, wordcount, rating.score, rating.count}?Sort field. Prefix value with '-' to sort descending. default: -score
{constraint} (optional)string?Additional search constraint (ex: language:en-us AND type:wiki) default: none
{pathancestors} (optional)string?Comma separated list of path ancestors to filter search results (default: none)
{tags} (optional)string?Comma separated list of tags to filter search results (default: none)
{classifications} (optional)string?Comma separated list of classifications to filter search results (default: none)
{types} (optional)string?Comma separated list of document types to filter search results (default: none)
{namespaces} (optional)string?Namespace for filtering search results (default: none)
{engine} (optional){lucene | es}?Search engine (lucene | es) default: lucene

Response

The response body media type is application/json; charset=utf-8
OpenSearch 1.1 Suggestions

The Expert API returns OpenSearch suggestion data in the OpenSearch 1.1 Suggestions extension JSON schema.


Remove search recommendation

Applies to:
All MindTouch Versions
Role required:
Admin
DELETE /@api/deki/site/query/recommendations/{id}
cURL
$ curl --request DELETE --header 'X-Deki-Token: {signature}' https://{hostname}/@api/deki/site/query/recommendations/{id}
JavaScript
fetch('https://{hostname}/@api/deki/site/query/recommendations/{id}?dream.out.format=json', {
    method: 'DELETE',
    headers: {
        'X-Deki-Token': '{signature}'
    }
}).then((response) => {
    return response.json();
});

Request

► Expand / Collapse
Parameters
The parameters that are required or accepted by this endpoint (optional parameters can be appended to the endpoint query string)
NameTypeDescription
{hostname}stringThe MindTouch site hostname
{signature}stringThe API Token key or signature
{id}intIdentifies a search recommendation by id

Response

The API endpoint does not respond with a message body

Retrieve list of search recommendations

Applies to:
All MindTouch Versions
Role required:
Admin
GET /@api/deki/site/query/recommendations
cURL
$ curl --request GET --header 'X-Deki-Token: {signature}' https://{hostname}/@api/deki/site/query/recommendations
JavaScript
fetch('https://{hostname}/@api/deki/site/query/recommendations?dream.out.format=json', {
    method: 'GET',
    headers: {
        'X-Deki-Token': '{signature}'
    }
}).then((response) => {
    return response.json();
});

Request

► Expand / Collapse
Parameters
The parameters that are required or accepted by this endpoint (optional parameters can be appended to the endpoint query string)
NameTypeDescription
{hostname}stringThe MindTouch site hostname
{signature}stringThe API Token key or signature
{limit} (optional)int?Maximum number of items to retrieve (allowed: a positive number) (default: 25)
{offset} (optional)int?Number of items to skip (allowed: a positive number or 0 to not skip any) (default: 0)

Response

The response body is alternatively available in JSON format by appending dream.out.format=json to the request URL
<recommendations count="{count}" querycount="{totalcount}" totalcount="{totalcount}">

    <!-- multiple search recommendations are supported -->
    {recommendation}
    ...
</recommendations>
Name Type Description
{count} int Count of search recommendations in response
{totalcount} int Total count of search recommendations (ignoring limit and offset)
{recommendation} Search Recommendation An active search recommendation

 


Retrieve search recommendation

Applies to:
All MindTouch Versions
Role required:
Admin
GET /@api/deki/site/query/recommendations/{id}
cURL
$ curl --request GET --header 'X-Deki-Token: {signature}' https://{hostname}/@api/deki/site/query/recommendations/{id}
JavaScript
fetch('https://{hostname}/@api/deki/site/query/recommendations/{id}?dream.out.format=json', {
    method: 'GET',
    headers: {
        'X-Deki-Token': '{signature}'
    }
}).then((response) => {
    return response.json();
});

Request

► Expand / Collapse
Parameters
The parameters that are required or accepted by this endpoint (optional parameters can be appended to the endpoint query string)
NameTypeDescription
{hostname}stringThe MindTouch site hostname
{signature}stringThe API Token key or signature
{id}intIdentifies a search recommendation by id

Response

The response body is alternatively available in JSON format by appending dream.out.format=json to the request URL
Search Recommendation
<recommendation id="{id}">
    <title>{title}</title>
    <pageid>{pageid}</pageid>
    
    <!-- example {terms}: foo bar baz -->
    <terms>{terms}</terms>
    <page.title>{page.title}</page.title>
    <page.path>{path}</page.path>
</recommendation> 
Name Type Description
{id} int Local search recommendation id - if the search recommendation is exported and imported into a different Expert site, a new local search recommendation id will be assigned
{title} (optional) string? The recommended search result title (overrides recommended search page title in the Intelligent Search API endpoint response
{pageid} int The search result page id
{page.title} string The search result page display title
{page.path} string The search result page hierarchy location
{terms} string Whitespace separated search terms to match, in order to retrieve recommended search result

Create search recommendation

Applies to:
All MindTouch Versions
Role required:
Admin
POST /@api/deki/site/query/recommendations
cURL
$ curl --request POST --header 'X-Deki-Token: {signature}' https://{hostname}/@api/deki/site/query/recommendations --data {body}
JavaScript
fetch('https://{hostname}/@api/deki/site/query/recommendations?dream.out.format=json', {
    method: 'POST',
    headers: {
        'X-Deki-Token': '{signature}'
    },
    body: '{body}'
}).then((response) => {
    return response.json();
});

Request

► Expand / Collapse
Parameters
The parameters that are required or accepted by this endpoint (optional parameters can be appended to the endpoint query string)
NameTypeDescription
{hostname}stringThe MindTouch site hostname
{signature}stringThe API Token key or signature
{body}application/xml; charset=utf-8The request payload that is required by this endpoint
Body
The request body media type is application/xml; charset=utf-8
<recommendation>
    <title>{title}</title>
    <pageid>{pageid}</pageid>
    
    <!-- example {terms}: foo bar baz -->
    <terms>{terms}</terms>
</recommendation> 
Name Type Description
{title} (optional) string The recommended search result title (overrides recommended search page title in the Intelligent Search API endpoint response
{pageid} int The search result page id
{terms} string Whitespace separated search terms to match, in order to retrieve recommended search result

Response

The response body is alternatively available in JSON format by appending dream.out.format=json to the request URL
{recommendation}
Name Type Description
{recommendation} Search Recommendation An active search recommendation

 


Update search recommendation

Applies to:
All MindTouch Versions
Role required:
Admin
PUT /@api/deki/site/query/recommendations/{id}
cURL
$ curl --request PUT --header 'X-Deki-Token: {signature}' https://{hostname}/@api/deki/site/query/recommendations/{id} --data {body}
JavaScript
fetch('https://{hostname}/@api/deki/site/query/recommendations/{id}?dream.out.format=json', {
    method: 'PUT',
    headers: {
        'X-Deki-Token': '{signature}'
    },
    body: '{body}'
}).then((response) => {
    return response.json();
});

Request

► Expand / Collapse
Parameters
The parameters that are required or accepted by this endpoint (optional parameters can be appended to the endpoint query string)
NameTypeDescription
{hostname}stringThe MindTouch site hostname
{signature}stringThe API Token key or signature
{id}intIdentifies a search recommendation by id
{body}application/xml; charset=utf-8The request payload that is required by this endpoint
Body
The request body media type is application/xml; charset=utf-8
<recommendation>
    <title>{title}</title>
    <pageid>{pageid}</pageid>
    
    <!-- example {terms}: foo bar baz -->
    <terms>{terms}</terms>
</recommendation> 
Name Type Description
{title} (optional) string The recommended search result title (overrides recommended search page title in the Intelligent Search API endpoint response
{pageid} int The search result page id
{terms} string Whitespace separated search terms to match, in order to retrieve recommended search result

Response

The response body is alternatively available in JSON format by appending dream.out.format=json to the request URL
{recommendation}
Name Type Description
{recommendation} Search Recommendation An active search recommendation

 

 


Integrations

API endpoints for extending MindTouch behavior into new applications and systems.

Tokens

In order to keep track of or audit integrations, Token API endpoints can be used to inspect the API Tokens or Authorizations provisioned on an Expert site. For enhanced security, Token API endpoints never return Server API Token or OAuth API Token secrets.

Endpoints

Touchpoints

Touchpoints, referred to as Web Widgets in the Expert API, can be inspected or audited using the Web Widget API endpoints.

Endpoints

Retrieve list of API tokens

Applies to:
All MindTouch Versions
Role required:
Admin
GET /@api/deki/site/developer-tokens
cURL
$ curl --request GET --header 'X-Deki-Token: {signature}' https://{hostname}/@api/deki/site/developer-tokens
JavaScript
fetch('https://{hostname}/@api/deki/site/developer-tokens?dream.out.format=json', {
    method: 'GET',
    headers: {
        'X-Deki-Token': '{signature}'
    }
}).then((response) => {
    return response.json();
});

Request

► Expand / Collapse
Parameters
The parameters that are required or accepted by this endpoint (optional parameters can be appended to the endpoint query string)
NameTypeDescription
{hostname}stringThe MindTouch site hostname
{signature}stringThe API Token key or signature

Response

The response body is alternatively available in JSON format by appending dream.out.format=json to the request URL
<developer-tokens count="{count}" href="https://{hostname}/@api/deki/site/developer-tokens">

    <!-- multiple tokens are supported -->
    {developer-token}
    ...
</developer-tokens>
Name Type Description
{hostname} string The Expert site hostname
{count} int The total token count
{developer-token} API Token An active token

Retrieve API token

Applies to:
All MindTouch Versions
Role required:
Admin
GET /@api/deki/site/developer-tokens/{id}
cURL
$ curl --request GET --header 'X-Deki-Token: {signature}' https://{hostname}/@api/deki/site/developer-tokens/{id}
JavaScript
fetch('https://{hostname}/@api/deki/site/developer-tokens/{id}?dream.out.format=json', {
    method: 'GET',
    headers: {
        'X-Deki-Token': '{signature}'
    }
}).then((response) => {
    return response.json();
});

Request

► Expand / Collapse
Parameters
The parameters that are required or accepted by this endpoint (optional parameters can be appended to the endpoint query string)
NameTypeDescription
{hostname}stringThe MindTouch site hostname
{signature}stringThe API Token key or signature
{id}stringThe integer API token id or "=" followed by an API token key

Response

The response body is alternatively available in JSON format by appending dream.out.format=json to the request URL
API Token
<developer-token id="{id}" type="{type}" date="{date}" href="https://{hostname}/@api/deki/site/developer-tokens/{id}">
    <key>{key}</key>
    <name>{name}</name>
    <host>{host}</host>
</developer-token>
Name Type Description
{hostname} string The Expert site hostname
{id} int The token numeric id
{type} {browser, oauth, server} The token type
{date} datetime ISO 8601 representation of the token's creation timestamp
{key} string The token unique public key
{name} string The token name
{host} (optional) string?

Retrieve list of web widgets

Applies to:
All MindTouch Versions
Role required:
Admin
GET /@api/deki/web-widgets
cURL
$ curl --request GET --header 'X-Deki-Token: {signature}' https://{hostname}/@api/deki/web-widgets
JavaScript
fetch('https://{hostname}/@api/deki/web-widgets?dream.out.format=json', {
    method: 'GET',
    headers: {
        'X-Deki-Token': '{signature}'
    }
}).then((response) => {
    return response.json();
});

Request

► Expand / Collapse
Parameters
The parameters that are required or accepted by this endpoint (optional parameters can be appended to the endpoint query string)
NameTypeDescription
{hostname}stringThe MindTouch site hostname
{signature}stringThe API Token key or signature

Response

The response body is alternatively available in JSON format by appending dream.out.format=json to the request URL
<web-widgets count="{count}" href="https://{hostname}/@api/deki/web-widgets">
    
    <!-- multiple web widgets are supported -->
    {web-widget}
    ...
</web-widgets>
Name Type Description
{hostname} string The Expert site hostname
{count} int The total web widget count
{web-widget} Web Widget An active web widget

Retrieve web widget

Applies to:
All MindTouch Versions
Role required:
Admin
GET /@api/deki/web-widgets/{id}
cURL
$ curl --request GET --header 'X-Deki-Token: {signature}' https://{hostname}/@api/deki/web-widgets/{id}
JavaScript
fetch('https://{hostname}/@api/deki/web-widgets/{id}?dream.out.format=json', {
    method: 'GET',
    headers: {
        'X-Deki-Token': '{signature}'
    }
}).then((response) => {
    return response.json();
});

Request

► Expand / Collapse
Parameters
The parameters that are required or accepted by this endpoint (optional parameters can be appended to the endpoint query string)
NameTypeDescription
{hostname}stringThe MindTouch site hostname
{signature}stringThe API Token key or signature
{id}stringThe web widget integer id or "=" followed by a web widget embed id string

Response

The response body is alternatively available in JSON format by appending dream.out.format=json to the request URL
Web Widget
<web-widget id="{id}" type="{type}" date="{date}" active="{active}" href="https://{hostname}/@api/deki/web-widgets/{id}">
    
    <!-- some web widgets rely on embedding child web widgets to provide a complete user experience -->
    <web-widgets count="{count}">
        {web-widget}
        ...
    </web-widgets>
    <name>{name}</name>
    <arguments>
        <{argument}>{value}</{argument}>
        ...
    </arguments>
    <host>{host}</host>
    <token>{token}</token>
    <code id="{embedid}" format="base64">{code}</code>
</web-widget>
Name Type Description
{hostname} string The Expert site hostname
{id} int The web widget numeric id
{type} string The web widget type (search, salesforce, zendesk, etc.)
{date} datetime ISO 8601 representation of the web widget's creation timestamp
{active} bool Is the web widget active or deactivated (unavailable to embed)?
{name} string The web widget's use case name or description
{argument} xml A configuration setting specific to the web widget type
{value} mixed The value of a configuration setting
{host} string The allowed browser CORS hostname pattern
{token} string A unique public key to allow Expert API access
{embedid} string A unique embed code id to identify where the web widget has been embedded
{code} string Base64 representation of the web widget's HTML embed code
{web-widget} Web Widget A child web widget, when necessary to provide a complete user experience
{count} int The total count of child web widgets

 

  • Was this article helpful?