REST API for Oracle Service Cloud Knowledge Advanced

Work with your REST API Client

Because REST APIs use HTTP methods to send and receive content, you can test REST APIs using any programming language or tool that supports sending and receiving HTTP messages. So, let's first choose a tool for making HTTP requests.

Choosing a REST API Client

You can choose among many REST API clients that interact with Oracle Service Cloud Knowledge Advanced, such as:

A standalone client, such as Postman or Advanced REST Client.
Your connecting application's client.
The cURL command-line utility.

With a REST API client you can:

Test the username, password, and request URL for your REST API account.
Access the metadata to learn more about REST resources, attributes, and parameters.
Use the collected information to construct and send various types of HTTP requests, such as those to create, update, or delete records.

Using cURL to Send HTTP Requests

In our examples, we use cURL, a popular command-line utility for transferring data using URL syntax, to send requests to REST services. cURL is available in most UNIX, Windows, and Macintosh environments. For details, see Installing the cURL Command-Line Tool on Windows.

The following table describes commonly used cURL options that you can use for REST services.

Option	Description
-user or -u	`username:password` Specifies the user name and password for server authentication.
-d	Sends the specified data (a JSON request body) to the server. If you begin the data with the at sign (@), it must be followed by the file name to read the data from. For example, `-d@example_request_payload.json`
-H	Specifies an extra HTTP header in the request. To specify multiple headers, precede each header with the `-H` option. Examples: Content-Type: Format of Request Body (for example, with POST) Accept: Format of Response Body
-output	`<file>` Writes the output to a file instead of to stdout.
-X	Specifies the request method to use when communicating with the HTTP server. The default method is GET.

The following table shows Service Cloud Knowledge Advanced REST APIs examples of the GET, POST, and PUT operations using cURL.

Operation cURL Command

Operation	cURL Command
Use GET to get a list of content history objects associated with a Content object	`curl -X GET https://site.example.com/km/api/latest/content/e3fad0e6303643bd8a930a6240db9ac7z/history -H 'Accept: application/json' -H 'Content-Type: application/json' -H 'kmauthtoken: {"siteName":"example_site","integrationUserToken":"ZXhhbXBs...SKIP...M1MHJjWT0="}' -d 'userName=user_name&password=password&siteName=example_site&userExternalType=ACCOUNT'`
Use POST to rate a Content object	curl -X POST https://site.example.com/km/api/latest/content/0480165035cb2f4a014581a0f299007b3a/rate -H 'Accept: application/json' -H 'Content-Type: application/json' -H 'kmauthtoken: {"siteName":"example_site","integrationUserToken":"ZXhhbXBs...SKIP...M1MHJjWT0="}' -d 'userName=user_name&password=password&siteName=example_site&userExternalType=ACCOUNT' -d {"survey":{"recordId":"0480165035cb2f4a014581a0f299007b3a"},"locale":{"recordId":"es_ES"},"answer":{"recordId":"0480165035cb2f4a014581a0f299007b3b"},"answerComment":"Sample answer comment"}
Use PUT to import a Content object	curl -X PUT https://site.example.com/km/api/latest/content/12345678/import -H 'Accept: application/json' -H 'Content-Type: application/json' -H 'kmauthtoken: {"siteName":"example_site","integrationUserToken":"ZXhhbXBs...SKIP...M1MHJjWT0="}' -d 'userName=user_name&password=password&siteName=example_site&userExternalType=ACCOUNT' -d {"content":{"isForEdit":true,"views":[{"recordId":"0246897531","referenceKey":"PRODUCT_MANAGEMENT","name":"PRODUCT_MANAGEMENT"}],"recordId":"12345678","versionId":"4B5BE004C5BD48B8B67D48E93E2D750D","documentId":"FAQ92","version":"0.1","answerId":1001041,"locale":{"recordId":"es_ES"},...,"basedLocale":{"recordId":"en_US"},"xml":"XML_VALUE"},"contentModificationQualifier":{"publish":false,"bypassWorkflowAndPublish":false}}

