Smart Tribune V2 API (1.0.5)

E-mail: devs@smart-tribune.com

The purpose of this API is to allow developers to build front-end interfaces for displaying knowledge base data (Faq, Helpbox, Chatbot ...)

Authorization and API Requests

To access the API, all requests need an api-token to be passed in the Authorization request header as a bearer token. Authorization: Bearer api-token You can retrieve your api-token using the POST request to /v1/auth.

Rate Limiting

We currently limit the number of API requests per IP address on a specific window of 1s. When the rate limit is exceeded for a given API endpoint, the API will return either HTTP 429 Too Many Requests or HTTP 503 Service Unavailable response.

Find below Standard API rate limits per window:

Endpoints	User limit per window
POST /v1/auth	2
GET /v1/knowledge-bases	2
POST /v1/knowledge-bases/{id}/filtered/questions	10
POST /v1/knowledge-bases/{id}/filtered/thematics	10
POST /v1/knowledge-bases/{id}/search	10
GET /v1/knowledge-bases/{id}/questions/{questionId}/channels/{channelId}/responses	10
POST /v1/knowledge-bases/{id}/questions/{questionId}/responses/{responseId}/responses-satisfactions	2
GET /v1/knowledge-bases/{id}/reasons	2
GET /v1/knowledge-bases/{id}/reasons-comments	2
PATCH /v1/knowledge-bases/{id}/questions/{questionId}/responses/{responseId}/responses-satisfactions/{satisfactionId}	2
GET /v1/knowledge-bases/{id}/contacts	2

Authentication

Authenticate through our API

Allow user to authenticate through our API and retrieve a JWT token that need to be used within all requests

Request Body schema: application/json

Authenticate user and retrieve JWT token

apiKey required	string API Key
apiSecret required	string API Secret

Responses

Request samples

Payload

Content type

application/json

{"apiKey": "yourprivateapikey",
"apiSecret": "yourprivateapisecret"
}

Response samples

200
401
429
503

Content type

application/json

