Triniti.ai v2.0
Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.
Triniti Api Reference
The API is organized around REST. Our API has predictable resource-oriented URLs, accepts json-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.
You can use the REST API in test mode, which does not affect your live data or interact with the networks. The API key you use to authenticate the request determines whether the request is live mode or test mode.
Subscribe to Triniti's API announce mailing list for updates.
Authentication
The Triniti API uses API keys to authenticate requests. You can view and manage your API keys in the portal Dashboard.
Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.
You need to provide two headers X-Api-Key and X-Api-Secret. This pair of headers acts as the credentials.
All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.
Versioning
When we make backwards-incompatible changes to the API, we release new, dated versions. The current version is 2.0. Read our API upgrades guide to see our API changelog and to learn more about backwards compatibility.
All requests will use your account API settings, unless you override the API version. The changelog lists every available version. Note that events generated by API requests will always be structured according to your account API version.
You can visit your Dashboard to upgrade your API version. As a precaution, use API versioning to test a new API version before committing to an upgrade.
Base URLs:
POST /process
Code samples
# You can also use wget
curl -X POST https://api.triniti.ai/v2/process \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'X-Api-Key: string' \
-H 'X-Api-Secret: string' \
-H 'X-User-Id: string' \
-H 'X-Session-Id: string'
POST https://api.triniti.ai/v2/process HTTP/1.1
Host: api.triniti.ai
Content-Type: application/json
Accept: application/json
X-Api-Key: string
X-Api-Secret: string
X-User-Id: string
X-Session-Id: string
var headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'X-Api-Key':'string',
'X-Api-Secret':'string',
'X-User-Id':'string',
'X-Session-Id':'string'
};
$.ajax({
url: 'https://api.triniti.ai/v2/process',
method: 'post',
headers: headers,
success: function(data) {
console.log(JSON.stringify(data));
}
})
const fetch = require('node-fetch');
const inputBody = '{
"input": "I want to send to Amol",
"previous-inputs": [
"I want to transfer 50 rs"
],
"prompt": "who do you want to transfer to?",
"current-intent": "txn-moneymovement",
"expected-entities": [
"banking.payee_name",
"sys.amount",
"banking.from_account"
],
"triniti-state-context": "",
"client-state-context": {
"user": "a",
"txn": 124345
},
"options": [
"similar",
"fragment",
"compression",
"debug",
"semantics",
"discourse",
"expansion"
]
}';
const headers = {
'Content-Type':'application/json',
'Accept':'application/json',
'X-Api-Key':'string',
'X-Api-Secret':'string',
'X-User-Id':'string',
'X-Session-Id':'string'
};
fetch('https://api.triniti.ai/v2/process',
{
method: 'POST',
body: inputBody,
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
require 'rest-client'
require 'json'
headers = {
'Content-Type' => 'application/json',
'Accept' => 'application/json',
'X-Api-Key' => 'string',
'X-Api-Secret' => 'string',
'X-User-Id' => 'string',
'X-Session-Id' => 'string'
}
result = RestClient.post 'https://api.triniti.ai/v2/process',
params: {
}, headers: headers
p JSON.parse(result)
import requests
headers = {
'Content-Type': 'application/json',
'Accept': 'application/json',
'X-Api-Key': 'string',
'X-Api-Secret': 'string',
'X-User-Id': 'string',
'X-Session-Id': 'string'
}
r = requests.post('https://api.triniti.ai/v2/process', params={
}, headers = headers)
print r.json()
URL obj = new URL("https://api.triniti.ai/v2/process");
HttpURLConnection con = (HttpURLConnection) obj.openConnection();
con.setRequestMethod("POST");
int responseCode = con.getResponseCode();
BufferedReader in = new BufferedReader(
new InputStreamReader(con.getInputStream()));
String inputLine;
StringBuffer response = new StringBuffer();
while ((inputLine = in.readLine()) != null) {
response.append(inputLine);
}
in.close();
System.out.println(response.toString());
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Content-Type": []string{"application/json"},
"Accept": []string{"application/json"},
"X-Api-Key": []string{"string"},
"X-Api-Secret": []string{"string"},
"X-User-Id": []string{"string"},
"X-Session-Id": []string{"string"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("POST", "https://api.triniti.ai/v2/process", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
POST /process
Analyse the provided text using triniti v2 API engine.
Body parameter
{
"input": "I want to send to Amol",
"previous-inputs": [
"I want to transfer 50 rs"
],
"prompt": "who do you want to transfer to?",
"current-intent": "txn-moneymovement",
"expected-entities": [
"banking.payee_name",
"sys.amount",
"banking.from_account"
],
"triniti-state-context": "",
"client-state-context": {
"user": "a",
"txn": 124345
},
"options": [
"similar",
"fragment",
"compression",
"debug",
"semantics",
"discourse",
"expansion"
]
}
Parameters
Parameter |
In |
Type |
Required |
Description |
---|---|---|---|---|
X-Api-Key | header | string | true | Api key of the workspace that you want to analyse |
X-Api-Secret | header | string | true | Api Secret of the workspace |
X-User-Id | header | string | true | User-ID that you want to associate the request with |
X-Session-Id | header | string | true | Session-ID to associate the context of the logged in user. |
body | body | Request Object | true | The endpoint is used to process the natural language in the form of text. The response contains structured information which can be used to perform appropriate actions. |
Example responses
200 Response
{
"version": "string",
"client-state-context": "string",
"query-processor": {
"input": "string",
"corrected": "string",
"normalised": "string",
"punctuated": "string",
"compressed": "string",
"cleaned": "string"
},
"output": [
{
"query": "string",
"expanded": "string",
"expansion-confidence": 0,
"adversity": 0,
"emotion": "string",
"emotion-score": 0,
"subject-of-emotion": "string",
"intention": {
"confirmation": true,
"cancellation": true,
"negation": true
},
"product-actions": {
"products": "string",
"actions": "string"
},
"semantic-roles": {
"general-purpose": [
"string"
],
"cause": [
"string"
],
"direction": [
"string"
],
"discourse-marker": [
"string"
],
"extent": [
"string"
],
"location": [
"string"
],
"manner": [
"string"
],
"modal-verb": [
"string"
],
"negation-marker": "string",
"purpose": [
"string"
],
"predication": [
"string"
],
"reciprocal": [
"string"
],
"temporal": [
"string"
]
},
"context-changed": true,
"discourse-relationship": {
"temporal-asynchronous": 0,
"temporal-synchronous": 0,
"contingency-cause": 0,
"contingency-pragmatic-cause": 0,
"comparison-contrast": 0,
"comparison-concession": 0,
"expansion-conjunction": 0,
"expansion-instantiation": 0,
"expansion-restatement": 0,
"expansion-alternative": 0,
"expansion-list": 0
},
"semantics": {
"sentence-type": "string",
"response-type": "string",
"response-grain": "string",
"event-tense": "string",
"semantic-parse": "string"
},
"top-intent": {
"name": "string",
"confidence": 0
},
"all-intents": [
{
"name": "string",
"confidence": 0
}
],
"fragment": [
{
"expansion": "string"
}
],
"modifiers": [
"string"
],
"entities": [
{
"name": "string",
"modifier": "string",
"value": "string",
"confidence": 0
}
],
"triniti-state-context": "string",
"response": {
"message": "string",
"confidence": 0
},
"user-options": [
{
"label": "string",
"value": "string"
}
],
"similar": [
{
"id": "string",
"query": "string",
"answer": "string",
"confidence": 0
}
],
"debug": {
"faq-subtopic": "string",
"faq-subtopic-confidence": 0,
"faq-topic": "string",
"faq-topic-confidence": 0,
"faq-products": "string",
"faq-candidates": "string"
}
}
]
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | OK | Response Object |
400 | Bad Request | Bad Request | None |
401 | Unauthorized | Unauthorized | None |
404 | Not Found | Not Found | None |
Schemas
RequestObject
{
"input": "I want to send to Amol",
"previous-inputs": [
"I want to transfer 50 rs"
],
"prompt": "who do you want to transfer to?",
"current-intent": "txn-moneymovement",
"expected-entities": [
"banking.payee_name",
"sys.amount",
"banking.from_account"
],
"triniti-state-context": "",
"client-state-context": {
"user": "a",
"txn": 124345
},
"options": [
"similar",
"fragment",
"compression",
"debug",
"semantics",
"discourse",
"expansion"
]
}
Properties
Name |
Type |
Required |
Restrictions |
Description |
---|---|---|---|---|
input | string | true | none | Input query string in natural language as specified by the user |
previous-inputs | string | false | none | Previous input stringd in the same session. |
prompt | string | false | none | The query that was posted to the user before he queried |
current-intent | string | false | none | The current intent of the transaction. if any |
expected-entities | string | false | none | none |
triniti-state-context | string | true | none | none |
client-state-context | string | true | none | Serialized string which will be returned back after processing |
options | string | false | none | none |
ResponseObject
{
"version": "string",
"client-state-context": "string",
"query-processor": {
"input": "string",
"corrected": "string",
"normalised": "string",
"punctuated": "string",
"compressed": "string",
"cleaned": "string"
},
"output": [
{
"query": "string",
"expanded": "string",
"expansion-confidence": 0,
"adversity": 0,
"emotion": "string",
"emotion-score": 0,
"subject-of-emotion": "string",
"intention": {
"confirmation": true,
"cancellation": true,
"negation": true
},
"product-actions": {
"products": "string",
"actions": "string"
},
"semantic-roles": {
"general-purpose": [
"string"
],
"cause": [
"string"
],
"direction": [
"string"
],
"discourse-marker": [
"string"
],
"extent": [
"string"
],
"location": [
"string"
],
"manner": [
"string"
],
"modal-verb": [
"string"
],
"negation-marker": "string",
"purpose": [
"string"
],
"predication": [
"string"
],
"reciprocal": [
"string"
],
"temporal": [
"string"
]
},
"context-changed": true,
"discourse-relationship": {
"temporal-asynchronous": 0,
"temporal-synchronous": 0,
"contingency-cause": 0,
"contingency-pragmatic-cause": 0,
"comparison-contrast": 0,
"comparison-concession": 0,
"expansion-conjunction": 0,
"expansion-instantiation": 0,
"expansion-restatement": 0,
"expansion-alternative": 0,
"expansion-list": 0
},
"semantics": {
"sentence-type": "string",
"response-type": "string",
"response-grain": "string",
"event-tense": "string",
"semantic-parse": "string"
},
"top-intent": {
"name": "string",
"confidence": 0
},
"all-intents": [
{
"name": "string",
"confidence": 0
}
],
"fragment": [
{
"expansion": "string"
}
],
"modifiers": [
"string"
],
"entities": [
{
"name": "string",
"modifier": "string",
"value": "string",
"confidence": 0
}
],
"triniti-state-context": "string",
"response": {
"message": "string",
"confidence": 0
},
"user-options": [
{
"label": "string",
"value": "string"
}
],
"similar": [
{
"id": "string",
"query": "string",
"answer": "string",
"confidence": 0
}
],
"debug": {
"faq-subtopic": "string",
"faq-subtopic-confidence": 0,
"faq-topic": "string",
"faq-topic-confidence": 0,
"faq-products": "string",
"faq-candidates": "string"
}
}
]
}
ResponseObject
Properties
Name |
Type |
Required |
Restrictions |
Description |
---|---|---|---|---|
version | string | false | none | This provides the Triniti Version that is processing this request. Triniti upgrades within a major release 2.X.X are backward compatible for response structure. |
client-state-context | string | false | none | This simply returns the Client-State-Context passed in the process request parameters. This is usually used when calling application does not want to maintain state or have implemented someone sort of call back. |
query-processor | Query Processor | false | none | Output of query processor engine |
output | [Output] | false | none | Analysis of the input query split based on sentence. |
QueryProcessor
{
"input": "string",
"corrected": "string",
"normalised": "string",
"punctuated": "string",
"compressed": "string",
"cleaned": "string"
}
Properties
Name |
Type |
Required |
Restrictions |
Description |
---|---|---|---|---|
input | string | false | none | This is the input provided in the query parameters. Returned for purposes for reference and for use in stateless implementations |
corrected | string | false | none | This is the intermediate output after spelling correction and acronym expansion. |
normalised | string | false | none | This is the final output used for processing further. After performing Date and Number processing into standard formats. |
punctuated | string | false | none | The normalised input is punctuated to identify multiple sentences and for removal of noise by means of compression |
compressed | string | false | none | The punctuated input is compressed to remove all informative parts. |
cleaned | string | false | none | Not Implemented |
Output
{
"query": "string",
"expanded": "string",
"expansion-confidence": 0,
"adversity": 0,
"emotion": "string",
"emotion-score": 0,
"subject-of-emotion": "string",
"intention": {
"confirmation": true,
"cancellation": true,
"negation": true
},
"product-actions": {
"products": "string",
"actions": "string"
},
"semantic-roles": {
"general-purpose": [
"string"
],
"cause": [
"string"
],
"direction": [
"string"
],
"discourse-marker": [
"string"
],
"extent": [
"string"
],
"location": [
"string"
],
"manner": [
"string"
],
"modal-verb": [
"string"
],
"negation-marker": "string",
"purpose": [
"string"
],
"predication": [
"string"
],
"reciprocal": [
"string"
],
"temporal": [
"string"
]
},
"context-changed": true,
"discourse-relationship": {
"temporal-asynchronous": 0,
"temporal-synchronous": 0,
"contingency-cause": 0,
"contingency-pragmatic-cause": 0,
"comparison-contrast": 0,
"comparison-concession": 0,
"expansion-conjunction": 0,
"expansion-instantiation": 0,
"expansion-restatement": 0,
"expansion-alternative": 0,
"expansion-list": 0
},
"semantics": {
"sentence-type": "string",
"response-type": "string",
"response-grain": "string",
"event-tense": "string",
"semantic-parse": "string"
},
"top-intent": {
"name": "string",
"confidence": 0
},
"all-intents": [
{
"name": "string",
"confidence": 0
}
],
"fragment": [
{
"expansion": "string"
}
],
"modifiers": [
"string"
],
"entities": [
{
"name": "string",
"modifier": "string",
"value": "string",
"confidence": 0
}
],
"triniti-state-context": "string",
"response": {
"message": "string",
"confidence": 0
},
"user-options": [
{
"label": "string",
"value": "string"
}
],
"similar": [
{
"id": "string",
"query": "string",
"answer": "string",
"confidence": 0
}
],
"debug": {
"faq-subtopic": "string",
"faq-subtopic-confidence": 0,
"faq-topic": "string",
"faq-topic-confidence": 0,
"faq-products": "string",
"faq-candidates": "string"
}
}
Properties
Name |
Type |
Required |
Restrictions |
Description |
---|---|---|---|---|
query | string | false | none | Queries section will have upto 2 queries in case user provides a compound sentence. This “Query” show the first/second query. |
expanded | string | false | none | This is the contextually expanded query that is used for further processing. |
expansion-confidence | integer | false | none | Not Implemented |
adversity | integer | false | none | This returns the probability of the query being invalid or out of domain that the classifier has been trained for. Anything above 0.5 is to be considered as an adversarial input. |
emotion | string | false | none | This returns if the emotion of the input is “positive” or “Negative” |
emotion-score | integer | false | none | This return the emotion score on scale of 0.0 - 1.0. 0.0 being extremely negative and 1.0 being extremely positive |
subject-of-emotion | string | false | none | This return the subject of emotion if available based on users input. This is typically the noun phrases such as “card”, “service” etc. |
intention | Intention | false | none | List of intentions |
product-actions | Product Actions | false | none | List of products and actions |
semantic-roles | Semantic Roles | false | none | List of semantic roles |
context-changed | boolean | false | none | Return True if the current input from the user is not in context of the conversation |
discourse-relationship | Discourse Relationship | false | none | This return the top 3 probable relationships between the users previous input and the current one. |
semantics | Semantics | false | none | none |
top-intent | Intent | false | none | This is the Top Intent that the classifier has identified. It has “name” of the intent and the “confidence” |
all-intents | [Intent] | false | none | This is a collection of upto 3 intents which were returned by the classifier. If available. |
fragment | [Fragment] | false | none | List of fragments |
modifiers | string | false | none | List of Modifier String that were found in users utterance |
entities | [Entities] | false | none | List of entities |
triniti-state-context | string | false | none | This is returned by triniti at times to remember the state of the conversation. This value must be passed back on the subsequent call of triniti for that user session. |
response | Response | false | none | none |
user-options | [User Options] | false | none | List of user options |
similar | [Similar] | false | none | none |
debug | Debug | false | none | This contains debug information, that can communicate errors, exceptions and other information that can be useful to debug and behaviour from triniti. |
Intention
{
"confirmation": true,
"cancellation": true,
"negation": true
}
Properties
Name |
Type |
Required |
Restrictions |
Description |
---|---|---|---|---|
confirmation | boolean | false | none | Return True if user provides an input that denotes confirmation of the bots confirmation. |
cancellation | boolean | false | none | Returns True if user expresses his wish to abort the current conversation |
negation | boolean | false | none | Returns True if user negates his input. Such as “the amount is not 400” |
ProductActions
{
"products": "string",
"actions": "string"
}
Properties
Name |
Type |
Required |
Restrictions |
Description |
---|---|---|---|---|
products | string | false | none | List of Product Strings that were mentioned in the users input |
actions | string | false | none | List of Action Verbs mentioned in the users input. |
SemanticRoles
{
"general-purpose": [
"string"
],
"cause": [
"string"
],
"direction": [
"string"
],
"discourse-marker": [
"string"
],
"extent": [
"string"
],
"location": [
"string"
],
"manner": [
"string"
],
"modal-verb": [
"string"
],
"negation-marker": "string",
"purpose": [
"string"
],
"predication": [
"string"
],
"reciprocal": [
"string"
],
"temporal": [
"string"
]
}
Returns list of Semantic Roles applicable in the given input and the phrases performing that role.
Properties
Name |
Type |
Required |
Restrictions |
Description |
---|---|---|---|---|
general-purpose | string | false | none | none |
cause | string | false | none | none |
direction | string | false | none | none |
discourse-marker | string | false | none | none |
extent | string | false | none | none |
location | string | false | none | none |
manner | string | false | none | none |
modal-verb | string | false | none | none |
negation-marker | string | false | none | none |
purpose | string | false | none | none |
predication | string | false | none | none |
reciprocal | string | false | none | none |
temporal | string | false | none | none |
DiscourseRelationship
{
"temporal-asynchronous": 0,
"temporal-synchronous": 0,
"contingency-cause": 0,
"contingency-pragmatic-cause": 0,
"comparison-contrast": 0,
"comparison-concession": 0,
"expansion-conjunction": 0,
"expansion-instantiation": 0,
"expansion-restatement": 0,
"expansion-alternative": 0,
"expansion-list": 0
}
This return the top 3 probable relationships between the users previous input and the current one.
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
temporal-asynchronous | integer | false | none | none |
temporal-synchronous | integer | false | none | none |
contingency-cause | integer | false | none | none |
contingency-pragmatic-cause | integer | false | none | none |
comparison-contrast | integer | false | none | none |
comparison-concession | integer | false | none | none |
expansion-conjunction | integer | false | none | none |
expansion-instantiation | integer | false | none | none |
expansion-restatement | integer | false | none | none |
expansion-alternative | integer | false | none | none |
expansion-list | integer | false | none | none |
Semantics
{
"sentence-type": "string",
"response-type": "string",
"response-grain": "string",
"event-tense": "string",
"semantic-parse": "string"
}
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
sentence-type | string | false | none | Returns “information” for inputs that are informative in nature. “instruction” for queries, transactions. This may be ignored if the input is smalltalk. |
response-type | string | false | none | none |
response-grain | string | false | none | none |
event-tense | string | false | none | Returns “past” or “present” denoting the tense of the user input |
semantic-parse | string | false | none | none |
Intent
{
"name": "string",
"confidence": 0
}
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
name | string | false | none | none |
confidence | integer | false | none | none |
Fragment
{
"expansion": "string"
}
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
expansion | string | false | none | Provides upto 3 expansion options to make the users input complete and classifiable. This can be presented to the user if needed to let them make the choice on how their input should be interpreted. |
Entities
{
"name": "string",
"modifier": "string",
"value": "string",
"confidence": 0
}
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
name | string | false | none | Name of the Entity |
modifier | string | false | none | Modifier Attached to the entity “to”, “from” |
value | string | false | none | Value of the Entity that is extracted |
confidence | integer | false | none | Confidence Level on a scale of 0-1 |
Response
{
"message": "string",
"confidence": 0
}
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
message | string | false | none | none |
confidence | integer | false | none | none |
UserOptions
{
"label": "string",
"value": "string"
}
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
label | string | false | none | Label of the user options to be presented to the user. |
value | string | false | none | Value to be sent back to triniti if the user selects that option. |
Similar
{
"id": "string",
"query": "string",
"answer": "string",
"confidence": 0
}
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
id | string | false | none | ID of similar question as what the user asked |
query | string | false | none | The question that is similar |
answer | string | false | none | Answer to be shown if user selects this question. |
confidence | integer | false | none | Score between 0 - 1.0 denoting the similarity of the question user asked and this one. |
Debug
{
"faq-subtopic": "string",
"faq-subtopic-confidence": 0,
"faq-topic": "string",
"faq-topic-confidence": 0,
"faq-products": "string",
"faq-candidates": "string"
}
This contains debug information, that can communicate errors, exceptions and other information that can be useful to debug and behaviour from triniti.
Properties
Name | Type | Required | Restrictions | Description |
---|---|---|---|---|
faq-subtopic | string | false | none | none |
faq-subtopic-confidence | integer | false | none | none |
faq-topic | string | false | none | none |
faq-topic-confidence | integer | false | none | none |
faq-products | string | false | none | none |
faq-candidates | string | false | none | none |