Use GET to get a list of content history objects associated with a Content object

curl -X GET https://site.example.com/km/api/latest/content/e3fad0e6303643bd8a930a6240db9ac7z/history -H 'Accept: application/json' -H 'Content-Type: application/json' -H 'kmauthtoken: {"siteName":"example_site","integrationUserToken":"ZXhhbXBs...SKIP...M1MHJjWT0="}' -d 'userName=user_name&password=password&siteName=example_site&userExternalType=ACCOUNT'

Use POST to rate a Content object

curl -X POST https://site.example.com/km/api/latest/content/0480165035cb2f4a014581a0f299007b3a/rate -H 'Accept: application/json' -H 'Content-Type: application/json' -H 'kmauthtoken: {"siteName":"example_site","integrationUserToken":"ZXhhbXBs...SKIP...M1MHJjWT0="}' -d 'userName=user_name&password=password&siteName=example_site&userExternalType=ACCOUNT' -d {"survey":{"recordId":"0480165035cb2f4a014581a0f299007b3a"},"locale":{"recordId":"es_ES"},"answer":{"recordId":"0480165035cb2f4a014581a0f299007b3b"},"answerComment":"Sample answer comment"}

Use PUT to import a Content object

curl -X PUT https://site.example.com/km/api/latest/content/12345678/import -H 'Accept: application/json' -H 'Content-Type: application/json' -H 'kmauthtoken: {"siteName":"example_site","integrationUserToken":"ZXhhbXBs...SKIP...M1MHJjWT0="}' -d 'userName=user_name&password=password&siteName=example_site&userExternalType=ACCOUNT' -d {"content":{"isForEdit":true,"views":[{"recordId":"0246897531","referenceKey":"PRODUCT_MANAGEMENT","name":"PRODUCT_MANAGEMENT"}],"recordId":"12345678","versionId":"4B5BE004C5BD48B8B67D48E93E2D750D","documentId":"FAQ92","version":"0.1","answerId":1001041,"locale":{"recordId":"es_ES"},...,"basedLocale":{"recordId":"en_US"},"xml":"XML_VALUE"},"contentModificationQualifier":{"publish":false,"bypassWorkflowAndPublish":false}}

Using REST API Clients to Send HTTP Requests

You can use standalone clients, third-party browser extensions, or add-ons, such as the Advanced REST Client, to send HTTP requests.

The following list includes examples of the GET, POST, and PUT operations using a REST API client.

GET: Get history of a Content object

Request URL:

https://site.example.com/km/api/latest/content/e3fad0e6303643bd8a930a6240db9ac7/history

Request Header:

kmauthtoken: {"siteName":"example_site","integrationUserToken":""+eCJYkxKwj5HUaIiJYun0/TpatwT1LmtcsF05W33xnEojifV/AsLDj9RpN0lKuorTMNKeSE1tgC7svVL+BzntqDON4KiM1HFlpxvXEUCB0P2w0Xrs75McygqxdVaDSE9"}
Accept: application/json

Response Body:

{
	{
      "recordId" : "e3fad0e6303643bd8a930a6240db9ac7",
      "answerId" : 0
    },
    "action" : "ACTION_VALUE",
    "comments" : "COMMENTS_VALUE",
    "dateAdded" : "2013-04-23T21:06:28-0400",
    "dateModified" : "2013-04-23T21:06:28-0400",
    "previousWorkflowStepId" : "PREVIOUSWORKFLOWSTEPID_VALUE",
    "userInformationId" : "USERINFORMATIONID_VALUE",
    "userName" : "USERNAME_VALUE",
    "workflowName" : "WORKFLOWNAME_VALUE",
    "workflowStepId" : "WORKFLOWSTEPID_VALUE",
    "workflowStepName" : "WORKFLOWSTEPNAME_VALUE",
    "links" : [ {
      "rel" : "canonical",
      "href" : "http://<IM_REST_API_HOST>/km/api/{version}/{resourceURI}",
      "mediaType" : "application/json, application/xml",
      "templated" : true,
      "method" : "GET"
    } ]
  } ],
  "hasMore" : false,
  "limit" : 20,
  "offset" : 0,
  "count" : 1
}

