Smart Tribune V2 API (1.0.5)
The purpose of this API is to allow developers to build front-end interfaces for displaying knowledge base data (Faq, Helpbox, Chatbot ...)
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.
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 |
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
{- "apiKey": "fc5e038d38a57032085441e7fe7010b0",
- "apiSecret": "6ec691bb4195f541374adafcb2484aad"
}
Response samples
- 200
- 401
- 429
- 503
{- "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}
Fetch a (list of) Question(s) depend on specified Filters Deprecated
Authorizations:
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
{- "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
- 200
- 400
- 401
- 403
- 404
- 429
- 503
{- "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:
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
{- "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
- 200
- 400
- 401
- 403
- 404
- 429
- 503
{- "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"
}
]
}
Fetch a list of Documents ( questions and/or guides ) or Thematics
Authorizations:
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
{- "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
- 200
- 400
- 401
- 403
- 404
- 429
- 503
{- "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"
}
]
}
Fetch allowed Knowledge bases
Authorizations:
header Parameters
Accept-Language required | string Example: fr Language locale to filter api results |
Responses
Response samples
- 200
- 400
- 401
- 403
- 404
- 429
- 503
{- "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:
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
- 200
- 400
- 401
- 403
- 404
- 429
- 503
{- "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": [
]
}
}
]
}
Post a Response Satisfaction on a specified Response
Authorizations:
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
{- "positive": true
}
Response samples
- 200
- 400
- 401
- 403
- 404
- 429
- 503
{- "id": 1,
- "positive": true,
- "locale": "fr",
- "responseId": 4,
- "reasonId": null
}
Fetch available negative vote Reasons
Authorizations:
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
- 200
- 400
- 401
- 403
- 404
- 429
- 503
{- "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:
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
- 200
- 400
- 401
- 403
- 404
- 429
- 503
{- "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:
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
{- "reason": 6,
- "responseSatisfactionComment": {
- "content": "Additional comment for the reason"
}
}
Response samples
- 200
- 400
- 401
- 403
- 404
- 429
- 503
{- "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:
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
- 200
- 400
- 401
- 403
- 404
- 429
- 503
{- "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"
]
}
}
]
}