Smart Tribune V2 API (1.0.6)

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 ...) and to interact with AI-powered generation features.

Quick Start Guide

1. Authenticate

Obtain a JWT token by calling POST /v1/auth with your API credentials (apiKey and apiSecret). The token is valid for 1 hour and must be included in all subsequent requests.

2. Explore Knowledge Bases

Use GET /v1/knowledge-bases to retrieve the list of knowledge bases you have access to.

3. Search Content

Use POST /v1/knowledge-bases/{id}/search to search for questions, guides, or documents with powerful filtering options.

4. Get AI Responses (Optional)

Use POST /v1/ai/generate for immediate AI responses, or POST /v1/ai/generate/async for webhook-based responses.

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.

Token Lifecycle:

Tokens expire after 1 hour
When a token expires, you'll receive a 401 Unauthorized response
Request a new token using the /v1/auth endpoint

Supported Languages

The API supports multiple languages through the Accept-Language header. Language code format like:

fr - French
fr_FR - French (France)
fr_CA - French (Canada)

Refer to your Knowledge Base settings for the list of supported languages

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.

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 (deprecated)
POST /v1/knowledge-bases/{id}/filtered/thematics	10 (deprecated)
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
POST /v1/ai/generate	5
POST /v1/ai/generate/async	5

Authentication

Obtain JWT tokens for API access. Tokens are valid for 1 hour and required for all other endpoints.

Authenticate through our API

Authenticate using your API credentials and retrieve a JWT token.

Important: The token expires after 1 hour. Store it securely and refresh when needed.

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": "your-api-key-here",
"apiSecret": "your-api-secret-here"
}

Response samples

200
401
429
503

Content type

application/json

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

Filtered API

⚠️ DEPRECATED - Legacy endpoints for filtering questions and thematics. Use Search API instead.

⚠️ DEPRECATED - Fetch a (list of) Question(s) depend on specified Filters Deprecated

This endpoint is deprecated. Please use POST /v1/knowledge-bases/{id}/search instead.

Migration Guide:

Replace searchFilters array with filterLogic.and or filterLogic.or
Use knowledgeType: ["question"] to filter by questions only
Replace questionSlug with slug
The new /search endpoint offers better performance and more flexible filtering

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 Include full tag objects in the response payload. When false (default): Only tag IDs are returned (lighter response) When true: Complete tag objects with names, descriptions, and metadata (heavier response) Use case: Set to true when you need tag details for display or filtering
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

⚠️ DEPRECATED - Use the Search API endpoint instead. Legacy examples provided for migration reference.

channel	string Enum: "faq" "push" "bot"
promoted	boolean
frequent	boolean
query	string <= 255 characters
useSuggester	boolean Enable typo tolerance and smart query correction for better search results. When true: "baking" → "booking", "pasword" → "password" (fuzzy matching enabled) When false: exact term matching only Recommended: true for user-facing search interfaces
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

Example

Promoted Questions

DEPRECATED: Use Search API with knowledgeType instead

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

Response samples

Content type

application/json

Legacy response format - migrate to /search endpoint

{"meta": {"limit": 25,
"currentItems": 2,
"totalItems": 2,
"offset": 1,
"currentPage": 1,
"numberPage": 1,
"originalQuery": null,
"executedQuery": null
},
"data": [{"id": 1874,
"title": "How to reset your password",
"slug": "how-to-reset-your-password",
"metaTitle": "Password Reset Guide",
"metaDescription": "Step-by-step password reset",
"thematics": [{"id": 198,
"name": "account-management",
"description": "Account settings and management",
"title": "Account Management",
"parentId": null,
"position": 1,
"slug": "account-management"
}
],
"tags": [{"id": 14,
"name": "password-reset",
"description": "Password recovery",
"title": "Password Reset"
}
],
"contacts": [1,
3
],
"linkedQuestion": {"id": 2086,
"title": "Forgot username",
"slug": "forgot-username"
},
"canonicalUrl": "https://help.example.com/password-reset"
}
]
}