POST: Rate content

Request URL:

https://site.example.com/km/api/latest/contentcontent/0480165035cb2f4a014581a0f299007b3a/rate

Request Header:

kmauthtoken: {"siteName":"example_site","integrationUserToken":""+eCJYkxKwj5HUaIiJYun0/TpatwT1LmtcsF05W33xnEojifV/AsLDj9RpN0lKuorTMNKeSE1tgC7svVL+BzntqDON4KiM1HFlpxvXEUCB0P2w0Xrs75McygqxdVaDSE9"}
Accept: application/json

Request Body:

{
  "survey" : {
    "recordId" : "0480165035cb2f4a014581a0f299007b3a",
    "referenceKey" : "REFERENCEKEY_VALUE",
    "links" : [ {
      "rel" : "canonical",
      "href" : "http://<IM_REST_API_HOST>/km/api/{version}/{resourceURI}",
      "mediaType" : "application/json, application/xml",
      "templated" : true,
      "method" : "GET"
    } ]
  },
  "locale" : {
  },
  "answer" : {
  },
  "answerComment" : "ANSWER_COMMENT"
}

Response Body:

This request does not return any response body.

PUT: Import a Content object

Request URL:

https://site.example.com/km/api/latest/content/12345678/import

Request Header:

kmauthtoken: {"siteName":"example_site","integrationUserToken":""+eCJYkxKwj5HUaIiJYun0/TpatwT1LmtcsF05W33xnEojifV/AsLDj9RpN0lKuorTMNKeSE1tgC7svVL+BzntqDON4KiM1HFlpxvXEUCB0P2w0Xrs75McygqxdVaDSE9"}
Accept: application/json

Request Body:

{
  "content" : {
    "isForEdit" : true,
    "views" : [ {
      "recordId" : "0246897531",
      "referenceKey" : "PRODUCT_MANAGEMENT",
      "name" : "PRODUCT_MANAGEMENT"
    } ],
    "recordId" : "12345678",
    "versionId" : "4B5BE004C5BD48B8B67D48E93E2D750D",
    "documentId" : "FAQ92",
    "version" : "0.1",
    "answerId" : 1001041,
    "locale" : {
      "recordId" : "es_ES"
    },
    "dateModified" : "2017-05-18T12:10:38-0700",
    "contentType" : {
      "recordId" : "9876543210",
      "referenceKey" : "FAQ",
      "name" : "FAQ"
    },
    "createDate" : "2017-05-18T12:10:38-0700",
    "dateAdded" : "2017-05-18T12:10:38-0700",
    "basedOnVersion" : "2.0",
    "basedLocale" : {
      "recordId" : "en_US"
    },
    "xml" : "XML_VALUE"
  },
  "contentModificationQualifier" : {
  }
}

Response Body:

{
  "isForEdit" : true,
  "replacementTokens" : [ {
    "dateModified" : "284852364-01-15T04:07:46-0800",
    "replacementText" : "REPLACEMENTTEXT_VALUE",
    "replacementTextNonFormatted" : "REPLACEMENTTEXTNONFORMATTED_VALUE",
    "tokenType" : "TOKENTYPE_VALUE",
    "tokenName" : "TOKENNAME_VALUE",
    "links" : [ {
      "rel" : "canonical",
      "href" : "http://<IM_REST_API_HOST>/km/api/{version}/{resourceURI}",
      "mediaType" : "application/json, application/xml",
      "templated" : true,
      "method" : "GET",
      "profile" : "http://<IM_REST_API_HOST>/km/api/{version}/metadata-catalog/{resourceName}"
    } ]
  } ],
  "categories" : [ {
    "referenceKey" : "REFERENCEKEY_VALUE",
    "name" : "NAME_VALUE",
    "externalType" : "EXTERNALTYPE_VALUE",
    "links" : [ {
      "rel" : "canonical",
      "href" : "http://<IM_REST_API_HOST>/km/api/{version}/{resourceURI}",
      "mediaType" : "application/json, application/xml",
      "templated" : true,
      "method" : "GET",
      "profile" : "http://<IM_REST_API_HOST>/km/api/{version}/metadata-catalog/{resourceName}"
    } ]
  } ],
  "userGroups" : [ {
    "referenceKey" : "REFERENCEKEY_VALUE",
    "name" : "NAME_VALUE",
    "externalType" : "EXTERNALTYPE_VALUE",
    "links" : [ {
      "rel" : "canonical",
      "href" : "http://<IM_REST_API_HOST>/km/api/{version}/{resourceURI}",
      "mediaType" : "application/json, application/xml",
      "templated" : true,
      "method" : "GET",
      "profile" : "http://<IM_REST_API_HOST>/km/api/{version}/metadata-catalog/{resourceName}"
    } ]
  } ],
  "views" : [ {
    "referenceKey" : "REFERENCEKEY_VALUE",
    "name" : "NAME_VALUE",
    "links" : [ {
      "rel" : "canonical",
      "href" : "http://<IM_REST_API_HOST>/km/api/{version}/{resourceURI}",
      "mediaType" : "application/json, application/xml",
      "templated" : true,
      "method" : "GET",
      "profile" : "http://<IM_REST_API_HOST>/km/api/{version}/metadata-catalog/{resourceName}"
    } ]
  } ],
  "versionId" : "VERSIONID_VALUE",
  "documentId" : "DOCUMENTID_VALUE",
  "title" : "TITLE_VALUE",
  "version" : "VERSION_VALUE",
  "answerId" : 1428416791848,
  "locale" : {
    "links" : [ {
      "rel" : "canonical",
      "href" : "http://<IM_REST_API_HOST>/km/api/{version}/{resourceURI}",
      "mediaType" : "application/json, application/xml",
      "templated" : true,
      "method" : "GET",
      "profile" : "http://<IM_REST_API_HOST>/km/api/{version}/metadata-catalog/{resourceName}"
    } ]
  },
  "dateModified" : "2013-04-23T18:06:26-0700",
  "links" : [ {
    "rel" : "canonical",
    "href" : "http://<IM_REST_API_HOST>/km/api/{version}/{resourceURI}",
    "mediaType" : "application/json, application/xml",
    "templated" : true,
    "method" : "GET",
    "profile" : "http://<IM_REST_API_HOST>/km/api/{version}/metadata-catalog/{resourceName}"
  } ],
  "contentType" : {
    "referenceKey" : "REFERENCEKEY_VALUE",
    "name" : "NAME_VALUE",
    "links" : [ {
      "rel" : "canonical",
      "href" : "http://<IM_REST_API_HOST>/km/api/{version}/{resourceURI}",
      "mediaType" : "application/json, application/xml",
      "templated" : true,
      "method" : "GET",
      "profile" : "http://<IM_REST_API_HOST>/km/api/{version}/metadata-catalog/{resourceName}"
    } ]
  },
  "priority" : "PRIORITY_20",
  "createDate" : "2013-04-23T18:06:26-0700",
  "dateAdded" : "2013-04-23T18:06:26-0700",
  "displayStartDate" : "2013-04-23T18:06:26-0700",
  "displayEndDate" : "2013-04-23T18:06:26-0700",
  "eventStartDate" : "2013-04-23T18:06:26-0700",
  "eventEndDate" : "2013-04-23T18:06:26-0700",
  "owner" : {
    "name" : "NAME_VALUE",
    "externalId" : 1428416791841,
    "externalType" : "EXTERNALTYPE_VALUE",
    "links" : [ {
      "rel" : "canonical",
      "href" : "http://<IM_REST_API_HOST>/km/api/{version}/{resourceURI}",
      "mediaType" : "application/json, application/xml",
      "templated" : true,
      "method" : "GET",
      "profile" : "http://<IM_REST_API_HOST>/km/api/{version}/metadata-catalog/{resourceName}"
    } ]
  },
  "lastModifier" : {
    "name" : "NAME_VALUE",
    "externalId" : 1428416791859,
    "externalType" : "EXTERNALTYPE_VALUE",
    "links" : [ {
      "rel" : "canonical",
      "href" : "http://<IM_REST_API_HOST>/km/api/{version}/{resourceURI}",
      "mediaType" : "application/json, application/xml",
      "templated" : true,
      "method" : "GET",
      "profile" : "http://<IM_REST_API_HOST>/km/api/{version}/metadata-catalog/{resourceName}"
    } ]
  },
  "creator" : {
    "name" : "NAME_VALUE",
    "externalId" : 1428416791867,
    "externalType" : "EXTERNALTYPE_VALUE",
    "links" : [ {
      "rel" : "canonical",
      "href" : "http://<IM_REST_API_HOST>/km/api/{version}/{resourceURI}",
      "mediaType" : "application/json, application/xml",
      "templated" : true,
      "method" : "GET",
      "profile" : "http://<IM_REST_API_HOST>/km/api/{version}/metadata-catalog/{resourceName}"
    } ]
  },
  "published" : true,
  "pending" : false,
  "displayReviewDate" : "2013-04-23T18:06:26-0700",
  "checkedOut" : true,
  "checkedOutBy" : {
    "name" : "NAME_VALUE",
    "externalType" : "EXTERNALTYPE_VALUE",
    "links" : [ {
      "rel" : "canonical",
      "href" : "http://<IM_REST_API_HOST>/km/api/{version}/{resourceURI}",
      "mediaType" : "application/json, application/xml",
      "templated" : true,
      "method" : "GET",
      "profile" : "http://<IM_REST_API_HOST>/km/api/{version}/metadata-catalog/{resourceName}"
    } ]
  },
  "basedOnVersion" : "BASEDONVERSION_VALUE",
  "publishedVersion" : "PUBLISHEDVERSION_VALUE",
  "basedLocale" : {
    "links" : [ {
      "rel" : "canonical",
      "href" : "http://<IM_REST_API_HOST>/km/api/{version}/{resourceURI}",
      "mediaType" : "application/json, application/xml",
      "templated" : true,
      "method" : "GET",
      "profile" : "http://<IM_REST_API_HOST>/km/api/{version}/metadata-catalog/{resourceName}"
    } ]
  },
  "displayPosition" : "HISTORICAL_USEFULNESS",
  "workflowStep" : {
    "referenceKey" : "REFERENCEKEY_VALUE",
    "name" : "NAME_VALUE",
    "links" : [ {
      "rel" : "canonical",
      "href" : "http://<IM_REST_API_HOST>/km/api/{version}/{resourceURI}",
      "mediaType" : "application/json, application/xml",
      "templated" : true,
      "method" : "GET"
    } ]
  },
  "wfStepNotificationOverride" : "2013-04-23T18:06:26-0700",
  "xml" : "XML_VALUE",
  "metaDataXml" : "METADATAXML_VALUE",
  "resourcePath" : "http://<IM_REST_API_HOST>/okcs/resources/{TENANTID}/content/draft/{CONTENTID}/{CONTENTTEXTID}/{FILENAME_WITH_EXTENSION}?login={USER_NAME}",
  "metaDataResourcePath" : "METADATARESOURCEPATH_VALUE",
  "reasonForEdit" : "REASON_FOR_EDITING_OR_CREATING_CONTENT_RECORD"
}