API Reference

Last updated
Save as PDF

Welcome to the MindTouch API reference documentation! This guide is your starting point to begin leveraging the MindTouch 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

MindTouch 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 MindTouch 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 MindTouch becomes a critical piece of your organization's business.

These types of integrations typically require more complexity and application programming skills. While the MindTouch 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 MindTouch functionality into key parts of an organization.

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

Getting Started

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

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

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

HTTPS

MindTouch API communication is secured with HTTPS. It can be accessed privately and securely by HTTPS compatible clients such as a web browser. The MindTouch API domain (a MindTouch 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 MindTouch site domain, integrations with the MindTouch 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

MindTouch 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 MindTouch API and can be reported to the MindTouch 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
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 MindTouch 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 MindTouch 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 MindTouch API can receive three types of tokens to allow access to MindTouch site data.

Auth Token

Browser API Token

Browser API Tokens are sent from a website, web application, or simply anything that runs in a web browser to the MindTouch 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 MindTouch 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 aren't 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 MindTouch site, then the API considers the user to be an anonymous user

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 MindTouch 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.

OAuth API Token

While Server API Tokens provide a developer with the ability to connect applications and devices to the MindTouch API with unlimited permissions, under some scenarios this level of access control is inappropriate for a developer. Examples include integrations between the MindTouch API and a third-party service, on behalf of the organization deploying MindTouch. By implementing OAuth 2.0 authorization flows, OAuth API Tokens allow MindTouch users to authorize which applications or devices can access their MindTouch 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 MindTouch site administrator access.

Core Resources

MindTouch 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 MindTouch 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 article 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 MindTouch site, a new local page id will be assigned
{guid}	string	Global page id - if the page is exported and imported into a different MindTouch 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 MindTouch 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 MindTouch API. They can also be used to create links that resolve and redirect to the page content in the MindTouch 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>

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 MindTouch site hostname
{pageid}	int	Local page id - if the page is exported and imported into a different MindTouch 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 MindTouch 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 MindTouch 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 MindTouch 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 MindTouch site, a new local property id will be assigned
{name}	string	The property name (ex: `urn:custom.mindtouch.com#css`) Required properties that the MindTouch platform relies on are often prefixed with namespaces ending with a `#` symbol (ex: urn:ui.deki.mindtouch.com#)
{hostname}	string	The MindTouch 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

GET /@api/deki/site/query/log

GET /@api/deki/site/query/logs

GET /@api/deki/site/query/logs/{logname}/url

GET /@api/deki/site/query/log/{queryid}

GET /@api/deki/site/query/log/terms

GET /@api/deki/site/search/analytics

GET /@api/deki/site/search/analytics/query

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

GET /@api/deki/pages/{pageid}/health

GET /@api/deki/site/reports/conditionalcontent.csv

GET /@api/deki/site/reports/health.csv

GET /@api/deki/site/reports/sitehealth

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)

Name	Type	Description
{hostname}	string	The MindTouch site hostname
{signature}	string	The 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)

Name	Type	Description
{hostname}	string	The MindTouch site hostname
{signature}	string	The 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)

Name	Type	Description
{hostname}	string	The MindTouch site hostname
{signature}	string	The API Token key or signature
{logname}	string	Name 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 (e.g. 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)

Name	Type	Description
{hostname}	string	The MindTouch site hostname
{signature}	string	The API Token key or signature
{queryid}	string	Either 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 MindTouch 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 MindTouch 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)

Name	Type	Description
{hostname}	string	The MindTouch site hostname
{signature}	string	The 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)

Name	Type	Description
{hostname}	string	The MindTouch site hostname
{signature}	string	The 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)

Name	Type	Description
{hostname}	string	The MindTouch site hostname
{signature}	string	The 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}	string	Search 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)

Name	Type	Description
{hostname}	string	The MindTouch site hostname
{signature}	string	The 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}	int	Maximum number of results to return (default: 100)
{offset}	int	Number 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 MindTouch site, a new local page id will be assigned
{article} (optional)	string?	Page article 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)

Name	Type	Description
{hostname}	string	The MindTouch site hostname
{signature}	string	The 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)

Name	Type	Description
{hostname}	string	The MindTouch site hostname
{signature}	string	The 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)

Name	Type	Description
{hostname}	string	The MindTouch site hostname
{signature}	string	The 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}	int	Maximum number of results to return (default: 100)
{offset}	int	Number 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 different knowledge management use cases, such as Content Translation, can be automated through the use of Job API endpoints to export and import content. Job API endpoints can start content import and export jobs, cancel, and check the status of in-progress jobs. Content import and export job requests are sent to a background job queue to be processed when compute resources are available to handle the job. Since concurrent content import and export jobs can possibly 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 content export jobs that can run per MindTouch site, however, a content export job cannot start if a content import job is in progress
Only one content import job can run concurrently per MindTouch site

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

Endpoints

GET /@api/deki/site/jobs

GET /@api/deki/site/jobs/{id}

POST /@api/deki/site/jobs/{id}/cancel

POST /@api/deki/site/jobs/export

POST /@api/deki/site/jobs/import

PUT /@api/deki/site/jobs/{id}/status/{status}

Paths

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

Endpoints