{"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}

Filtered API

Performance oriented API to fetch list of items

Fetch a (list of) Question(s) depend on specified Filters Deprecated

Authorizations:

bearerAuth

path Parameters

id

required

integer

The knowledgebase Id that needs to be fetched.

query Parameters

hydrateTags	boolean Enum: true false Example: hydrateTags=false If set to true, associated tags will be included in response payload
page	integer Example: page=1 Page identifier
limit	integer <= 200 Example: limit=25 Items per page
sort	string Enum: "createdAt" "updatedAt" Example: sort=createdAt Property used to sort results (not applicable when body "query" parameter is set)
order	string Enum: "asc" "desc" Example: order=asc direction used when sort query param is defined (not applicable when body "query" parameter is set)

header Parameters

Accept-Language

required

string

Example: fr

Language locale to filter api results

Request Body schema: application/json

Example of payloads to fetch :

Promoted Questions within Smart FAQ Channel

 {
   "channel": "faq",
   "promoted": true
 }

Frequent Questions within Smart FAQ Channel

{
  "channel": "faq",
  "frequent": true
}

Related questions within Smart FAQ channel for thematic systemName "how-to-make-booking-987" and Question id 19

{
  "channel" : "faq",
  "excludedQuestions" : [19],
  "searchFilters": [
      {
          "name": "thematic-system-name-859",
          "type": "thematic"
      }
  ]
}

Questions within Smart FAQ channel that were updated by user with id 10 and 11 between March 1 and 31, 2022

{
  "channel" : "faq",
  "updatedBy": [10, 11],
  "dateFilter": {
    "field": "updatedAt",
    "startDate": "2022-03-01",
    "endDate": "2022-03-31"
  }
}

Search results within Smart FAQ Channel

{
  "channel": "faq",
  "query": "my search query",
  "useSuggester": true
}

Single Question by slug

{
  "channel": "faq",
  "questionSlug": "my-question-slug"
}

Questions filtered by Thematic with slug "my-thematic"

{
  "channel": "faq",
  "searchFilters": [
      {
          "slug": "my-thematic-slug",
          "type": "thematic"
      }
  ]
}

Questions filtered using Tags with name "my-tag-1" OR "my-tag-2"

{
  "channel": "faq",
  "searchFilters": [
      {
          "name": "my-tag-1",
          "type": "tag"
      },
      {
          "name": "my-tag-2",
          "type": "tag"
      }
  ],
  "searchFiltersOperators": [
     { "tag" : "OR" }
   ]
}

Questions filtered by Thematic with systemName "tag-system-name-568" AND Tag with systemName "my-tag-14"

{
  "channel": "faq",
  "searchFilters": [
      {
          "name": "thematic-system-name-859",
          "type": "thematic"
      },
      {
          "name": "tag-system-name-568",
          "type": "tag"
      }
  ]
}

channel	string Enum: "faq" "push" "bot"
promoted	boolean
frequent	boolean
query	string <= 255 characters
useSuggester	boolean
excludedQuestions	Array of integers
questionSlug	string^[a-z0-9]+(-?[a-z0-9]+)*$
updatedBy	Array of integers
	object
	Array of SearchFiltersThematicName (object) or SearchFiltersThematicSlug (object) or SearchFiltersTagName (object)
	Array of searchFiltersOperatorsTag (object) or searchFiltersOperatorsThematic (object)
limit	integer <= 200

Responses

Request samples

Payload

Content type

application/json

{"channel": "faq",
"promoted": false,
"frequent": false,
"query": "How to finalize my baking",
"useSuggester": true,
"excludedQuestions": [[185,
198
]
],
"questionSlug": "my-question-slug",
"updatedBy": [[1,
2
]
],
"dateFilter": {"field": "createdAt",
"startDate": "2022-03-01",
"endDate": "2022-03-31 (defaults to current Date)"
},
"searchFilters": [{"type": "thematic",
"name": "thematic-system-name-859"
}
],
"searchFiltersOperators": [{"tag": "OR"
}
],
"limit": 50
}

Response samples

Content type

application/json

{"meta": {"limit": 25,
"currentItems": 25,
"totalItems": 151,
"offset": 1,
"currentPage": 1,
"numberPage": 7,
"originalQuery": "How to finalize my baking",
"executedQuery": "How to finalize my booking"
},
"data": [{"id": 1874,
"title": "This is the title of the Question",
"slug": "this-is-slug-of-question",
"metaTitle": "This is a custom meta title",
"metaDescription": "This is a custom meta description",
"thematics": [{"id": 198,
"name": "my-thematic-198",
"description": "This is the description of the Thematic with id 198",
"title": "My thematic",
"parentId": 4,
"position": 10,
"slug": "my-thematic"
}
],
"tags": [{"id": 14,
"name": "my-tag-14",
"description": "This is the description of the Tag with id 14",
"title": "My tag"
}
],
"contacts": [4
],
"linkedQuestion": {"id": 2086,
"title": "This is the title of the linked question",
"slug": "this-is-slug-of-linked-question"
},
"canonicalUrl": "string (valid URL, max length 500) or null or not present"
}
]
}

Fetch a (list of) Thematic(s) depend on specified Filters Deprecated

Authorizations:

bearerAuth

path Parameters

id

required

integer

The knowledgebase Id that needs to be fetched.

query Parameters

page	integer Example: page=1 Page identifier
limit	integer <= 200 Example: limit=25 Items per page

header Parameters

Accept-Language

required

string

Example: fr

Language locale to filter api results

Request Body schema: application/json

Example of payloads to fetch :

Thematics filtered by SystemName "how-to-make-booking-987"

{
  "channel": "faq",
  "searchFilters": [
      {
          "name": "how-to-make-booking-987",
          "type": "thematic"
      }
  ]
}

Thematics filtered by slug "my-thematic"

{
  "channel": "faq",
  "searchFilters": [
      {
          "slug": "my-thematic-slug",
          "type": "thematic"
      }
  ]
}

channel	string Enum: "faq" "push" "bot"
promoted	boolean
frequent	boolean
excludedQuestions	Array of integers
questionSlug	string^[a-z0-9]+(-?[a-z0-9]+)*$
	Array of SearchFiltersThematicName (object) or SearchFiltersThematicSlug (object) or SearchFiltersTagName (object)
limit	integer <= 200

Responses

Request samples

Payload

Content type

application/json

{"channel": "faq",
"promoted": false,
"frequent": false,
"excludedQuestions": [[185,
198
]
],
"questionSlug": "my-question-slug",
"searchFilters": [{"type": "thematic",
"name": "thematic-system-name-859"
}
],
"limit": 50
}

Response samples

Content type

application/json

{"meta": {"limit": 25,
"currentItems": 25,
"totalItems": 151,
"offset": 1,
"currentPage": 1,
"numberPage": 7
},
"data": [{"id": 198,
"name": "my-thematic-198",
"description": "This is the description of the Thematic with id 198",
"title": "My thematic",
"parentId": 4,
"position": 10,
"slug": "my-thematic"
}
]
}

Search API

Performance oriented API to fetch list of items

Fetch a list of Documents ( questions and/or guides and/or documents)

Authorizations:

bearerAuth

path Parameters

id

required

integer

The knowledgebase Id that needs to be fetched.

query Parameters

page	integer Example: page=1 Page identifier
limit	integer <= 200 Example: limit=25 Items per page
sort	string Enum: "createdAt" "updatedAt" "viewsCount" "votesYesCount" Example: sort=createdAt Property used to sort results (not applicable when body "query" parameter is set)
order	string Enum: "asc" "desc" Example: order=asc direction used when sort query param is defined (not applicable when body "query" parameter is set)

header Parameters

Accept-Language

required

string

Example: fr

Language locale to filter api results

Request Body schema: application/json

Example of payloads to fetch :

Promoted Questions within Smart FAQ Channel

 {
   "knowledgeType":["question"]
   "channel": "faq",
   "promoted": true
 }

All thematics

 {
   "knowledgeType":["question","guide"],
   "resourceType": "thematic"
 }

Frequent Questions and Guides within Smart FAQ Channel

{
   "knowledgeType":["question","guide"]
   "channel": "faq",
   "frequent": true
}

Related Questions and Guides within Smart FAQ channel for thematic systemName "how-to-make-booking-987" and excluding Question with id 19

{
   "knowledgeType":["question","guide"],
   "channel" : "faq",
   "excludedIds" :{
      "question" :[19]
   },
  "filters": [
      {
          "name": "thematic-system-name-859",
          "type": "thematic"
      }
  ]
}

Questions within Smart FAQ channel that were updated by user with id 10 and 11 between March 1 and 31, 2022

{
  "knowledgeType":["question"],
  "channel" : "faq",
  "updatedBy": [10, 11],
  "dateFilter": {
    "field": "updatedAt",
    "startDate": "2022-03-01",
    "endDate": "2022-03-31"
  }
}

Search results within Smart FAQ Channel

{
   "knowledgeType" :["question"],
    "channel": "faq",
    "query": "my search query",
    "useSuggester": true
}

Single Question by slug

{
  "knowledgeType" :["question"],
  "channel": "faq",
  "slug": "my-question-slug"
}

Questions filtered by Thematic with slug "my-thematic"

{
  "knowledgeType" :["question"],
  "channel": "faq",
  "filters": [
      {
          "slug": "my-thematic-slug",
          "type": "thematic"
      }
  ]
}

Questions filtered using Tags with name "my-tag-1" OR "my-tag-2"

{
  "knowledgeType" :["question"],
  "channel": "faq",
  "filters": [
      {
          "name": "my-tag-1",
          "type": "tag"
      },
      {
          "name": "my-tag-2",
          "type": "tag"
      }
  ],
  "filtersOperators": [
     { "tag" : "OR" }
   ]
}

Questions filtered by Thematic with systemName "tag-system-name-568" AND Tag with systemName "my-tag-14"

{
  "knowledgeType" :["question"],
  "channel": "faq",
  "filters": [
      {
          "name": "thematic-system-name-859",
          "type": "thematic"
      },
      {
          "name": "tag-system-name-568",
          "type": "tag"
      }
  ]
}

resourceType	string or null Enum: "knowledge" "thematic" Which resourceType should be returned (defaults to knowledge)
knowledgeType	Array of strings (knowledgeType) non-empty Items Enum: "question" "guide" An array of at least one knowledgeType
channel	string Enum: "faq" "push" "bot"
promoted	boolean
frequent	boolean
query	string <= 255 characters
useSuggester	boolean
	object
slug	string^[a-z0-9]+(-?[a-z0-9]+)*$
updatedBy	Array of integers
	object
	Array of SearchFiltersThematicName (object) or SearchFiltersThematicSlug (object) or SearchFiltersTagName (object)
	Array of searchFiltersOperatorsTag (object) or searchFiltersOperatorsThematic (object)
limit	integer <= 200
searchStrictnessThreshold	integer >= 1

Responses

Request samples

Payload

Content type

application/json

{"resourceType": "knowledge",
"knowledgeType": ["question"
],
"channel": "faq",
"promoted": false,
"frequent": false,
"query": "How to finalize my baking",
"useSuggester": true,
"excludedIds": {"question": [185,
198
],
"guide": [533,
87
]
},
"slug": "my-question-or-guide-slug",
"updatedBy": [1,
2
],
"dateFilter": {"field": "createdAt",
"startDate": "2022-03-01",
"endDate": "2022-03-31 (defaults to current Date)"
},
"filters": [{"type": "thematic",
"name": "thematic-system-name-859"
}
],
"filtersOperators": [{"tag": "OR"
}
],
"limit": 50,
"searchStrictnessThreshold": 30
}

Response samples

Content type

application/json

{"meta": {"limit": 25,
"currentItems": 25,
"totalItems": 151,
"offset": 1,
"currentPage": 1,
"numberPage": 7,
"originalQuery": "How to finalize my baking",
"executedQuery": "How to finalize my booking"
},
"data": [{"documentId": 1874,
"knowledgeType": "question",
"title": "This is the title of the Question",
"slug": "this-is-slug-of-question",
"metaTitle": "This is a custom meta title",
"metaDescription": "This is a custom meta description",
"thematics": [{"id": 198,
"name": "my-thematic-198",
"description": "This is the description of the Thematic with id 198",
"title": "My thematic",
"parentId": 4,
"position": 10,
"slug": "my-thematic"
}
],
"tags": [{"id": 14,
"name": "my-tag-14",
"description": "This is the description of the Tag with id 14",
"title": "My tag"
}
],
"contacts": [4
],
"linkedQuestion": {"id": 2086,
"title": "This is the title of the linked question",
"slug": "this-is-slug-of-linked-question"
},
"canonicalUrl": "string (valid URL, max length 500) or null or not present"
}
]
}

Generic API

Fetch allowed Knowledge bases

Authorizations:

bearerAuth

header Parameters

Accept-Language

required

string

Example: fr

Language locale to filter api results

Responses

Response samples

Content type

application/json

{"meta": {"limit": 25,
"currentItems": 25,
"totalItems": 151,
"offset": 1,
"currentPage": 1,
"numberPage": 7
},
"data": [{"id": 12,
"name": "Smart Tribune internal HelpCenter",
"account": 4,
"languages": [{"id": 2,
"locale": "fr"
}
],
"channels": [{"id": 1,
"name": "Smart FAQ",
"systemName": "faq"
}
]
}
]
}

Fetch Response related to a specified Question for a specific Channel

Authorizations:

bearerAuth

path Parameters

id required	integer The Knowledgebase id that needs to be fetched.
questionId required	integer The Question id that needs to be fetched.
channelId required	integer The Channel id that needs to be fetched.

query Parameters

customResponses

string

Example: customResponses=b2b-114,b2c-115

List of tags names used for custom responses (separated by comma)

header Parameters

Accept-Language

required

string

Example: fr

Language locale to filter api results

Responses

Response samples

Content type

application/json

{"meta": {"limit": 25,
"currentItems": 25,
"totalItems": 151,
"offset": 1,
"currentPage": 1,
"numberPage": 7
},
"data": [{"id": 16,
"questionId": 14,
"channel": {"id": 1,
"name": "Smart FAQ",
"systemName": "faq"
},
"content": {"id": 156,
"body": "This is the content of the response. lorem ipsum lorem ipsum lorem ipsum lorem ipsum lorem ipsum lorem ipsum lorem ipsum lorem ipsum lorem ipsum lorem ipsum lorem ipsum lorem ipsum lorem ipsum lorem ipsum lorem ipsum lorem ipsum lorem ipsum",
"htmlBody": "<p>This is the content of the response.</p><p>lorem ipsum lorem ipsum lorem ipsum lorem ipsum lorem ipsum lorem ipsum lorem ipsum lorem ipsum lorem ipsum <img src='https://uploads.app.smart-tribune.com/accounts/9999/knowledgeBase/9999/c3d2282f-d9b2-4cfb-9c40-07d3d1aa50d4.png' /> lorem ipsum lorem ipsum lorem ipsum lorem ipsum lorem ipsum lorem ipsum lorem ipsum lorem ipsum</p>",
"locale": "fr",
"status": "published",
"images": [{"id": 156,
"url": "https://uploads.app.smart-tribune.com/accounts/9999/knowlegebases/9999/c3d2282f-d9b2-4cfb-9c40-07d3d1aa50d4.png"
}
]
}
}
]
}

Post a Response Satisfaction on a specified Response

Authorizations:

bearerAuth

path Parameters

id required	integer The knowledgebase id that needs to be fetched.
questionId required	integer The Question id that needs to be fetched.
responseId required	integer The Response id that needs to be fetched.

header Parameters

Accept-Language

required

string

Example: fr

Language locale to filter api results

Request Body schema: application/json

positive

required

boolean

Responses

Request samples

Payload

Content type

application/json

{"positive": true
}

Response samples

Content type

application/json

{"id": 1,
"positive": true,
"locale": "fr",
"responseId": 4,
"reasonId": null
}

Fetch available negative vote Reasons

Authorizations:

bearerAuth

path Parameters

id

required

integer

The Knowledgebase id that needs to be fetched.

header Parameters

Accept-Language

required

string

Example: fr

Language locale to filter api results

Responses

Response samples

Content type

application/json

{"meta": {"limit": 25,
"currentItems": 25,
"totalItems": 151,
"offset": 1,
"currentPage": 1,
"numberPage": 7
},
"data": [{"id": 6,
"value": "Does not answer to the question",
"locale": "fr",
"knowledgeBaseId": 2
}
]
}

Fetch available comments for negative vote Reasons

Authorizations:

bearerAuth

path Parameters

id

required

integer

The Knowledgebase id that needs to be fetched.

query Parameters

startDate required	string Example: startDate=2021-06-12 Start Date in yyyy-mm-dd format. Comments fetched are created at startDate (between 00:00:00 and 23:59:59)
channel required	string Example: channel=faq The channel name of the responses affected by comments
extended	boolean Example: extended=true used to display additional information : thematics list and response content associated to the question

header Parameters

Accept-Language

required

string

Example: fr

Language locale to filter api results

Responses

Response samples

Content type

application/json

{"meta": {"limit": 25,
"currentItems": 25,
"totalItems": 151,
"offset": 1,
"currentPage": 1,
"numberPage": 7
},
"data": [{"date": "2021-06-16 10:37:36",
"comment": "Very bad response content !",
"questionTitle": "This is the title of the question",
"questionId": 28,
"reasonTitle": "Does not answer to the question",
"thematics": "thematic 1, thematic2",
"responseContent": "this is the content of the response"
}
]
}

Update a Response Satisfaction on a specified Response to provide a Reason or Comment

Authorizations:

bearerAuth

path Parameters

id required	integer The knowledgebase id that needs to be fetched.
questionId required	integer The Question id that needs to be fetched.
responseId required	integer The Response id that needs to be fetched.
satisfactionId required	integer The Response satisfaction id that needs to be fetched.

header Parameters

Accept-Language

required

string

Example: fr

Language locale to filter api results

Request Body schema: application/json

reason required	integer
	object

Responses

Request samples

Payload

Content type

application/json

{"reason": 6,
"responseSatisfactionComment": {"content": "Additional comment for the reason"
}
}

Response samples

Content type

application/json

{"id": 1,
"positive": true,
"locale": "fr",
"responseId": 4,
"reason": {"id": 6,
"value": "Does not answer to the question",
"locale": "fr",
"knowledgeBaseId": 2
}
}

Fetch available Contact methods

Authorizations:

bearerAuth

path Parameters

id

required

integer

The Knowledgebase id that needs to be fetched.

header Parameters

Accept-Language

required

string

Example: fr

Language locale to filter api results

Responses

Response samples

Content type

application/json

{"meta": {"limit": 25,
"currentItems": 25,
"totalItems": 151,
"offset": 1,
"currentPage": 1,
"numberPage": 7
},
"data": [{"id": 4,
"systemName": "contact-phone-4",
"name": "VIP Phone contact",
"locale": "fr",
"method": "phone",
"knowledgeBaseId": 2,
"contactConfiguration": {"phone": "0102030405",
"title": "Contact us by phone",
"description": "Our support center is open from 24/24, 7/7",
"applyAllQuestions": false,
"isActive": true,
"channels": ["faq"
],
"tags": ["tag-1"
]
}
}
]
}