Create a live page via API

Last updated
Save as PDF

This document provides a high-level overview of the API endpoints required to add a page to an Expert site via API.

Prerequisites

An expert site with the following:
- At least one available API token.
- A strategy for identifying and isolating generated content before it has been reviewed and verified.
  - For copilot implementations, have a private guide page directly under the home page called "Generated Content" where the integration can place the pages.
- Review manager capability turned on
Copilot implementation where you can:
- Generate content
- Upload to Expert
- Set a location for pages to go - either in the admin UI or another default location
- Set a default tag for all AI generated pages to receive
- Capability to "open in Expert" for most editing needs

Create a live page

Here's some docs for how it works in the UI: https://expert-help.nice.com/Manage/...raft_Authoring

POST to {base_url}/@api/deki/pages/={DOUBLE_URI_ENCODED_PATH}/contents
- the {double_uri_encoded_path} determines where in the hierarchy the page will go:
  - As explained in the page resource documentation, the {path} is everything after the base_url on an expert site. When you are creating a draft, the {path} will determine where on an expert site the page will go.
  - To add a page or draft to an existing hierarchy, use the desired page title as the final component of the path.
  - For example, to add a page with title "new page" to an already existing site with a parent page with the path "{base_url}/parent_page", you would end up creating a page with path '{base_url}/parent_page/new_page/'.
  - To create the page at "parent_page/new_page", you will POST to {base_url}/@api/deki/pages/=parent_page%2fnew_page/contents- this will create the page "new page"
  - Note: underscores are interpreted as spaces when pages get created using this method.
- Headers:
  - Content-Type: text/plain
- Query Parameters:
  - edittime=now
- In the body of the request, you will put your content (examples and details below)

Notable Headers, Query Parameters, and Path Parameters

Headers:

Content-Type: text/plain

Query Params:

edittime=now

Path Params:

={DOUBLE_URI_ENCODED_PATH} => =Generated_Content%2fTesting%2ftesting

Note that the / characters in the path are encoded to the value %2f

Sample complete endpoint url:

https://sample.mindtouch.us/@api/deki/pages/=Generated_Content$2fTesting%2ftesting/contents?&edittime=now

This will edit the contents on a page with the path Generated_Content/Testing/testing

Request body

You will always want the following boilerplate in the body of your request:

<content>
    <body>
        <!-- here is where you can change the content -->
        <h1>Your HTML Content Here</h1>
        <div id="main-content-here">
            <a href="/">Sample link element</a>
            <p>Main body of the article starts here...</p>
        </div>
        <!-- The below <p> tag content is required, do not change it -->
        <p class="template:tag-insert">
            <em>Tags recommended by the template: </em>
            <a href="#">article:topic</a>
        </p>
    </body>
</content>

Here is an example that is a bit more tangible:

 <content>
    <body>
        <p class=\"mt-script-comment\">Page summary display</p>
        <pre class=\"script\">template('MindTouch/Controls/PageOverview');</pre>
        <p class=\"mt-script-comment\">List subpages if any exist</p>
        <pre class=\"script\">template(\"Template:Custom/List_Subpages_If_Exists\")</pre>
        <h2>Problem</h2>
        <p>I recently started using Reference articles nested below Topic pages as a way of organizing information for
            each of the Solutions I'm working on. The idea being that the Topic page represents the overall description
            and project notes, while the Reference pages are the working notes or a record of the decisions we made.</p>
        <p>At the Guide level, it is relatively simple to see these Reference articles, as they're shown slightly smaller
            and underneatch their parent article. However, much of the time I'm sharing these Topic pages with
            stakeholders that likely won't think to navigate to the Guide to seek more details. I wanted to add a set of
            links at the top of the article that represented all the addition Reference children articles for easy
            access in a way that wouldn't obstruct normal usage of an article.</p>
        <h2>Solution</h2>
        <p>Using Dekiscript, I was able to put together a script that displays a list of links and the associated
            article titles only when subpages exist. Ideally, there's more to do to on the usability and design front,
            but I will outline the more interesting Dekiscript&nbsp;components and provide the code.</p>
        <p><strong>Here's a page where we can see the solution in action:</strong></p>
        <p><a href=\"/Internal_Solutions/Solutions/WCX_Content_Import_Automation_and_Connector\" title=\"WCX Madcap
                Flare Content Import Connector\">WCX Madcap Flare Content Import Connector</a></p>
        <h3>Conditionally Executing Based on If Subpages Exist</h3>
        <pre function=\"syntax.dekiscript\">if(#page.subpages){    ...Code to execute here...}</pre>
        <p>The code above represents how to determine if subpages exist and, if so, execute the code within the braces.
            Of note is the usage of #variableName notation.</p>
        <p>You can get the number of elements in an array or object by preppending the # character in front of the
            variable name! For example:</p>
        <pre
            function=\"syntax.dekiscript\">var object = {\"entry1\":\"val1\",\"entry2\":\"val2\"};<p>\"Number of entries: \";#object</p>var array = [\"item1\",\"item2\"];<p>\"Number of items: \";#array</p></pre>
        <p>The output is shown below:&nbsp;</p>
        <pre
            class=\"script\">var object = {\"entry1\":\"val1\",\"entry2\":\"val2\"};<p>\"Number of entries: \";#object</p>var array = [\"item1\",\"item2\"];<p>\"Number of items: \";#array</p></pre>
        <p>The other secret to this code is that some values are considered truthy or falsey. Of importance to this
            example is that the number 0 is considered falsey, and any other integer is considered truthy. So when the
            number of subpages is 0, the if condition sees a false value and doesn't execute the code in the braces.
            When there's 1 or more pages present, the code in the braces executes!</p>
        <p class="template:tag-insert"> <em>Tags recommended by the template: </em> <a href="#">article:topic</a> </p>
    </body>
</content>

Article tags:

The API will search for the specified page path. If it's not found, it will be created, provided all the correct data is entered. The article type is determined by the following <p> tag keywords during its creation:

"topic-category" - This will create a new Category
"topic-guide" - This will create a new Guide
"topic" - This will create a new Topic
"howto" - This will create a new How-to
"reference" - This will create a new Reference

For example, to create a new Category:

<p class="template:tag-insert">
   <em>Tags recommended by the template: </em>
   <a href="#">article:topic-category</a>
</p>