⚠️ DEPRECATED - Fetch a (list of) Thematic(s) depend on specified Filters Deprecated

This endpoint is deprecated. Please use POST /v1/knowledge-bases/{id}/search instead.

Migration Guide:

Use resourceType: "thematic" to fetch thematics
Replace searchFilters array with filterLogic.and or filterLogic.or
The new /search endpoint provides consistent filtering across all resource types

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

⚠️ DEPRECATED - Use the Search API with resourceType: "thematic" instead. Legacy examples provided for migration reference.

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

Example

Filter by System Name

DEPRECATED: Use Search API with resourceType and filterLogic instead

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

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

Modern search API with advanced filtering, supports questions, guides, and documents with AND/OR logic.

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

Search for questions, guides, documents, or thematics with flexible filtering options. Select an example below to see common use cases.

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 Enable typo tolerance and smart query correction for better search results. When true: "baking" → "booking", "pasword" → "password" (fuzzy matching enabled) When false: exact term matching only Recommended: true for user-facing search interfaces
	object
slug	string^[a-z0-9]+(-?[a-z0-9]+)*$
updatedBy	Array of integers
	object
	Array of SearchFiltersThematicName (object) or SearchFiltersThematicSlug (object) or SearchFiltersTagName (object) Deprecated
	Array of searchFiltersOperatorsTag (object) or searchFiltersOperatorsThematic (object) Deprecated
	object
limit	integer <= 200
searchStrictnessThreshold	integer >= 1 Control search result relevance threshold (1-100). Lower values (1-30): More lenient, returns more results (higher recall) Higher values (70-100): Stricter, returns only highly relevant results (higher precision) Default: 30 (balanced between recall and precision) Use case: Increase for precise searches, decrease for broader discovery

Responses

Request samples

Payload

Content type

application/json

Example

Promoted Questions

Fetch promoted questions for display on homepage or featured section

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

Response samples

Content type

application/json

Example

Search results for questions

{"meta": {"limit": 25,
"currentItems": 3,
"totalItems": 3,
"offset": 1,
"currentPage": 1,
"numberPage": 1,
"originalQuery": "How to reset pasword",
"executedQuery": "How to reset password"
},
"data": [{"documentId": 1874,
"knowledgeType": "question",
"title": "How to reset your password",
"slug": "how-to-reset-your-password",
"metaTitle": "Password Reset Guide",
"metaDescription": "Step-by-step guide to reset your account password",
"thematics": [{"id": 198,
"name": "my-thematic-198",
"description": "Account Management",
"title": "Account Settings",
"parentId": null,
"position": 1,
"slug": "account-management"
}
],
"tags": [{"id": 14,
"name": "password-reset",
"description": "Password recovery tag",
"title": "Password Reset"
}
],
"contacts": [1,
3
],
"linkedQuestion": {"id": 2086,
"title": "Forgot my username",
"slug": "forgot-my-username"
},
"canonicalUrl": "https://help.example.com/password-reset"
}
]
}

Knowledge Base Operations