GET /@api/deki/learning-paths

GET /@api/deki/learning-paths/{pathid}

GET /@api/deki/learning-paths/{pathid}/pages

GET /@api/deki/learning-paths/{pathid}/pages/{pageid}

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)

Name	Type	Description
{hostname}	string	The MindTouch site hostname
{signature}	string	The 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)

Name	Type	Description
{hostname}	string	The MindTouch site hostname
{signature}	string	The 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)

Name	Type	Description
{hostname}	string	The MindTouch site hostname
{signature}	string	The API Token key or signature
{body}	application/xml; charset=utf-8	The 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)

Name	Type	Description
{hostname}	string	The MindTouch site hostname
{signature}	string	The API Token key or signature
{body}	application/xml; charset=utf-8	The 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 subpage 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)

Name	Type	Description
{hostname}	string	The MindTouch site hostname
{signature}	string	The 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-8	The 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)

Name	Type	Description
{hostname}	string	The MindTouch site hostname
{signature}	string	The API Token key or signature
{body}	application/xml; charset=utf-8	The 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:

A URL to download any generated error or warning logs
If successful, the MindTouch site that completed a content import or export
If a successful content export job, a URL to the exported archive to download

Webhook

A public webhook (without any authorization requirements) can be configured to receive an HTTP POST message from MindTouch 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 MindTouch 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 MindTouch 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 MindTouch site page hierarchy needs to be moved to a location inside the destination MindTouch 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 MindTouch 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)

Name	Type	Description
{hostname}	string	The MindTouch site hostname
{signature}	string	The 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 MindTouch 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)

Name	Type	Description
{hostname}	string	The MindTouch site hostname
{signature}	string	The API Token key or signature
{pathid}	string	The 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 MindTouch 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)

Name	Type	Description
{hostname}	string	The MindTouch site hostname
{signature}	string	The API Token key or signature
{pathid}	string	The 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 MindTouch 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)

Name	Type	Description
{hostname}	string	The MindTouch site hostname
{signature}	string	The API Token key or signature
{pathid}	string	The learning path id prefixed with "="
{pageid}	string	Either 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

GET /@api/deki/site/query

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

GET /@api/deki/site/opensearch

GET /@api/deki/site/opensearch/description

GET /@api/deki/site/opensearch/suggestions

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

DELETE /@api/deki/site/query/recommendations/{id}

GET /@api/deki/site/query/recommendations

GET /@api/deki/site/query/recommendations/{id}

POST /@api/deki/site/query/recommendations

PUT /@api/deki/site/query/recommendations/{id}

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)

Name	Type	Description
{hostname}	string	The MindTouch site hostname
{signature}	string	The API Token key or signature
{q}	string	Search 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 article 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 article type filter option
{aggs/articles/value}	string	The name of the article 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)

Name	Type	Description
{hostname}	string	The MindTouch site hostname
{signature}	string	The API Token key or signature
{format} (optional)	{rss \| atom}?	Search output format (rss \| atom) default: atom
{q}	string	Search 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 MindTouch 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 MindTouch 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)

Name	Type	Description
{hostname}	string	The MindTouch site hostname
{signature}	string	The 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 MindTouch 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)

Name	Type	Description
{hostname}	string	The MindTouch site hostname
{signature}	string	The API Token key or signature
{q}	string	Search 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 MindTouch 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)

Name	Type	Description
{hostname}	string	The MindTouch site hostname
{signature}	string	The API Token key or signature
{id}	int	Identifies 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)

Name	Type	Description
{hostname}	string	The MindTouch site hostname
{signature}	string	The 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)

Name	Type	Description
{hostname}	string	The MindTouch site hostname
{signature}	string	The API Token key or signature
{id}	int	Identifies 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 MindTouch 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)

Name	Type	Description
{hostname}	string	The MindTouch site hostname
{signature}	string	The API Token key or signature
{body}	application/xml; charset=utf-8	The 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)

Name	Type	Description
{hostname}	string	The MindTouch site hostname
{signature}	string	The API Token key or signature
{id}	int	Identifies a search recommendation by id
{body}	application/xml; charset=utf-8	The 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 a MindTouch site. For enhanced security, Token API endpoints never return Server API Token or OAuth API Token secrets.

Endpoints

GET /@api/deki/site/developer-tokens

GET /@api/deki/site/developer-tokens/{id}

Touchpoints

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

Endpoints

GET /@api/deki/web-widgets

GET /@api/deki/web-widgets/{id}

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)

Name	Type	Description
{hostname}	string	The MindTouch site hostname
{signature}	string	The 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 MindTouch 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)

Name	Type	Description
{hostname}	string	The MindTouch site hostname
{signature}	string	The API Token key or signature
{id}	string	The 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 MindTouch 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?	The allowed browser CORS hostname pattern (`{type} = browser`) The allowed OAuth 2.0 authorization code callback hostname pattern (`{type} = oauth`)

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)

Name	Type	Description
{hostname}	string	The MindTouch site hostname
{signature}	string	The 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 MindTouch 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)

Name	Type	Description
{hostname}	string	The MindTouch site hostname
{signature}	string	The API Token key or signature
{id}	string	The 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 MindTouch 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 MindTouch 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