Retrieve knowledge base articles

Overview

The get-articles Ortto endpoint of the kb entity is used to retrieve articles within Ortto’s customer data platform (CDP).

NOTE: You can also retrieve one article by referring to the 1/kb/get-one-article endpoint in retrieve one knowledge base article.

This page provides descriptions of the endpoint’s:

Request resource and method.
Valid parameters, headers and request body values.
The response payload.

HTTP method and request resource

Get articles endpoint


 POST https://api.ap3api.com/v1/kb/get-articles

NOTE: Ortto customers who have their instance region set to Australia or Europe will need to use specific service endpoints relative to the region:

Australia: https://api.au.ap3api.com/
Europe: https://api.eu.ap3api.com/

For example: https://api.eu.ap3api.com/v1/<entity/endpoint>

All other Ortto users will use the default service endpoint (https://api.ap3api.com/).

Path and query parameters

This endpoint take no additional path and/or query parameters.

Headers

This endpoint requires a custom API key and content type (application/json for the request body) in the header of the request:

X-Api-Key: CUSTOM-PRIVATE-API-KEY
Content-Type: application/json

Request body

The request body consists of a JSON object whose valid elements are listed in the table below.

Example get articles request body from Ortto's CDP

json
 {  
    "status": "",   
    "q": "" 
}

NOTE:

The default limit for articles is 50.
If there are more articles to view, the next-offset value indicates the starting point for retrieving the next set of articles, and to use this value in the offset field on the next API call.

Example get articles request body with an offset from Ortto's CDP

json
 {
    "status": "", 
    "q": "", 
    "offset": 50
}

Valid request body elements

The following table lists all valid, optional request body elements that are available at this endpoint.

Element	Type	Description
`status`	`string`	The status of an article can be specified as "on", "off", or left blank `""` to include all statuses.
`q`	`string`	A search term used to retrieve articles that contain the specified term in their title or description.
`limit`	`integer`	The `limit` value determines the number of activities to be returned by Ortto from the request. This value also represents the "page" length of articles (for pagination purposes). This element can be used in conjunction with `offset` to retrieve subsequent pages of article records. The default value is 50 but also accepts between 1 and 50.
`offset`	`integer`	The `offset` field specifies how far through the list of articles to get this batch from, enabling pagination through the results. For example, assuming the default limit of 50, get the first 50 matching articles by using an offset of 0, and then get the next 50 articles by using an offset of 50. Keep adding 50 to the offset each time to iterate through the list.

Response payload

The following JSON object is an example of an articles call that Ortto retrieves from your Ortto account’s CDP after a request to this endpoint.

json
 {
   "articles":[
      {
         "id":"671f0d10685bbcdf25e4f896",
         "title":"My first article"
      },
      {
         "id":"6695e4ccf24fff085e9df112",
         "title":"How to get multiple articles"
      },
      {
         "id":"6695c9d1f24fff085e9df103",
         "title":"How to create an article"
      },
      {
         "id":"6695c29948b1e5f3462ffaa5",
         "title":"Table Demo"
      },
      {
         "id":"6548518986f49929d2ae016a",
         "title":"Image Demo"
      },
      {
         "id":"650cf26b8bdeb4e9fbb12567",
         "title":"Title",
         "description":"Testing"
      }
   ],
   "total":6,
   "offset":0,
   "next_offset":6,
   "has_more":false
}

Response payload elements

The following table lists all elements (arrays, objects, or fields) in the response from a request to this endpoint.

Element		Type	Description
`articles`		`array` of objects	The `articles` array consists of an array of objects, where each object contains data for the knowledge base articles in your CDP.
	`id`	`string`	A string identifying the article ID by their unique ID number.
	`title`	`string`	The title of the article.
	`description`	`string`	The description included with the article.
`total`		`integer`	The total number of articles in the account.
`offset`		`integer`	The `offset` element represents the count of articles in your Ortto account’s CDP for pagination purposes, and is the point from which the next page of articles (defined by the limit member value) is retrieved. The offset value determines how many of the first articles will be skipped in the response.
`next_offset`		`integer`	The `next_offset` value indicates the starting point for retrieving the next page of articles. In this example, `next_offset: 6` means the next request would start after skipping the first 6 articles.
`has_more`		`boolean`	This endpoint returns the `limit` of articles at a time. If there are more articles in the list beyond what was returned, this is `true`.