Aller au contenu principal

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 ...)

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

Content type
application/json
{
  • "apiKey": "fc5e038d38a57032085441e7fe7010b0",
  • "apiSecret": "6ec691bb4195f541374adafcb2484aad"
}

Response samples

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

Content type
application/json
{
  • "channel": "faq",
  • "promoted": false,
  • "frequent": false,
  • "query": "How to finalize my baking",
  • "useSuggester": true,
  • "excludedQuestions": [
    ],
  • "questionSlug": "my-question-slug",
  • "updatedBy": [
    ],
  • "dateFilter": {
    },
  • "searchFilters": [
    ],
  • "searchFiltersOperators": [
    ],
  • "limit": 50
}

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "data": [
    ]
}

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

Content type
application/json
{
  • "channel": "faq",
  • "promoted": false,
  • "frequent": false,
  • "excludedQuestions": [
    ],
  • "questionSlug": "my-question-slug",
  • "searchFilters": [
    ],
  • "limit": 50
}

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "data": [
    ]
}

Search API

Performance oriented API to fetch list of items

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

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

Content type
application/json
{
  • "resourceType": "knowledge",
  • "knowledgeType": [
    ],
  • "channel": "faq",
  • "promoted": false,
  • "frequent": false,
  • "query": "How to finalize my baking",
  • "useSuggester": true,
  • "excludedIds": {
    },
  • "slug": "my-question-or-guide-slug",
  • "updatedBy": [
    ],
  • "dateFilter": {
    },
  • "filters": [
    ],
  • "filtersOperators": [
    ],
  • "limit": 50,
  • "searchStrictnessThreshold": 30
}

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "data": [
    ]
}

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": {
    },
  • "data": [
    ]
}

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": {
    },
  • "data": [
    ]
}

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

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": {
    },
  • "data": [
    ]
}

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": {
    },
  • "data": [
    ]
}

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

Content type
application/json
{
  • "reason": 6,
  • "responseSatisfactionComment": {
    }
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "positive": true,
  • "locale": "fr",
  • "responseId": 4,
  • "reason": {
    }
}

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": {
    },
  • "data": [
    ]
}