Skip to main content
MindTouch Success Center

API 101 (MT4)

Written by Kalid Azad
Solutions Architect at MindTouch
This page applies to:MindTouch 4

Perform commands to create, update, and modify content on your site with the MindTouch API.

Step 1: Create a page

Create a page on your site for testing ( and enter some sample content.


Step 2: Access the API

Every object on the MindTouch site (pages, users, groups, etc.) are available through the API. If the page is public, we can use the "pages" API and visit in a browser:


A few notes:

  • MindTouch objects can be accessed by name (@api/deki/pages/=test) or id (@api/deki/pages/353). To find the id of a page manually, view the source in the browser and look for Deki.PageId.

  • The default response format is XML, but a JSON response is possible with the dream.out.format=json parameter (i.e.

  • The RESTful API is easy to explore with a browser. For example, here's the API response for the homepage of this help site.
Step 3: Access the page contents

Browsing the API response for the page, we see an XML document that includes several attributes such as the creation time, permissions, the user who created the page. If you search for "contents" in the response, you'll see the following attribute:

<contents type="application/x.deki0805+xml" href=""etag="31579b7948b2c3381ee049796f344508"/>

The page contents are not directly included in the summary API response by default, but available by loading the page in the href attribute. You can visit to access the page contents:

<content type="text/html" title="test">
    <body><p>Test page.</p></body>
    <body target="toc"><em>No headers</em></body>

This is the rendered version of the page HTML, which includes autogenerated content (such as an empty table of contents). We'd like to access the original page contents, before rendering.

Looking at the page contents API, we see there's a "mode" parameter that lets us access the raw page contents. We can load the API URL like so:

<content type="application/x.deki0805+xml" title="test">
    <body><p>Test page.</p></body>

This version returns the original page contents, in a format we can edit.

Step 4: Edit the page contents

For this example, we'll use curl to save the API response and edit the page locally. In other programming environments, use a standard HTTP library to perform a request and save the response to a variable.

From the command line, run the following:

curl > page.xml

The page contents are now saved inpage.xml:

<content type="application/x.deki0805+xml" title="test"><body>&lt;p&gt;Test page.&lt;/p&gt;</body></content>

Notice the page contents are stored as XML-encoded value. Using a text editor, we can modify the text and save page.xml.

Step 5: Update the page contents API

Let's send the new page information back to the site:

curl -X POST -d @page.xml -u user:pass

A few notes:

  • The -X POST setting indicates this a HTTP POST request. Make sure to use the right HTTP verb with the API (GET for accessing data, PUT for creating data, POST for updating, and DELETE for removing).

  • You can authenticate with standard HTTP Authentication (username/password), or by passing your API key in a header (X-ApiKey: YOUR-API-KEY)

  • -d @page.xml sends the file contents in the POST

  • By default, XML is the assumed input format.

When the request goes through, we see:

$ curl -X POST -d @page.xml -u user:pass
<?xml-stylesheet type='text/xsl' href='/@api/host/resources/error.xslt'?>
<error><status>400</status><title>Bad Request</title>
<message>'edittime' parameter is not valid</message>

We haven't included a required parameter, and the API returned an error response. The API is very descriptive if an error has occurred, which makes it simple to debug. Looking at the API documentation, we realize we need to include the "edittime" parameter (in the documentation, optional parameters are listed with a question mark).

Now we can resend the API request with an edit time:

$ curl -X POST -d @page.xml -u user:pass
<edit status="success"><page id="353" href="" deleted="false" revision="2"><uri.ui></uri.ui><title>test</title><path>test</path><namespace>main</namespace><date.created>2014-02-27T02:27:58Z</date.created></page></edit>

The API response was a success, and includes an edit summary in the response.

What's next

Most API interactions will be similar: querying information using GET requests, and creating or updating information with PUT and POST requests. The MindTouch API documentation includes short samples in C#, PHP and curl to help demonstrate a sample session for each type of request.

The API Best Practices includes tips for using the API, and several common requests you may wish to perform.

  • Was this article helpful?