Manage knowledge bases, retrieve responses, handle user feedback, and access contact information.

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": 2,
"totalItems": 2,
"offset": 1,
"currentPage": 1,
"numberPage": 1
},
"data": [{"id": 12,
"name": "Smart Tribune internal HelpCenter",
"account": 4,
"languages": [{"id": 1,
"locale": "fr"
},
{"id": 2,
"locale": "en"
}
],
"channels": [{"id": 1,
"name": "Smart FAQ",
"systemName": "faq"
},
{"id": 2,
"name": "Smart Push",
"systemName": "push"
}
]
},
{"id": 15,
"name": "Customer Support KB",
"account": 4,
"languages": [{"id": 1,
"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": 1,
"totalItems": 1,
"offset": 1,
"currentPage": 1,
"numberPage": 1
},
"data": [{"id": 16,
"questionId": 14,
"channel": {"id": 1,
"name": "Smart FAQ",
"systemName": "faq"
},
"content": {"id": 156,
"body": "To reset your password, follow these steps: 1. Go to the login page 2. Click 'Forgot Password' 3. Enter your email address 4. Check your inbox for the reset link 5. Follow the link and create your new password.",
"htmlBody": "<p>To reset your password, follow these steps:</p><ol><li>Go to the login page</li><li>Click 'Forgot Password'</li><li>Enter your email address</li><li>Check your inbox for the reset link</li><li>Follow the link and create your new password</li></ol>",
"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"
]
}
}
]
}

AI Generation

AI-powered response generation with conversation context. Supports both synchronous (immediate) and asynchronous (webhook-based) modes.

Synchronous AI Generation

Use this mode when you want to receive the AI-generated response directly in the same HTTP request.

Use Case: Real-time chat interfaces, FAQ widgets, immediate user interactions.

Response Time: Typically 1-3 seconds depending on query complexity.

Authorizations:

bearerAuth

header Parameters

X-Conversation-Id

string

Identifier for tracking the conversation context

Request Body schema: application/json

application required	string non-empty Identifier for the calling application (provided by ST)
query required	string non-empty The user's query
	Array of objects (HistoryItem) Conversation history as an array of Q-A objects

Responses

Request samples

Payload

Content type

application/json

Example

Simple query without history

{"application": "my-chatbot-app",
"query": "How do I reset my password?"
}

Response samples

200

Content type

application/json

{"response": "To reset your password: 1. Go to the login page 2. Click 'Forgot Password' 3. Enter your email 4. Check your inbox for the reset link 5. Follow the link and create a new password",
"response_sources": ["kb-article-123",
"faq-password-reset"
],
"status_code": 200,
"error": null,
"circuit_breaker": null,
"guard": null,
"criteria_results": null,
"missing_data": false,
"extra_config": ""
}

Asynchronous AI Generation

Using this mode, the client must provide at least a webhook_url in the body and an X-Webhook-Token header to allow us to send back the response once it has been generated.

Use Case: Background processing, bulk operations, non-time-sensitive interactions.

Flow

The client calls this endpoint, including:
- A webhook URL (in body)
- A webhook token (header)
- A unique conversation identifier (optional - header)
The server responds with HTTP status 202 (Accepted) and returns a JSON payload containing a request_id for tracking and debugging purposes.
Once the response is generated, it is sent to the specified webhook URL, authenticating with the provided webhook token as a Bearer JWT header. The payload sent is the same as the synchronous response payload.

Security Best Practices:

Use HTTPS-only webhook URLs
Validate the Bearer token in your webhook handler
Implement request signing verification
Set short token expiration times
Log all webhook deliveries for audit purposes

Authorizations:

bearerAuth

header Parameters

X-Webhook-Token required	string JWT token to authenticate the callback delivery
X-Conversation-Id	string Identifier for tracking the conversation context

Request Body schema: application/json

application required	string non-empty Identifier for the calling application (provided by ST)
query required	string non-empty The user's query
	Array of objects (HistoryItem) Conversation history as an array of Q-A objects
webhook_url required	string <uri> non-empty URL that will receive the onCompletion callback

Responses

Callbacks

Request samples

Payload

Content type

application/json

Example

Async request with webhook

{"application": "my-chatbot-app",
"query": "How do I reset my password?",
"webhook_url": "https://my-app.com/webhooks/ai-response"
}

Response samples

202

Content type

application/json

{"request_id": "82c1cfdb-d305-473c-b4e7-43b5899b8985"
}

Callback payload samples

Callback

POST: AI generation completed (webhook)

Content type

application/json

{"circuit_breaker": null,
"criteria_results": null,
"error": null,
"extra_config": "string",
"guard": null,
"missing_data": null,
"response": "string",
"response_sources": [ ],
"status_code": 200
}