Introduction

Besides the community edition, SAP Conversational AI also offers the enterprise edition that enables the customers to have all their chatbots and data securely isolated in their own tenant within the SAP Business Technology Platform. This means that each tenant specific URL is unique. However, the URL for the community edition is same for all community users.

Edition	URL Prefix
Enterprise	`https://TENANT_DOMAIN.sapcai.<region>.hana.ondemand.com/public/api`
Community	`https://api.cai.tools.sap`

TENANT_DOMAIN can be obtained by checking with your tenant admin or clicking on Go to Application hyperlink in SAP Conversational AI service tile.

Endpoints

The whole API is versioned, thus all endpoints have to be prefixed with the version number.

Responses

Renders a collection

{
  "results": [
    {
      "id": 1,
      "name": "bot-1"
    },
    {
      "id": 2,
      "name": "bot-2"
    }
  ],
  "message": "Bots rendered with success"
}

Renders a resource

{
  "results": {
    "id": 1,
    "name": "Bot1"
  },
  "message": "Bot rendered with success"
}

Renders an error

{
  "results": null,
  "message": "Request is invalid"
}

On the right you can see examples of responses returned by the API.

Format

All responses have the same format, containing two keys: results and message.

In results, we provide the answer of your request.

In message, we provide information about the response (See Status codes).

When requesting a collection or a resource, the results key will respectively contain an array of resources or a resource.

Request	Variable	Resource	Type
Collection	`results`	Found	Array: `[{}, ...]`
	`results`	Empty	Empty array: `[]`
	`message`		`String`
Model	`results`	Found	Object: `{"id":1, ...}`
	`results`	Empty	`null`
	`message`		`String`

Status codes

Except websocket, every request will have one of these status codes:

Code	Name	Response message	Description
200	`Success`	`Resource rendered with success`	Returned when resource is successfully rendered
200	`Success`	`Resource empty`	Returned when collection is successfully rendered but empty
200	`Success`	`Resource deleted with success`	Returned when resource is successfully deleted
201	`Created`	`Resource created with success`	Returned when resource is successfully created
206	`Partial Content`	`Partial resource rendered with success`	Returned when resource is paginated, or partial
400	`Bad Request`	`Request is invalid`	Returned if a request parameter is invalid
401	`Unauthorized`	`Request can not be processed without authentication`	Returned if you are not authenticated
403	`Forbidden`	`Request can not be processed with your role`	Returned if you do no have sufficient permissions with your role
404	`Not found`	`Resource not found`	Returned if request or resource is not found
415	`Unsupported Media Type`	`Request media type not supported`	Returned if the media type you provided in your request is not supported
500	`Internal Server Error`	`Internal server error`	Returned if a server error occured
503	`External Service Unavalaible`	`Service unavailable`	Returned if an external service we use is unavailable
504	`Timeout`	`Service timeout`	Returned if a service timeout

In cases of 2xx status codes, Resource is replaced by the resource name (e.g: Bots rendered with success).

Authentication

Your can access to SAP Conversational AI API with your bots’ tokens. Go in the settings of your bot in the tokens section.

Depending on which token you choose, you are allowed to make different requests.

With your request token, you can make requests in the RUNTIME API, to analyse text or start a conversation. When you create a new bot, by default, your bot has only one main version v1 and is assigned to the DEVELOPMENT environment. You will have one request token for each version and for each environment of your bot.

With your developer token, you can make requests on every endpoint our API provides.

All your requests must contain a header called Authorization, with a value of this form: Token DEVELOPER_TOKEN.

The APIs can also be called using OAuth tokens for more secure communication. OAuth token should be provided in the Authorization header as Authorization: Bearer <OAUTH_TOKEN> and developer or request token as X-Token: Token <DEVELOPER_TOKEN>

We encourage you to use request token on nothing but client side. Your developer token must be only used on server side to manage your bots.

SDKs

SAP Conversational AI provides several SDKs. They all are open-source and hosted on Github.

You can find instructions relative to each SDK in the README of the repository.

Language	Latest version	Repositories
Python	`1.0.0`	Github - Pypi
NodeJS	`1.0.0`	Github - NPM
Ruby	`1.0.0`	Github - Rubygems
PHP	`1.0.0`	Github - Packagist
Android	`1.0.0`	Github - Bintray
Swift	`1.0.0`	Github - Cocoapods

Runtime API

Analyse endpoints

/request (text)

This endpoint retrieves all metadata and intents from a sentence.

curl -H "Authorization: Token REQUEST_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"text":"Hello SAP Conversational AI", "language":"en"}' \
     -X POST "URL_PREFIX/train/v2/request"

require 'sapcai'

request = Sapcai::Request.new(REQUEST_TOKEN, 'en')
response = request.analyse_text('Hello SAP Conversational AI')

puts response.raw

import sapcai

request = sapcai.Request(REQUEST_TOKEN, 'en')
response = request.analyse_text('Hello SAP Conversational AI')

print(response.raw)

var sapcai = require('sapcai').default

var request = new sapcai.request(REQUEST_TOKEN, 'en')

request.analyseText('Hello SAP Conversational AI')
  .then(function(res) {
    console.log(res.raw)
  })

Text request works with any raw text.

POST URL_PREFIX/train/v2/request

Name	Type	Description	Constraints
`text`	`String`	This is your user input	Required, not empty, not blank, less than 512 characters
`language`	`String`	This is your user input’s language	Optional, must be a valid language isocode, if not provided a language detection will be performed

Response

{
  "results": {
    "uuid": "21ec79d8-3865-40e3-be8b-f31d040efed8",
    "source": "What'll be the weather in London next Thursday?",
    "intents": [
      {
        "slug": "weather",
        "confidence": 0.95
      }
    ],
    "act": "wh-query",
    "type": "desc:desc",
    "sentiment": "neutral",
    "entities": {
      "location": [
        {
          "formatted": "London, UK",
          "lat": 51.5073509,
          "lng": -0.1277583,
          "type": "locality",
          "place": "ChIJdd4hrwug2EcRmSrV3Vo6llI",
          "street_number": null,
          "street_name": null,
          "postal_code": null,
          "city": "London",
          "state": "England",
          "country": "gb",
          "raw": "London",
          "confidence": 0.99
        }
      ],
      "datetime": [
        {
          "formatted": "Thursday, 06 October 2016 at 09:00:00 AM",
          "iso": "2016-10-06T09:00:00Z",
          "accuracy": "day",
          "chronology": "future",
          "raw": "next Thursday",
          "confidence": 0.95
        }
      ]
    },
    "language": "en",
      "processing_language": "en",
    "version": "2.4.0",
    "timestamp": "2016-09-30T10:29:54.211866Z",
    "status": 200
  },
  "message": "Resource rendered with success"
}

We return a JSON containing your sentences and actionable data extracted from them.

Name	Type	Description
`uuid`	`String`	The universally unique id for this request
`source`	`String`	The text we processed
`intents`	`Array` of intent	The intents we found, sorted by probability
`intent.slug`	`String`	The slug of the intent which matched
`intent.confidence`	`Float`	The maching score of the intent
`act` (deprecated)	`String`	The act of the request, more info in the glossary
`type` (deprecated)	`String`	The type of the request, more info in the glossary
`sentiment`	`String`	The sentiment of the request, more info in the glossary
`entities`	`Object`	Every keys are an array of entity, more infos in the glossary
`language`	`String`	The language detected (or given) from the processed sentence, follows the ISO 639-1 standard
`processing_language`	`String`	The language used to process the sentence, follows the ISO 639-1 standard
`version`	`String`	The version of our JSON, follows the Semantic Versioning Specification
`timestamp`	`String`	The UTC timestamp at the end of our processing, follows the ISO 8601 standard
`status`	`Integer`	The status of our Natural Language processor

Errors

We will return an error (400: bad_request) if any of these cases is met:

Parameter text is missing
Parameter text is blank
Text is longer than 512 characters
Parameter language is not a valid language isocode

We will return an error (401: unauthorized) if the following case is met:

The token provided in your request is not linked to any of your bots

We will return an error (503: service_unavailable) if any of these cases is met:

Our natural language processing service is unavailable

/request (voice file)

curl -H "Authorization: Token REQUEST_TOKEN" \
     -H "Content-Type: multipart/form-data" \
     -F "voice=@hello.wav;type=audio/wav" \
     -F "language=en" \
     -X POST "URL_PREFIX/train/v2/request"

require 'sapcai'

request = Sapcai::Request.new(REQUEST_TOKEN, 'en')
response = request.analyse_file('hello.wav')

puts response.raw

import sapcai

request = sapcai.Request(REQUEST_TOKEN, 'en')
response = request.analyse_file('hello.wav')

print(response.raw)

var request = new sapcai.request('YOUR_TOKEN')

request.analyseFile('YOUR_FILE')
  .then(function(res) {
    var intent = res.intent()
    console.log(intent)
  })

Voice request works with .wav file. You should send data with multipart/form-data form (mostly automatically done).

POST URL_PREFIX/train/v2/request (multipart)

Name	Type	Description	Constraints
`voice`	`data`	This is your user voice input.	Required, not empty, no empty file, only `.wav` file. min duration: 200ms, max duration: 10s
`language`	`String`	This is your user input’s language.	Required, must be ‘en’, ‘fr’, ‘es’, ‘de’, ‘ar’, ‘ca’, ‘da’, ‘fi’, ‘hi’, ‘it’, ‘ja’, ‘ko’, ‘no’, ‘no’, ‘nl’, ‘pl’, ‘pt’, ‘ru’, ‘sv’, or ‘zh’

Response

{
  "results": {
    "uuid": "21ec79d8-3865-40e3-be8b-f31d040efed8",
    "source": "What'll be the weather in London next Thursday?",
    "intents": [
      {
        "slug": "weather",
        "confidence": 0.95
      }
    ],
    "act": "wh-query",
    "type": "desc:desc",
    "sentiment": "neutral",
    "entities": {
      "location": [
        {
          "formatted": "London, UK",
          "lat": 51.5073509,
          "lng": -0.1277583,
          "type": "locality",
          "place": "ChIJdd4hrwug2EcRmSrV3Vo6llI",
          "street_number": null,
          "street_name": null,
          "postal_code": null,
          "city": "London",
          "state": "England",
          "country": "gb",
          "raw": "London",
          "confidence": 0.99
        }
      ],
      "datetime": [
        {
          "formatted": "Thursday, 06 October 2016 at 09:00:00 AM",
          "iso": "2016-10-06T09:00:00Z",
          "accuracy": "day",
          "chronology": "future",
          "raw": "next Thursday",
          "confidence": 0.95
        }
      ]
    },
    "language": "en",
    "processing_language": "en",
    "version": "2.4.0",
    "timestamp": "2016-09-30T10:29:54.211866Z",
    "status": 200
  },
  "message": "Resource rendered with success"
}

We return a JSON containing your sentences and actionable data extracted from them.

Name	Type	Description
`uuid`	`String`	The universally unique id for this request
`source`	`String`	The text we processed
`intents`	`Array` of intent	The intents we found, sorted by probability
`intent.slug`	`String`	The slug of the intent which matched
`intent.confidence`	`Float`	The maching score of the intent
`act`	`String`	The act of the request, more info in the glossary
`type`	`String`	The type of the request, more info in the glossary
`sentiment`	`String`	The sentiment of the request, more info in the glossary
`entities`	`Object`	Every keys are an array of entity, more infos in the glossary
`language`	`String`	The language detected (or given) from the processed sentence, follows the ISO 639-1 standard
`processing_language`	`String`	The language used to process the sentence, follows the ISO 639-1 standard
`version`	`String`	The version of our JSON, follows the Semantic Versioning Specification
`timestamp`	`String`	The UTC timestamp at the end of our processing, follows the ISO 8601 standard
`status`	`Integer`	The status of our Natural Language processor

Errors

We will return an error (400: bad_request) if any of these cases is met:

Parameter voice is missing
Voice file is empty
Voice file is shorter than 200 milliseconds
Voice file is longer than 10 seconds
Voice file does not contains detectable speech
Voice speech is not recognizable
Parameter language is missing
Parameter language is empty
Parameter language is not a valid language isocode or is not one handled by our speech recognition service

We will return an error (415: unsupported_media_type) if any of these cases is met:

Parameter voice is not a file
Voice file is not a valid audio/wav file

We will return an error (401: unauthorized) if the following case is met:

The token provided in your request is not linked to any of your bots

We will return an error (503: service_unavailable) if any of these cases is met:

Our speech regonition service is unavailable
Our natural language processing service is unavailable

Dialog endpoints

/dialog (text)

This endpoint retrieve all metadata, intents and replies from a sentence

curl -H "Authorization: Token REQUEST_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"message": {"content":"Hello SAP Conversational AI","type":"text"}, "conversation_id": "CONVERSATION_ID"}' \
     -X POST "URL_PREFIX/build/v1/dialog"

require 'json'
require 'httparty'

result = HTTParty.post('URL_PREFIX/build/v1/dialog',
  body: { message: { content: 'Hello SAP Conversational AI', type: 'text' }, conversation_id: 'CONVERSATION_ID' }.to_json,
  headers: {
    'Content-Type' => 'application/json',
    'Authorization' => 'Token REQUEST_TOKEN'

  }
)

puts JSON.parse(result.body)

import requests

response = requests.post('URL_PREFIX/build/v1/dialog',
                         json={'message': {'content': 'Hello SAP Conversational AI',
                                           'type': 'text'}, 'conversation_id': 'CONVERSATION_ID'},
                         headers={'Authorization': 'Token REQUEST_TOKEN',
                                  'Content-type': 'application/json'}
                         )

print(response.text)

const request = require("superagent");

request
  .post("URL_PREFIX/build/v1/dialog")
  .send({ message: { content:"Hello SAP Conversational AI", type:"text" }, conversation_id: "CONVERSATION_ID"})
  .set("Authorization", "Token REQUEST_TOKEN")
  .set("Content-type", "application/json")
  .end((err, res) => console.log(res.text));

POST URL_PREFIX/build/v1/dialog

Name	Type	Description	Constraints
`message`	`Hash`	{ type: ‘text’, content: ‘YOUR_TEXT’}	Required, not empty, not blank, less than 512 characters
`conversation_id`	`String`	A unique id for a conversation	Required, not empty, not blank
`language`	`String`	This is your user input’s language.	Optional, must be a valid language isocode, if not provided a language detection will be performed
`memory`	`JSON`	{ your_key: your_value, …}	Optional, must be a valid JSON

Conversation Id

Each time you want to start a new conversation, make the API call with a new conversation_id. It will automatically create a new conversation. If you use a messaging channel, it generally already provides you unique conversation ids.

Memory

Each time you want to start a conversation and fill your bot memory with elements in the same time, add the memory field in your API call. Any informations that can be usefull to start a new dialog can be stored in the memory, for example: * if you want to be able to say “Hello {{memory.name}}” at the beginning of a conversation ;) * if you have a webchat in your website, and want to know where the user is when he start the conversation * if you want to populate the memory with users informations needed to provide the best user experience..

Response

{
    "messages": [
        {
            "type": "text",
            "content": "Hello :-)"
        }
    ],
    "conversation": {
        "id": "CONVERSATION_ID",
        "language": "en",
        "memory": {},
        "skill": "default",
        "skill_occurences": 1
    },
    "nlp": {
        "uuid": "b96bc782-6aba-4fac-aeaa-2326936b08bf",
        "source": "Hello SAP Conversational AI",
        "intents": [
            {
                "slug": "greetings",
                "confidence": 0.99
            }
        ],
        "act": "assert",
        "type": null,
        "sentiment": "neutral",
        "entities": {},
        "language": "en",
        "processing_language": "en",
        "version": "2.10.1",
        "timestamp": "2017-10-19T13:24:12.984856+00:00",
        "status": 200
    }
}

We return a JSON containing three parts: nlp, messages and conversation.

The nlp section contains actionable data extracted from the input.

Name	Type	Description
`uuid`	`String`	The universally unique id for this request
`source`	`String`	The text we processed
`intents`	`Array` of intent	The intents we found, sorted by probability
`intent.slug`	`String`	The slug of the intent which matched
`intent.confidence`	`Float`	The maching score of the intent
`act` (deprecated)	`String`	The act of the request, more info in the glossary
`type` (deprecated)	`String`	The type of the request, more info in the glossary
`sentiment`	`String`	The sentiment of the request, more info in the glossary
`entities`	`Object`	Every keys are an array of entity, more infos in the glossary
`language`	`String`	The language detected (or given) from the processed sentence, follows the ISO 639-1 standard
`processing_language`	`String`	The language used to process the sentence, follows the ISO 639-1 standard
`version`	`String`	The version of our JSON, follows the Semantic Versioning Specification
`timestamp`	`String`	The UTC timestamp at the end of our processing, follows the ISO 8601 standard
`status`	`Integer`	The status of our Natural Language processor

The messages section contains the replies you can send back to the user given its input.

Name	Type	Description	Constraints
`messages`	`Array` of `Message`	Check the Message format here

The conversation section contains information about the current conversation.

Name	Type	Description
`id`	`String`	The id of the current conversation
`language`	`String`	The language of the current conversation
`memory`	`Hash`	The memory of your bot for the current conversation
`skill`	`String`	The slug of the current skill
`skill_occurrences`	`Integer`	The number of consecutive occurences for the current skill

Errors

We will return an error (400: bad_request) if any of these cases is met:

Parameter message is missing
Parameter message.content is blank
Message.content is longer than 512 characters
Parameter language is not a valid language isocode

We will return an error (401: unauthorized) if the following case is met:

The token provided in your request is not linked to any of your bots

We will return an error (503: service_unavailable) if any of these cases is met:

Our natural language processing service is unavailable

BOT API

/bots

{
  "id": "1",
  "name": "My Bot",
  "slug": "my-bot",
  "description": "My first bot",
  "private_data": true,
  "public": true,
  "is_privatisable": 0,
  "children_count": 0,
  "parent": {},
  "versions_count": 3,
  "is_versioning_enabled": true,
  "developer_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

This endpoint manages bots.

Bot model

Variable	Type	Description	Constraints
`id`	`Integer`	An unique bot id
`name`	`String`	The bot name
`slug`	`String`	The bot slug
`description`	`String`	The bot description
`private_data`	`Boolean option`	Does the bot have private data?
`public`	`Boolean`	Is the bot public?
`is_privatisable`	`Boolean`	Can the bot be privatized?
`children_count`	`Integer`	The number of bots that have this bot as parent
`parent`	`Bot`	The user and the bot from which this bot has been forked
`version_count`	`Integer`	The number of versions of this bot
`is_versioning_enabled`	`Boolean`	Is the versioning system enabled for this bot?
`developer_token`	`String`	A 32-character unique token	Only for your own bot

Showing a bot

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -X GET "URL_PREFIX/core/v1/users/$USER_SLUG/bots/$BOT_SLUG"

require 'json'
require 'httparty'

result = HTTParty.get("URL_PREFIX/core/v1/users/$USER_SLUG/bots/$BOT_SLUG",
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.get('URL_PREFIX/core/v1/users/$USER_SLUG/bots/$BOT_SLUG',
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

request
  .get(`URL_PREFIX/core/v1/users/${USER_SLUG}/bots/${BOT_SLUG}`)
  .send()
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end((err, res) => console.log(res.text));

GET URL_PREFIX/core/v1/users/${USER_SLUG}/bots/${BOT_SLUG}

This call returns a bot model in results variable.

Updating a bot

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"name":NAME, "description":DESCRIPTION}' \
     -X PUT "URL_PREFIX/core/v1/users/$USER_SLUG/bots/$BOT_SLUG"

require 'json'
require 'httparty'

result = HTTParty.put("URL_PREFIX/core/v1/users/$USER_SLUG/bots/$BOT_SLUG",
  body: { name: NAME, description: DESCRIPTION },
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.put('URL_PREFIX/core/v1/users/$USER_SLUG/bots/$BOT_SLUG',
  json={'name': NAME, 'description': DESCRIPTION},
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

request
  .put(`URL_PREFIX/core/v1/users/${USER_SLUG}/bots/${BOT_SLUG}`)
  .send({
    name: NAME,
    description: DESCRIPTION
  })
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end((err, res) => console.log(res.text));

PUT URL_PREFIX/core/v1/users/${USER_SLUG}/bots/${BOT_SLUG}

Parameters	Type	Description	Constraints
`name`	`String`	The bot name	Not blank
`description`	`String`	The bot description
`public`	`Boolean`	Whether the bot is public or not

This call returns a bot model in results variable.

NLP API

/datasets

{
  "id": 1,
  "slug": "v1",
  "strictness": 65,
  "intents_count": 0,
  "gazettes_count": 0,
  "logs_count": 0,
  "manual_training": false,
  "big_bot": false,
  "intents": [],
  "actions": [],
  "gazettes": [],
  "language": {}
}

This endpoint manages datasets.

Dataset model

Variable	Type	Description
`id`	`Integer`	A unique dataset ID
`slug`	`String`	The dataset slug
`strictness`	`Integer`	The dataset strictness
`intents_count`	`Integer`	The number of intents
`gazettes_count`	`Integer`	The number of gazettes
`logs_count`	`Integer`	The number of logs
`manual_training`	`Integer`	Is the dataset manually trained?
`big_bot`	`Integer`	Is the dataset big?
`intents`	`Array` of `Intent`	The dataset light intents
`actions`	`Array` of `Action`	The dataset light actions
`gazettes`	`Array` of `Gazette`	The dataset light gazettes
`language`	`Language`	The dataset primary language

Showing a dataset

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -X GET "URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset"

require 'json'
require 'httparty'

result = HTTParty.get("URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset",
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.get('URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset',
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

request
  .get(`URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset`)
  .send()
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end((err, res) => console.log(res.text));

GET URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset

This call returns a dataset model in results variable.

If you’ve not activated versioning of your bot, your $VERSION_SLUG is v1.

Updating a dataset

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"strictness":STRICTNESS}' \
     -X PUT "https://URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset"

require 'json'
require 'httparty'

result = HTTParty.put("URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset",
  body: { strictness: STRICTNESS },
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.put('URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset',
  json={'strictness': STRICTNESS},
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

request
  .put(`URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset`)
  .send({
    strictness: STRICTNESS
  })
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end((err, res) => console.log(res.text));

PUT URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset

Parameters	Type	Description	Constraints
`strictness`	`Integer`	The dataset strictness	Only integer, greater than or equal to 0, less than or equal to 100, default: 0
`language`	`Language`	The dataset language	A valid language, with `slug` accessible

This call returns a dataset model in results variable.

If you’ve not activated versioning of your bot, your $VERSION_SLUG is v1.

Indexing a dataset’s entities

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -X GET "URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities"

require 'json'
require 'httparty'

result = HTTParty.get("URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities",
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.get('URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities',
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

request
  .get(`URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities`)
  .send()
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end((err, res) => console.log(res.text));

GET URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities

This call returns an array of entity model in results variable.

Parameter	Type	Description	Constraints
`page`	`Integer`	The current page	Optional, superior to 0
`per_page`	`Integer`	The number of items per page	Optional, superior to 0

/train

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -H "Content-Type: application/json" \
     -X POST "https://URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/train"

require 'json'
require 'httparty'

result = HTTParty.post("URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/train",
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.post('URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/train',
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

request
  .post(`URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/train`)
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end((err, res) => console.log(res.text));

POST URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/train

This call returns a dataset model in results variable.

This endpoint manages the training of your bot.

/bulk_creations

{
  "enqued_at": "2016-09-30T10:29:54.211866Z",
  "started_at": "2016-09-30T10:30:12.211866Z",
  "status": "pending",
}

This endpoint manages bulk creations of expressions.

Bulk creation model

Variable	Type	Description
`enqueued_at`	`DateTime`	The time at which the bulk creation was scheduled
`started_at`	`DateTime`	The time at which the bulk creation was started
`status`	`String`	The bulk creation status

Indexing bulk creations

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -X GET "URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/bulk_creations"

require 'json'
require 'httparty'

result = HTTParty.get("URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/bulk_creations",
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.get('URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/bulk_creations',
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

request
  .get(`URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/bulk_creations`)
  .send()
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end((err, res) => console.log(res.text));

GET URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/bulk_creations

This call returns an array of bulk creation model in results variable.

Parameter	Type	Description	Constraints
`page`	`Integer`	The current page	Optional, superior to 0
`per_page`	`Integer`	The number of items per page	Optional, superior to 0
`filter`	`String`	A comma-separated list of language ISO codes	Optional, valid ISO code

If you’ve not activated versioning of your bot, your $VERSION_SLUG is v1.

/intents

{
  "id": 1,
  "name": "Weather",
  "slug": "weather",
  "description": "Weather intent",
  "expressions": []
}

This endpoint manages intents.

Intent model

Variable	Type	Description
`id`	`Integer`	A unique intent ID
`name`	`String`	The intent name
`slug`	`String`	The intent slug
`description`	`String`	The intent description
`expressions`	`Array` of `Expression`	The intent light expressions

Light intent model

Variable	Type	Description
`id`	`Integer`	A unique intent ID
`name`	`String`	The intent name
`slug`	`String`	The intent slug
`description`	`String`	The intent description

Indexing intents

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -X GET "URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/intents"

require 'json'
require 'httparty'

result = HTTParty.get("URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/intents",
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.get('URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/intents',
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

request
  .get(`URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/intents`)
  .send()
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end((err, res) => console.log(res.text));

GET URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/intents

This call returns an array of light intent model in results variable.

Parameter	Type	Description	Constraints
`page`	`Integer`	The current page	Optional, superior to 0
`per_page`	`Integer`	The number of items per page	Optional, superior to 0

If you’ve not activated versioning of your bot, your $VERSION_SLUG is v1.

Showing an intent

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -X GET "URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/intents/$INTENT_SLUG"

require 'json'
require 'httparty'

result = HTTParty.get("URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/intents/$INTENT_SLUG",
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.get('URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/intents/$INTENT_SLUG',
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

request
  .get(`URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/intents/$INTENT_SLUG`)
  .send()
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end((err, res) => console.log(res.text));

GET URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/intents/$INTENT_SLUG

This call returns an intent model in results variable.

If you’ve not activated versioning of your bot, your $VERSION_SLUG is v1.

Creating an intent

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"name":NAME, "description":DESCRIPTION, "expressions":[{"source":SOURCE, "language":{"isocode":ISOCODE}}, {"source":SOURCE, "language":{"isocode":ISOCODE}}]}' \
     -X POST "URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/intents"

require 'json'
require 'httparty'

result = HTTParty.post("URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/intents",
  body: { name: NAME, description: DESCRIPTION, expressions: [{ source: SOURCE, language: { isocode: ISOCODE } }, { source: SOURCE, language: { isocode: ISOCODE } }] },
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.post('URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/intents',
  json={'name': NAME, 'description': DESCRIPTION, 'expressions': [{'source': SOURCE, 'language': {'isocode': ISOCODE}}, {'source': SOURCE, 'language': {'isocode': ISOCODE}}]},
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

request
  .post(`URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/intents`)
  .send({
    name: NAME,
    description: DESCRIPTION,
    expressions: [
      { source: SOURCE, language: { isocode: ISOCODE } },
      { source: SOURCE, language: { isocode: ISOCODE } }
    ]
  })
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end((err, res) => console.log(res.text));

POST URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/intents

Parameter	Type	Description	Constraints
`name`	`String`	The intent name	Required, not blank, not empty
`description`	`String`	The intent description	Optional
`expressions`	`Array` of `Expression`	The intent expressions you want to create	Optional, valid expressions models with `source` accessible, max 10000 expressions

This call returns an intent model in results variable.

If you’ve not activated versioning of your bot, your $VERSION_SLUG is v1.

When this endpoint is called, a training session is created, which will update your NLP training.
You can follow the progress using this endpoint.

If the expressions parameter is provided when this endpoint is called, a bulk creation is created, which will process the expressions in the background.
You can follow the progress using this endpoint.

Updating an intent

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"name":NAME, "description":DESCRIPTION}' \
     -X PUT "URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/intents/$INTENT_SLUG"

require 'json'
require 'httparty'

result = HTTParty.put("URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/intents/$INTENT_SLUG",
  body: { name: NAME, description: DESCRIPTION },
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.put('URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/intents/$INTENT_SLUG',
  json={'name': NAME, 'description': DESCRIPTION},
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

request
  .put(`URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/intents/$INTENT_SLUG`)
  .send({
    name: NAME,
    description: DESCRIPTION
  })
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end((err, res) => console.log(res.text));

PUT URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/intents/$INTENT_SLUG

Parameters	Type	Description	Constraints
`name`	`String`	The intent name	Not blank
`description`	`String`	The intent description

This call returns an intent model in results variable.

If you’ve not activated versioning of your bot, your $VERSION_SLUG is v1.

Deleting an intent

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -X DELETE "URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/intents/$INTENT_SLUG"

require 'json'
require 'httparty'

result = HTTParty.delete("URL-PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/intents/$INTENT_SLUG",
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.delete('URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/intents/$INTENT_SLUG',
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

request
  .delete(`[<URL Prefix>]/train/v2/users/${USER_SLUG}/bots/${BOT_SLUG}/versions/$VERSION_SLUG/dataset/intents/${INTENT_SLUG}`)
  .send()
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end((err, res) => console.log(res.text));

DELETE URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/intents/$INTENT_SLUG

This call doesn’t return any content.

If you’ve not activated versioning of your bot, your $VERSION_SLUG is v1.

Indexing an intent’s entities

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -X GET "URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/intents/$INTENT_SLUG/entities"

require 'json'
require 'httparty'

result = HTTParty.get("URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/intents/$INTENT_SLUG/entities",
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.get('URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/intents/$INTENT_SLUG/entities',
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

request
  .get(`URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/intents/$INTENT_SLUG/entities`)
  .send()
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end((err, res) => console.log(res.text));

GET URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/intents/$INTENT_SLUG/entities

This call returns an array of entity model in results variable.

Parameter	Type	Description	Constraints
`page`	`Integer`	The current page	Optional, superior to 0
`per_page`	`Integer`	The number of items per page	Optional, superior to 0

If you’ve not activated versioning of your bot, your $VERSION_SLUG is v1.

/expressions

{
  "id": 1,
  "source": "What is the weather in Paris?",
  "tokens": [],
  "language": {}
}

This endpoint manages expressions.

Expression model

Variable	Type	Description
`id`	`Integer`	A unique expression ID
`source`	`String`	The expression source
`tokens`	`Array` of `Token`	The expression tokens
`language`	`Language`	The expression language

Light expression model

Variable	Type	Description
`id`	`Integer`	A unique expression ID
`source`	`String`	The expression source
`language`	`Language`	The expression language

Indexing expressions

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -X GET "URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/intents/$INTENT_SLUG/expressions"

require 'json'
require 'httparty'

result = HTTParty.get("URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/intents/$INTENT_SLUG/expressions",
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.get('URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/intents/$INTENT_SLUG/expressions',
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

request
  .get(`URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/intents/$INTENT_SLUG/expressions`)
  .send()
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end((err, res) => console.log(res.text));

GET URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/intents/$INTENT_SLUG/expressions

This call returns an array of light expression model in results variable.

Parameter	Type	Description	Constraints
`page`	`Integer`	The current page	Optional, superior to 0
`per_page`	`Integer`	The number of items per page	Optional, superior to 0
`filter`	`String`	A comma-separated list of language ISO codes	Optional, valid ISO code

If you’ve not activated versioning of your bot, your $VERSION_SLUG is v1.

Showing an expression

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -X GET "URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/intents/$INTENT_SLUG/expressions/$EXPRESSION_ID"

require 'json'
require 'httparty'

result = HTTParty.get("URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/intents/$INTENT_SLUG/expressions/$EXPRESSION_ID",
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.get('URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/intents/$INTENT_SLUG/expressions/$EXPRESSION_ID',
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

request
  .put(`URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/intents/$INTENT_SLUG/expressions/$EXPRESSION_ID`)
  .send()
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end((err, res) => console.log(res.text));

GET URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/intents/$INTENT_SLUG/expressions/$EXPRESSION_ID

This call returns an expression model in results variable.

If you’ve not activated versioning of your bot, your $VERSION_SLUG is v1.

Creating an expression

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"source":SOURCE, "language":{"isocode":ISOCODE}}' \
     -X POST "URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/intents/$INTENT_SLUG/expressions"

require 'json'
require 'httparty'

result = HTTParty.post("URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/intents/$INTENT_SLUG/expressions",
  body: { source: SOURCE, language: { isocode: ISOCODE } },
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.post('URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/intents/$INTENT_SLUG/expressions',
  json={'source': SOURCE, 'language': {'isocode': ISOCODE}},
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

request
  .post(`URL_PREFIX/train/v2/users/${USER_SLUG}/bots/${BOT_SLUG}/versions/$VERSION_SLUG/dataset/intents/${INTENT_SLUG}/expressions`)
  .send({
    source: SOURCE,
    language: {isocode: ISOCODE}
  })
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end((err, res) => console.log(res.text));

POST URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/intents/$INTENT_SLUG/expressions

Parameter	Type	Description	Constraints
`source`	`String`	The expression source	Required, not blank, not empty, less than or equal to 512 characters
`language`	`Language`	The expression language	Optional, valid language model with `isocode` accessible

This call returns an expression model in results variable.

If you’ve not activated versioning of your bot, your $VERSION_SLUG is v1.

Bulk creating expressions

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"expressions":[{"source":SOURCE, "language":{"isocode":ISOCODE}}, {"source":SOURCE, "language":{"isocode":ISOCODE}}]}' \
     -X POST "URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/intents/$INTENT_SLUG/expressions/bulk_create"

require 'json'
require 'httparty'

result = HTTParty.post("URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/intents/$INTENT_SLUG/expressions/bulk_create",
  body: {expressions: [{ source: SOURCE, language: { isocode: ISOCODE } }, { source: SOURCE, language: { isocode: ISOCODE } }]},
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.post('URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/intents/$INTENT_SLUG/expressions/bulk_create',
  json={'expressions': [{'source': SOURCE, 'language': {'isocode': ISOCODE}, {'source': SOURCE, 'language': {'isocode': ISOCODE}}}]},
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

request
  .post(`URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/intents/$INTENT_SLUG/expressions/bulk_create`)
  .send({
    expressions: [
      { source: SOURCE, language: { isocode: ISOCODE } },
      { source: SOURCE, language: { isocode: ISOCODE } }
      ]
  })
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end((err, res) => console.log(res.text));

POST URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/intents/$INTENT_SLUG/expressions/bulk_create

Parameter	Type	Description	Constraints
`expressions`	`Array` of `Expression`	The expressions you want to create	Required, valid expressions with `source` and `language`:`isocode` accessible, max 15 000 expressions

This call returns an empty array in results variable.

If you’ve not activated versioning of your bot, your $VERSION_SLUG is v1.

Updating an expression

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"source":SOURCE, "tokens":TOKENS}' \
     -X PUT "URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/intents/$INTENT_SLUG/expressions/$EXPRESSION_ID"

require 'json'
require 'httparty'

result = HTTParty.put("URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/intents/$INTENT_SLUG/expressions/$EXPRESSION_ID",
  body: { source: SOURCE, tokens: [TOKEN, TOKEN] },
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.put('URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/intents/$INTENT_SLUG/expressions/$EXPRESSION_ID',
  json={'source': SOURCE, 'tokens': [TOKEN, TOKEN]},
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

request
  .put(`URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/intents/$INTENT_SLUG/expressions/$EXPRESSION_ID`)
  .send({
    source: SOURCE,
    tokens: [
      TOKEN,
      TOKEN
    ],
  })
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end((err, res) => console.log(res.text));

PUT URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/intents/$INTENT_SLUG/expressions/$EXPRESSION_ID

Parameter	Type	Description	Constraints
`source`	`String`	The expression source
`tokens`	`Array` of `Token`	The expression tokens you want to update	Optional, valid tokens with format: `{ "entity": null or { "id": <id>, "slug": <slug> }, "word": { "name": <word> } }`

This call returns an expression model in results variable.

If you’ve not activated versioning of your bot, your $VERSION_SLUG is v1.

Deleting an expression

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -X DELETE "URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/intents/$INTENT_SLUG/expressions/$EXPRESSION_ID"

require 'json'
require 'httparty'

result = HTTParty.delete("URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/intents/$INTENT_SLUG/expressions/$EXPRESSION_ID",
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.delete('URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/intents/$INTENT_SLUG/expressions/$EXPRESSION_ID',
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

request
  .delete(`URL-PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/intents/$INTENT_SLUG/expressions/$EXPRESSION_ID`)
  .send()
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end((err, res) => console.log(res.text));

DELETE URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/intents/$INTENT_SLUG/expressions/$EXPRESSION_ID

This call doesn’t return any content.

If you’ve not activated versioning of your bot, your $VERSION_SLUG is v1.

/tokens

{
  "id": 1,
  "space": false,
  "word": {},
  "entity": {}
}

This endpoint manages tokens.

Token model

Variable	Type	Description
`id`	`Integer`	A unique token ID
`space`	`Boolean`	Is the token followed by a space?
`word`	`Word`	The token word: { “name”: “” }
`entity`	`Entity`	The token entity

/entities

{
  "id": 1,
  "name": "Location",
  "slug": "location",
  "color": "#caff66",
  "custom": false
}

This endpoint manages entities.

Entity model

Variable	Type	Description
`id`	`Integer`	A unique entity ID
`name`	`String`	The entity name
`slug`	`String`	The entity slug
`color`	`String`	The entity color
`custom`	`Boolean`	Has the entity been created by the community?

Indexing entities

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -X GET "URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities"

require 'json'
require 'httparty'

result = HTTParty.get("URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities",
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.get('URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities',
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

request
  .get(`URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities`)
  .send()
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end((err, res) => console.log(res.text));

GET URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities

This call returns an array of entity model in results variable.

Parameter	Type	Description	Constraints
`page`	`Integer`	The current page	Optional, superior to 0
`per_page`	`Integer`	The number of items per page	Optional, superior to 0

If you’ve not activated versioning of your bot, your $VERSION_SLUG is v1.

Indexing global entities

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -X GET "URL_PREFIX/train/v2/entities"

require 'json'
require 'httparty'

result = HTTParty.get("URL_PREFIX/train/v2/entities",
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.get('URL_PREFIX/train/v2/entities',
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

request
  .get('URL_PREFIX/train/v2/entities')
  .send()
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end((err, res) => console.log(res.text));

GET URL_PREFIX/train/v2/entities

This call returns an array of entity model in results variable.

Parameter	Type	Description	Constraints
`page`	`Integer`	The current page	Optional, superior to 0
`per_page`	`Integer`	The number of items per page	Optional, superior to 0

Creating a global entity

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"name":NAME}' \
     -X POST "URL_PREFIX/train/v2/entities"

require 'json'
require 'httparty'

result = HTTParty.post("URL_PREFIX/train/v2/entities",
  body: { name: NAME },
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.post('URL_PREFIX/train/v2/entities',
  json={'name': NAME},
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

request
  .post('URL_PREFIX/train/v2/entities')
  .send({ name: NAME })
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end((err, res) => console.log(res.text));

POST URL_PREFIX/train/v2/entities

Parameter	Type	Description	Constraints
`name`	`String`	The entity name	Required, will be upcased

This call returns an entity model in results variable.

/logs

{
  "id": 1,
  "source": "What is the weather in Paris?",
  "count": 1,
  "is_archived": false,
  "intent": {},
  "language": {}
}

This endpoint manages logs.

Log model

Variable	Type	Description	Constraints
`id`	`Integer`	A unique log ID
`source`	`String`	The log source
`count`	`Integer`	The number of logs with this source
`is_archived`	`Boolean`	Whether or not the log is archived
`intent`	`Intent`	The log light intent
`tokens`	`Array` of `Token`	The log tokens
`language`	`Language`	The log language
`version_id`	`String`	The ID of the version that processed the log
`environment_id`	`String`	The ID of the environment that processed the log	Optional

Light Log model

Variable	Type	Description	Constraints
`id`	`Integer`	A unique log ID
`source`	`String`	The log source
`count`	`Integer`	The number of logs with this source
`is_archived`	`Boolean`	Whether or not the log is archived
`intent`	`Intent`	The log light intent
`language`	`Language`	The log language
`version_id`	`String`	The ID of the version that processed the log
`environment_id`	`String`	The ID of the environment that processed the log	Optional

Indexing bot logs

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -X GET "URL_PREFIX]/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/logs"

require 'json'
require 'httparty'

result = HTTParty.get("URL-PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/logs",
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.get('URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/logs',
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

request
  .get(`URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/logs`)
  .send()
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end((err, res) => console.log(res.text));

GET URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/logs

This call returns an array of light log model in results variable.

Parameter	Type	Description	Constraints
`page`	`Integer`	The current page	Optional, superior to 0
`per_page`	`Integer`	The number of items per page	Optional, superior to 0
`languages`	`String`	Comma-separated list of language ISO codes
`versions`	`String`	Comma-separated list of versions slug or ID
`environments`	`String`	Comma-separated list of environments slug or ID
`intents`	`String`	Comma-separated list of intents slug
`matched`	`String`	Show logs that matched an intent	Allowed values: `'true'`, `'false'`
`mismatched`	`String`	Show logs that didn’t match an intent	Allowed values: `'true'`, `'false'`
`archived`	`String`	Show archived logs	Allowed values: `'true'`, `'false'`

Showing a log

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -X GET "URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/logs/$LOG_ID"

require 'json'
require 'httparty'

result = HTTParty.get("URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/logs/$LOG_ID",
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.get('URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/logs/$LOG_ID',
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

request
  .get(`URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/logs/$LOG_ID`)
  .send()
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end((err, res) => console.log(res.text));

GET URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/logs/$LOG_ID

This call returns a log model in results variable.

Deleting a log

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -X DELETE "URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/logs/$LOG_ID"

require 'json'
require 'httparty'

result = HTTParty.delete("URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/logs/$LOG_ID",
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.delete('URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/logs/$LOG_ID',
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

request
  .delete(`URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/logs/$LOG_ID`)
  .send()
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end((err, res) => console.log(res.text));

DELETE URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/logs/$LOG_ID

This call doesn’t return any content.

Bulk deleting logs

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"logs":[{"source":SOURCE, "language":{"isocode":ISOCODE}}, {"source":SOURCE, "language":{"isocode":ISOCODE}}]}' \
     -X POST "URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/logs/bulk_destroy"

require 'json'
require 'httparty'

result = HTTParty.post("URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/logs/bulk_destroy",
  body: { logs: [{ source: SOURCE, language: { isocode: ISOCODE } }, { source: SOURCE, language: { isocode: ISOCODE } }] },
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.post('URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/logs/bulk_destroy',
  json={'logs': [{'source': SOURCE, 'language': {'isocode': ISOCODE}}, {'source': SOURCE, 'language': {'isocode': ISOCODE}}]},
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

request
  .post(`URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/logs/bulk_destroy`)
  .send({
    logs: [
      { source: SOURCE, language: { isocode: ISOCODE } },
      { source: SOURCE, language: { isocode: ISOCODE } }
    ]
  })
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end((err, res) => console.log(res.text));

POST URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/logs/bulk_destroy

This call doesn’t return any content.

Parameter	Type	Description	Constraints
`logs`	`Array` of `Log`	The logs you want to delete	Required, valid logs with `source` and `language`:`isocode` accessible

/gazettes

{
  "id": 1,
  "slug": "location",
  "is_open": true,
  "is_activated": false,
  "strictness": 90,
  "entity": {},
  "synonyms": []
}

This endpoint manages gazettes.

Gazette model

Variable	Type	Description	Constraints
`id`	`Integer`	A unique gazette ID
`slug`	`String`	The gazette slug
`is_open`	`Boolean`	Whether or not the gazette is an open-ended list
`is_activated`	`Boolean`	Whether or not the gazette is activated
`strictness`	`Integer`	The strictness of the synonym matching in the gazette (100 means exact matching)	Only integer, greater than or equal to 0, less than or equal to 100, default: 90
`entity`	`Entity`	The gazette entity
`synonyms`	`Array` of `Synonym`	The gazette synonyms

Light gazette model

Variable	Type	Description	Constraints
`id`	`Integer`	A unique gazette ID
`slug`	`String`	The gazette slug
`is_open`	`Boolean`	Whether or not the gazette is an open-ended list
`is_activated`	`Boolean`	Whether or not the gazette is activated
`strictness`	`Integer`	The strictness of the synonym matching in the gazette (100 means exact matching)	Only integer, greater than or equal to 0, less than or equal to 100, default: 90
`entity`	`Entity`	The gazette entity

Indexing gazettes

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -X GET "URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/gazettes"

require 'json'
require 'httparty'

result = HTTParty.get("URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/gazettes",
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.get('URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/gazettes',
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

request
  .get(`URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/gazettes`)
  .send()
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end((err, res) => console.log(res.text));

GET URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/gazettes

This call returns an array of light gazette model in results variable.

Parameter	Type	Description	Constraints
`page`	`Integer`	The current page	Optional, superior to 0
`per_page`	`Integer`	The number of items per page	Optional, superior to 0
`filter`	`String`	A comma-separated list of gazette states	Optional, valid openess (`open` or `closed`), valid states (`activated` or `deactivated`)

If you’ve not activated versioning of your bot, your $VERSION_SLUG is v1.

Showing a gazette

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -X GET "URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/gazettes/$GAZETTE_SLUG"

require 'json'
require 'httparty'

result = HTTParty.get("URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/gazettes/$GAZETTE_SLUG",
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.get('URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/gazettes/$GAZETTE_SLUG',
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

request
  .get(`URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/gazettes/$GAZETTE_SLUG`)
  .send()
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end((err, res) => console.log(res.text));

GET URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/gazettes/$GAZETTE_SLUG

This call returns a gazette model in results variable.

If you’ve not activated versioning of your bot, your $VERSION_SLUG is v1.

Creating a gazette

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"entity_id":ENTITY_SLUG, "is_activated":IS_ACTIVATED, "is_open":IS_OPEN, "strictness":STRICTNESS, "synonyms":[{"value":VALUE, "language":{"isocode":ISOCODE}},{"value":VALUE, "language":{"isocode":ISOCODE}}]}}' \
     -X POST "URL_PREFIX]/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/gazettes"

require 'json'
require 'httparty'

result = HTTParty.post("URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/gazettes",
  body: {entity_id: ENTITY_SLUG, is_activated: IS_ACTIVATED, is_open: IS_OPEN, strictness: STRICTNESS, synonyms: [{ value: VALUE, language: { isocode: ISOCODE } }, { value: VALUE, language: { isocode: ISOCODE } }] },
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.post('URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/gazettes',
  json={'entity_id': ENTITY_SLUG, 'is_activated': IS_ACTIVATED, 'is_open': IS_OPEN, 'strictness': STRICTNESS, 'synonyms': [{'value': VALUE, 'language': {'isocode': ISOCODE}}, {'value': VALUE, 'language': {'isocode': ISOCODE}}]},
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

request
  .post(`URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/gazettes`)
  .send({
    entity_id: ENTITY_SLUG,
    is_activated: IS_ACTIVATED,
    is_open: IS_OPEN,
    strictness: STRICTNESS,
    synonyms: [
      {value: VALUE, language:{isocode: ISOCODE}},
      {value: VALUE, language:{isocode: ISOCODE}}
    ]
  })
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end((err, res) => console.log(res.text));

POST URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/gazettes

Parameter	Type	Description	Constraints
`entity_id`	`String`	The ID or slug of the gazette entity
`is_open`	`Boolean`	Whether or not the gazette is an open-ended list	Optional
`is_activated`	`Boolean`	Whether or not the gazette is activated	Optional
`strictness`	`Integer`	The strictness of the synonym matching in the gazette (100 means exact matching)	Optional, only integer, greater than or equal to 0, less than or equal to 100, default: 90
`synonyms`	`Array` of `Synonym`	The gazette synonyms you want to create	Optional, valid synonyms models with `value` and `language` accessible

This call returns a gazette model in results variable.

If you’ve not activated versioning of your bot, your $VERSION_SLUG is v1.

Updating a gazette

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"entity_id":ENTITY_SLUG, "is_activated":IS_ACTIVATED, "is_open":IS_OPEN, "strictness":STRICTNESS}' \
     -X PUT "URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/gazettes/$GAZETTE_SLUG"

require 'json'
require 'httparty'

result = HTTParty.put("URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/gazettes/$GAZETTE_SLUG",
  body: {entity_id: ENTITY_SLUG, is_activated: IS_ACTIVATED, is_open: IS_OPEN, strictness: STRICTNESS},
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.put('URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/gazettes/$GAZETTE_SLUG',
  json={'entity_id': ENTITY_SLUG, 'is_activated': IS_ACTIVATED, 'is_open': IS_OPEN, 'strictness': STRICTNESS},
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

request
  .put(`URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/gazettes/$GAZETTE_SLUG`)
  .send({
    entity_id: ENTITY_SLUG,
    is_activated: IS_ACTIVATED,
    is_open: IS_OPEN,
    strictness: STRICTNESS,
  })
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end((err, res) => console.log(res.text));

PUT URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/gazettes/$GAZETTE_SLUG

Parameter	Type	Description	Constraints
`entity`	`String`	The gazette entity slug
`is_open`	`Boolean`	Whether or not the gazette is an open-ended list	Optional
`is_activated`	`Boolean`	Whether or not the gazette is activated	Optional
`strictness`	`Integer`	The strictness of the synonym matching in the gazette (100 means exact matching)	Optional, only integer, greater than or equal to 0, less than or equal to 100, default: 90

This call returns a gazette model in results variable.

If you’ve not activated versioning of your bot, your $VERSION_SLUG is v1.

Deleting a gazette

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -X DELETE "URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/gazettes/$GAZETTE_SLUG"

require 'json'
require 'httparty'

result = HTTParty.delete("URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/gazettes/$GAZETTE_SLUG",
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.delete('URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/gazettes/$GAZETTE_SLUG',
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

request
  .delete(`URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/gazettes/$GAZETTE_SLUG`)
  .send()
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end((err, res) => console.log(res.text));

DELETE URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/gazettes/$GAZETTE_SLUG

This call doesn’t return any content.

If you’ve not activated versioning of your bot, your $VERSION_SLUG is v1.

/synonyms

{
  "id": 1,
  "slug": "new-york",
  "value": "New York",
  "language": {}
}

This endpoint manages synonyms.

Synonym model

Variable	Type	Description
`id`	`Integer`	A unique synonym ID
`slug`	`String`	The synonym slug
`value`	`Boolean`	The synonym real value
`language`	`Language`	The synonym language

Indexing synonyms

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -X GET "URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/gazettes/$GAZETTE_SLUG/synonyms"

require 'json'
require 'httparty'

result = HTTParty.get("URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/gazettes/$GAZETTE_SLUG/synonyms",
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.get('URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/gazettes/$GAZETTE_SLUG/synonyms',
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

request
  .get(`URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/datasets/versions/$VERSION_SLUG/dataset/$GAZETTE_SLUG/synonyms`)
  .send()
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end((err, res) => console.log(res.text));

GET URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG}/versions/$VERSION_SLUG/dataset/gazettes/$GAZETTE_SLUG/synonyms

This call returns an array of synonym model in results variable.

Parameter	Type	Description	Constraints
`page`	`Integer`	The current page	Optional, superior to 0
`per_page`	`Integer`	The number of items per page	Optional, superior to 0

If you’ve not activated versioning of your bot, your $VERSION_SLUG is v1.

Showing a synonym

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -X GET "[<URL Prefix>]/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/gazettes/$GAZETTE_SLUG/synonyms/$SYNONYM_SLUG"

require 'json'
require 'httparty'

result = HTTParty.get("[<URL Prefix>]/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/gazettes/$GAZETTE_SLUG/synonyms/$SYNONYM_SLUG",
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.get('[<URL Prefix>]/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/gazettes/$GAZETTE_SLUG/synonyms/$SYNONYM_SLUG',
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

request
  .get(`[<URL Prefix>]/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/gazettes/$GAZETTE_SLUG/synonyms/$SYNONYM_SLUG`)
  .send()
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end((err, res) => console.log(res.text));

GET [<URL Prefix>]/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/gazettes/$GAZETTE_SLUG/synonyms/$SYNONYM_SLUG

This call returns a synonym model in results variable.

If you’ve not activated versioning of your bot, your $VERSION_SLUG is v1.

Creating a synonym

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"value":VALUE, "language":{"isocode":ISOCODE}}' \
     -X POST "[<URL Prefix>]/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/gazettes/$GAZETTE_SLUG/synonyms"

require 'json'
require 'httparty'

result = HTTParty.post("[<URL Prefix>]/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/gazettes/$GAZETTE_SLUG/synonyms",
  body: {value: VALUE, language: {isocode: ISOCODE}},
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.post('[<URL Prefix>]/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/gazettes/$GAZETTE_SLUG/synonyms',
  json={'value': VALUE, 'language': {'isocode': ISOCODE}},
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

request
  .post(`[<URL Prefix>]/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/gazettes/$GAZETTE_SLUG/synonyms`)
  .send({
    value: VALUE,
    language: { isocode: ISOCODE }
  })
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end((err, res) => console.log(res.text));

POST [<URL Prefix>]/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/gazettes/$GAZETTE_SLUG/synonyms

Parameter	Type	Description	Constraints
`value`	`String`	The synonym value
`language`	`Language`	The synonym language

This call returns a synonym model in results variable.

If you’ve not activated versioning of your bot, your $VERSION_SLUG is v1.

Bulk creating synonyms

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"synonyms":[{"value":VALUE, "language":{"isocode":ISOCODE}}, {"value":VALUE, "language":{"isocode":ISOCODE}}]}' \
     -X POST "[<URL Prefix>]/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/gazettes/$GAZETTE_SLUG/synonyms/bulk_create"

require 'json'
require 'httparty'

result = HTTParty.post("[<URL Prefix>]/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/gazettes/$GAZETTE_SLUG/synonyms/bulk_create",
  body: { synonyms: [{ value: VALUE, language: { isocode: ISOCODE } }, { value: VALUE, language: { isocode: ISOCODE } }] },
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.post('[<URL Prefix>]/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/gazettes/$GAZETTE_SLUG/synonyms/bulk_create',
  json={'synonyms': [{'value': VALUE, 'language': {'isocode': ISOCODE}}, {'value': VALUE, 'language': {'isocode': ISOCODE}}]},
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

request
  .post(`[<URL Prefix>]/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/gazettes/$GAZETTE_SLUG/synonyms/bulk_create`)
  .send({
    synonyms: [
      { value: VALUE, language: { isocode: ISOCODE } },
      { value: VALUE, language: { isocode: ISOCODE } },
    ]
  })
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end((err, res) => console.log(res.text));

POST [<URL Prefix>]/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/gazettes/$GAZETTE_SLUG/synonyms/bulk_create

Parameter	Type	Description	Constraints
`synonyms`	`Array` of `Synonym`	The synonym you want to create	Required, valid synonym with `value` and `language`.`isocode` accessible

This call returns an array of synonym model in results variable.

If you’ve not activated versioning of your bot, your $VERSION_SLUG is v1.

Updating a synonym

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"value":VALUE, "language":{"isocode":ISOCODE}}' \
     -X PUT "[<URL Prefix>]/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/gazettes/$GAZETTE_SLUG/synonyms/$SYNONYM_SLUG"

require 'json'
require 'httparty'

result = HTTParty.put("[<URL Prefix>]/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/gazettes/$GAZETTE_SLUG/synonyms/$SYNONYM_SLUG",
  body: {entity_id: ENTITY_SLUG, is_activated: IS_ACTIVATED, is_open: IS_OPEN, strictness: STRICTNESS},
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.put('[<URL Prefix>]/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/gazettes/$GAZETTE_SLUG/synonyms/$SYNONYM_SLUG',
  json={value: VALUE, language: {'isocode': ISOCODE}},
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

request
  .put(`[<URL Prefix>]/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/gazettes/$GAZETTE_SLUG/synonyms/$SYNONYM_SLUG`)
  .send({
    value: VALUE,
    language: { isocode: ISOCODE }
  })
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end((err, res) => console.log(res.text));

PUT [<URL Prefix>]/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/gazettes/$GAZETTE_SLUG/synonyms/$SYNONYM_SLUG

Parameter	Type	Description	Constraints
`value`	`String`	The synonym value
`language`	`Language`	The synonym language

This call returns a synonym model in results variable.

If you’ve not activated versioning of your bot, your $VERSION_SLUG is v1.

Deleting a synonym

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -X DELETE "[<URL Prefix>]p/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/gazettes/$GAZETTE_SLUG/synonyms/$SYNONYM_SLUG"

require 'json'
require 'httparty'

result = HTTParty.delete("[<URL Prefix>]/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/gazettes/$GAZETTE_SLUG/synonyms/$SYNONYM_SLUG",
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.delete('[<URL Prefix>]/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/gazettes/$GAZETTE_SLUG/synonyms/$SYNONYM_SLUG',
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

request
  .delete(`[<URL Prefix>]/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/gazettes/$GAZETTE_SLUG/synonyms/$SYNONYM_SLUG`)
  .send()
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end((err, res) => console.log(res.text));

DELETE [<URL Prefix>]/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/gazettes/$GAZETTE_SLUG/synonyms/$SYNONYM_SLUG

This call doesn’t return any content.

If you’ve not activated versioning of your bot, your $VERSION_SLUG is v1.

/languages

{
  "id": 1,
  "name": "French",
  "slug": "french",
  "isocode": "fr"
}

This endpoint manages languages.

Language model

Variable	Type	Description
`id`	`Integer`	A unique language ID
`name`	`String`	The language name
`slug`	`String`	The language slug
`isocode`	`String`	The language ISO code as per the ISO 639-1 standard
`is_supported`	`Boolean`	Is the language fully handled by the platform (advanced level) or not (standard level)?

/pair_keys

This endpoint manages custom keys for a given entity

Models

Custom pair key

Variable	Type	Description
`id`	`String`	A unique entity ID
`slug`	`String`	The custom key slug
`default_enrichment_values`	`Array` of `Default Enrichment Value`	List of default enrichment values

Default enrichment Value

Variable	Type	Description	Constraints
`language`	`String`	Language the default enrichment belongs to
`value`	`String`	Value for the default enrichment

Index custom pair keys

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -X GET "URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/pair_keys"

require 'json'
require 'httparty'

result = HTTParty.get("URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/pair_keys",
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.get('URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/pair_keys',
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

request
  .get(`URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/pair_keys`)
  .send()
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end((err, res) => console.log(res.text));

GET URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/pair_keys

This call returns an array of custom keys in results variable.

Parameter	Type	Description	Constraints
`language`	`String`	Language ISO code	Optional

Create a custom pair key

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"slug":"KEYNAME","default_enrichments":[{"language":"ISOCODE","value":"DEFAULTVALUE"}]}' \
     -X POST "URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/pair_keys"

require 'json'
require 'httparty'

result = HTTParty.post("URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/pair_keys",
  body: {slug: KEYNAME, default_enrichments:[{ language: ISOCODE,value: DEFAULTVALUE }],
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.post('URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/pair_keys',
  json={'slug': KEYNAME, 'default_enrichments':[{'language': ISOCODE, 'value' : DEFAULTVALUE}]},
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

request
  .post(`URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/pair_keys`)
  .send({
    slug: KEYNAME,
    default_enrichments: [
      { value: DEFAULTVALUE, language: ISOCODE},
      { value: DEFAULTVALUE, language: ISOCODE }
    ]
  })
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end((err, res) => console.log(res.text));

POST URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/pair_keys

Variable	Type	Description	Constraints
`slug`	`String`	The custom key slug
`default_enrichments`	`Array` of `Default Enrichment Value`	List of default enrichment values

This call returns a custom key in results variable.

Update a custom pair key

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"default_enrichments":[{"language":"ISOCODE","value":"DEFAULTVALUE"}]}' \
     -X PUT "URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/pair_keys/$KEY_SLUG"

require 'json'
require 'httparty'

result = HTTParty.put("URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/pair_keys/$KEY_SLUG",
  body: {default_enrichments:[{ language: ISOCODE,value: DEFAULTVALUE }],
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.put('URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/pair_keys/$KEY_SLUG',
  json={'default_enrichments':[{'language': ISOCODE, 'value' : DEFAULTVALUE}]},
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

request
  .put(`URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/pair_keys/$KEY_SLUG`)
  .send({
    default_enrichments: [
      { value: DEFAULTVALUE, language: ISOCODE},
      { value: DEFAULTVALUE, language: ISOCODE }
    ]
  })
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end((err, res) => console.log(res.text));

PUT URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/pair_keys/$KEY_SLUG

Variable	Type	Description	Constraints
`default_enrichments`	`Array` of `Default Enrichment`	List of default enrichments values

This call returns a custom key in results variable.

Delete a custom pair key

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -X DElETE "URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/pair_keys/$KEY_SLUG"

require 'json'
require 'httparty'

result = HTTParty.delete("URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/pair_keys/$KEY_SLUG",
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.delete('URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/pair_keys/$KEY_SLUG',
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

request
  .delete(`URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/pair_keys/$KEY_SLUG`)
  .send()
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end((err, res) => console.log(res.text));

DELETE URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/pair_keys/$KEY_SLUG

This call doesn’t return any content.

Show a custom pair key

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -X GET "URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/pair_keys/$KEY_SLUG"

require 'json'
require 'httparty'

result = HTTParty.get("URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/pair_keys/$KEY_SLUG",
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.get('URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/pair_keys/$KEY_SLUG',
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

request
  .get(`URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/pair_keys/$KEY_SLUG`)
  .send()
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end((err, res) => console.log(res.text));

GET URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/pair_keys/$KEY_SLUG

This call returns a custom pair key in results variable.

Parameter	Type	Description	Constraints
`language`	`String`	Language ISO code	Optional

/groups

This endpoint manages enrichment groups for a given entity

Models

Enrichment group

Variable	Type	Description	Constraints
`id`	`String`	A unique entity ID
`slug`	`String`	The enrichment group slug
`language`	`String`	Language ISO code
`entity_values`	`Array` of `String`	List of entity values that are going to be enriched
`enrichment_pair_values`	`Array` of `Hash`	{enrichment_pair_key_id: `String`, value: `String`} Enrichment for the given key	value must be valid JSON

Index enrichment group

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -X GET "URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/groups"

require 'json'
require 'httparty'

result = HTTParty.get("URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/groups",
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.get('URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/groups',
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

request
  .get(`URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/groups`)
  .send()
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end((err, res) => console.log(res.text));

GET URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/groups

This call returns an array of enrichment groups in results variable.

Parameter	Type	Description	Constraints
`language`	`String`	Language ISO code	Optional
`q`	`String`	search query, to filter by entity value, enrichment value or group name	Optional

Create an enrichment group

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"slug":"GROUPNAME","entity_values":["VALUE"],"enrichment_pair_values:[{enrichment_pair_key_id:KEYID,value:"VALUE"}]"}' \
     -X POST "URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/groups"

require 'json'
require 'httparty'

result = HTTParty.post("URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/groups",
  body: {slug: GROUPNAME, entity_values:[VALUE], enrichment_pair_values:[{enrichment_pair_key_id:KEYID,value:VALUE}]},
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.post('URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/groups',
  json={'slug': GROUPNAME, 'entity_values':[VALUE], 'enrichment_pair_values:[{enrichment_pair_key_id:KEYID, value:VALUE}]'},
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

request
  .post(`URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/groups`)
  .send({
    slug: GROUPNAME,
    entity_values: [VALUE],
    enrichment_pair_values: [
      { enrichment_pair_key_id: KEYID, value: VALUE},
    ]
  })
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end((err, res) => console.log(res.text));

POST URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/groups

Variable	Type	Description	Constraints
`slug`	`String`	The enrichment group slug
`language`	`String`	Language ISO code	Optional
`entity_values`	`Array` of `String`	List of entity values that are going to be enriched
`enrichment_pair_values`	`Array` of `Hash`	{enrichment_pair_key_id: `String`, value: `String`} Enrichment for the given key	value must be valid JSON

This call returns an enrichment group in results variable.

Update an enrichment group

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"slug":"GROUPNAME","entity_values":["VALUE"],"enrichment_pair_values:[{enrichment_pair_key_id:KEYID,value:"VALUE"}]"}' \
     -X PUT "URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/groups"

require 'json'
require 'httparty'

result = HTTParty.put("URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/groups",
  body: {slug: GROUPNAME, entity_values:[VALUE], enrichment_pair_values:[{enrichment_pair_key_id:KEYID,value:VALUE}]},
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.put('URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/groups',
  json={'slug': GROUPNAME, 'entity_values':[VALUE], 'enrichment_pair_values:[{enrichment_pair_key_id:KEYID, value:VALUE}]'},
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

request
  .put(`URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/groups`)
  .send({
    slug: GROUPNAME,
    entity_values: [VALUE],
    enrichment_pair_values: [
      { enrichment_pair_key_id: KEYID, value: VALUE},
    ]
  })
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end((err, res) => console.log(res.text));

PUT URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/pair_keys/$KEY_SLUG

Variable	Type	Description	Constraints
`slug`	`String`	The enrichment group slug
`entity_values`	`Array` of `String`	List of entity values that are going to be enriched
`enrichment_pair_values`	`Array` of `Hash`	{enrichment_pair_key_id: `String`, value: `String`} Enrichment for the given key	value must be valid JSON

This call returns an enrichment group in results variable.

Delete an enrichment group

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -X DElETE "URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/groups/$ENRICHMENT_GROUP_SLUG"

require 'json'
require 'httparty'

result = HTTParty.delete("URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/groups/$ENRICHMENT_GROUP_SLUG",
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.delete('URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/groups/$ENRICHMENT_GROUP_SLUG',
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

request
  .delete(`URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/groups/$ENRICHMENT_GROUP_SLUG`)
  .send()
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end((err, res) => console.log(res.text));

DELETE URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/groups/$ENRICHMENT_GROUP_SLUG

This call doesn’t return any content.

Show an enrichment group

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -X GET "URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/groups/$ENRICHMENT_GROUP_SLUG"

require 'json'
require 'httparty'

result = HTTParty.get("URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/groups/$ENRICHMENT_GROUP_SLUG",
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.get('URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/groups/$ENRICHMENT_GROUP_SLUG',
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

request
  .get(`URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/groups/$ENRICHMENT_GROUP_SLUG`)
  .send()
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end((err, res) => console.log(res.text));

GET URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/groups/$ENRICHMENT_GROUP_SLUG

This call returns an enrichment group in results variable.

/keys

This endpoint manages custom keys for a given entity

Models

Custom key

Variable	Type	Description
`id`	`String`	A unique entity ID
`slug`	`String`	The custom key slug
`default_enrichments`	`Array` of `Default Enrichment`	List of default enrichments

Default enrichment

Variable	Type	Description	Constraints
`language`	`String`	Language the default enrichment belongs to
`value`	`String`	Value for the default enrichment

Index custom keys

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -X GET "URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/keys"

require 'json'
require 'httparty'

result = HTTParty.get("URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/keys",
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.get('URL_PREFIX]/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/keys',
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

request
  .get(`URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/keys`)
  .send()
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end((err, res) => console.log(res.text));

GET URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/keys

This call returns an array of custom keys in results variable.

Parameter	Type	Description	Constraints
`language`	`String`	Language ISO code	Optional

Create a custom key

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"slug":"KEYNAME","default_enrichments":[{"language":"ISOCODE","value":"DEFAULTVALUE"}]}' \
     -X POST "URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/keys"

require 'json'
require 'httparty'

result = HTTParty.post("URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/keys",
  body: {slug: KEYNAME, default_enrichments:[{ language: ISOCODE,value: DEFAULTVALUE }],
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.post('URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/keys',
  json={'slug': KEYNAME, 'default_enrichments':[{'language': ISOCODE, 'value' : DEFAULTVALUE}]},
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

request
  .post(`URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/keys`)
  .send({
    slug: KEYNAME,
    default_enrichments: [
      { value: DEFAULTVALUE, language: ISOCODE},
      { value: DEFAULTVALUE, language: ISOCODE }
    ]
  })
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end((err, res) => console.log(res.text));

POST URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/keys

Variable	Type	Description	Constraints
`slug`	`String`	The custom key slug
`default_enrichments`	`Array` of `Default Enrichment`	List of default enrichments

This call returns a custom key in results variable.

Update a custom key

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"default_enrichments":[{"language":"ISOCODE","value":"DEFAULTVALUE"}]}' \
     -X PUT "URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/keys/$KEY_SLUG"

require 'json'
require 'httparty'

result = HTTParty.put("URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/keys/$KEY_SLUG",
  body: {default_enrichments:[{ language: ISOCODE,value: DEFAULTVALUE }],
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.put('URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/keys/$KEY_SLUG',
  json={'default_enrichments':[{'language': ISOCODE, 'value' : DEFAULTVALUE}]},
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

request
  .put(`URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/keys/$KEY_SLUG`)
  .send({
    default_enrichments: [
      { value: DEFAULTVALUE, language: ISOCODE},
      { value: DEFAULTVALUE, language: ISOCODE }
    ]
  })
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end((err, res) => console.log(res.text));

PUT URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/keys/$KEY_SLUG

Variable	Type	Description	Constraints
`default_enrichments`	`Array` of `Default Enrichment`	List of default enrichments

This call returns a custom key in results variable.

Delete a custom key

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -X DElETE "URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/keys/$KEY_SLUG"

require 'json'
require 'httparty'

result = HTTParty.delete("URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/keys/$KEY_SLUG",
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.delete('URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/keys/$KEY_SLUG',
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

request
  .delete(`URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/keys/$KEY_SLUG`)
  .send()
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end((err, res) => console.log(res.text));

DELETE URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/keys/$KEY_SLUG

This call doesn’t return any content.

Show a custom key

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -X GET "URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/keys/$KEY_SLUG"

require 'json'
require 'httparty'

result = HTTParty.get("URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/keys/$KEY_SLUG",
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.get('URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/keys/$KEY_SLUG',
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

request
  .get(`URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/keys/$KEY_SLUG`)
  .send()
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end((err, res) => console.log(res.text));

GET URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/keys/$KEY_SLUG

This call returns a custom key in results variable.

Parameter	Type	Description	Constraints
`language`	`String`	Language ISO code	Optional

/enrichments

This endpoint manages specific enrichments for a custom key.

Specific enrichment model

Variable	Type	Description	Constraints
`id`	`String`	A unique entity ID
`language`	`String`	Language ISO code
`value`	`String`	Value returned during runtime
`entity_values`	`Array` of `String`	List of entity values	Only the first 5 are returned
`entity_values_count`	`String`	Total count of entity values

Index specific enrichments

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -X GET "URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/keys/$KEY_SLUG/enrichments"

require 'json'
require 'httparty'

result = HTTParty.get("URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/keys/$KEY_SLUG/enrichments",
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.get('URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/keys/$KEY_SLUG/enrichments',
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

request
  .get(`URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/keys/$KEY_SLUG/enrichments`)
  .send()
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end((err, res) => console.log(res.text));

GET URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/keys/$KEY_SLUG/enrichments

Parameter	Type	Description	Constraints
`language`	`String`	Language ISO code	Optional
`page`	`Integer`	Requested page (one-based)	Optional
`per_page`	`Integer`	Number of items per page	Optional

This call returns the following response in results variable.

Parameter	Type	Description	Constraints
`enrichments_count`	`integer`	Total count of specific enrichments
`enrichments`	`Array` of `Specific enrichment`	List of specific enrichments

Create a specific enrichment

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"language": "ISOCODE","value": "VALUE","entity_values": ["ENTITYVALUE1",
    "ENTITYVALUE1"]}' \
     -X POST "URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/keys/$KEY_SLUG/enrichments"

require 'json'
require 'httparty'

result = HTTParty.post("URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/keys/$KEY_SLUG/enrichments",
  body: {language: ISOCODE,value: VALUE,entity_values: [ENTITYVALUE1,
    ENTITYVALUE1]},
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.post('URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/keys/enrichments',
  json={{'language': ISOCODE,'value': VALUE,'entity_values': [ ENTITYVALUE1,
    ENTITYVALUE1]}},
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

request
  .post(`URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/keys`)
  .send({
    language: ISOCODE,
    value: VALUE,
    entity_values: [
      ENTITYVALUE1,
      ENTITYVALUE1
    ]})
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end((err, res) => console.log(res.text));

POST URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/keys/$KEY_SLUG/enrichments

Variable	Type	Description	Constraints
`language`	`String`	Language ISO code
`value`	`String`	Value returned during runtime
`entity_values`	`Array` of `String`	List of entity values	Only the first 5 are returned

This call returns a specific enrichment in results variable.

Update a specific enrichment

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"language": "ISOCODE","value": "VALUE","entity_values": ["ENTITYVALUE1",
    "ENTITYVALUE1"]}' \
     -X PUT "URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/keys/$KEY_SLUG/enrichments/$ENRICHMENT_ID"

require 'json'
require 'httparty'

result = HTTParty.put("URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/keys/$KEY_SLUG/enrichments/$ENRICHMENT_ID",
  body: {language: ISOCODE,value: VALUE,entity_values: [ENTITYVALUE1,
    ENTITYVALUE1]},
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.put('URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/keys/$KEY_SLUG/enrichments/$ENRICHMENT_ID',
  json={{'language': ISOCODE,'value': VALUE,'entity_values': [ ENTITYVALUE1,
    ENTITYVALUE1]}},
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

request
  .put(`URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/keys/$KEY_SLUG/enrichments/$ENRICHMENT_ID`)
  .send({
    language: ISOCODE,
    value: VALUE,
    entity_values: [
      ENTITYVALUE1,
      ENTITYVALUE1
    ]})
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end((err, res) => console.log(res.text));

PUT URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/keys/$KEY_SLUG/enrichments/$ENRICHMENT_ID

Variable	Type	Description	Constraints
`language`	`String`	Language ISO code
`value`	`String`	Value returned during runtime
`entity_values`	`Array` of `String`	List of entity values	Only the first 5 are returned

This call returns a specific enrichment in results variable.

Delete a specific enrichment

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -X DElETE "URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/keys/$KEY_SLUG/enrichments/$ENRICHMENT_ID"

require 'json'
require 'httparty'

result = HTTParty.delete("URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/keys/$KEY_SLUG/enrichments/$ENRICHMENT_ID",
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.delete('URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/keys/$KEY_SLUG/enrichments/$ENRICHMENT_ID',
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

request
  .delete(`URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/keys/$KEY_SLUG/enrichments/$ENRICHMENT_ID`)
  .send()
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end((err, res) => console.log(res.text));

DELETE URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities/$ENTITY_SLUG/keys/$KEY_SLUG/enrichments/$ENRICHMENT_ID

This call doesn’t return any content.

Bot Builder API

/conversation_states

This endpoint manages builder conversations. A conversation is what allows us to recognize a user when a call is made to /dialog. Inside the scope of a call to /dialog you can change the language of the conversation or update it’s memory directly using builder actions, including webhook actions. Outside of this scope, you can do the same by updating the builder conversation using this REST endpoint.

Conversation model

Name	Type	Description
`id`	`UUID`	The internal id of the current conversation state
`conversation_id`	`String`	The id of the current conversation
`language`	`String`	The language of the current conversation
`memory`	`Hash`	The memory of your bot for the current conversation
`skill`	`String`	The slug of the current skill
`skill_occurrences`	`Integer`	The number of consecutive occurences for the current skill
`skill_stack`	`Array`	The current skill stack represented as an array of skill slugs

Show a conversation

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -X GET
     "URL_PREFIX/build/v1/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/builder/conversation_states/$CONVERSATION_ID"

require 'json'
require 'httparty'

result = HTTParty.get('URL_PREFIX/build/v1/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/builder/conversation_states/$CONVERSATION_ID',
  headers: {
    'Authorization' => 'Token DEVELOPER_TOKEN'
  }
)

puts JSON.parse(result.body)

import requests

response = requests.get('URL_PREFIX/build/v1/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/builder/conversation_states/$CONVERSATION_ID',
                        headers={'Authorization': 'Token DEVELOPER_TOKEN'}
                        )

print(response.text)

const request = require("superagent");

request
  .get("URL_PREFIX/build/v1/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/builder/conversation_states/$CONVERSATION_ID")
  .send()
  .set("Authorization", "Token DEVELOPER_TOKEN")
  .end((err, res) => console.log(res.text));

GET URL_PREFIX/build/v1/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/builder/conversation_states/$CONVERSATION_ID

This call returns a conversation model in the results field.

Update a conversation

This call allows you to update the language or the memory of your conversation. If merge_memory is set, the memory you pass as argument won’t override the current memory entirely, new fields will be added or override existing ones, and old ones will be kept.

Parameter	Type	Description	Constraints
`language`	`String`	The language of the conversation	Optional, a valid isocode
`memory`	`Object`	The new memory of the conversation	Optional
`merge_memory`	`Boolean`	If set to `true`, won’t override the memory but merge it	Optional

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{ "language": "en", "merge_memory": true, "memory": { "user": { "id": "12345", "name": "John Doe" } } }' \
     -X PUT
     "URL_PREFIX/build/v1/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/builder/conversation_states/$CONVERSATION_ID"

require 'json'
require 'httparty'

result = HTTParty.put('URL_PREFIX/build/v1/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/builder/conversation_states/$CONVERSATION_ID',
  body: {language: 'en'}.to_json,
  headers: {
    'Authorization' => 'Token DEVELOPER_TOKEN',
    'Content-Type' => 'application/json'
  }
)

puts JSON.parse(result.body)

import requests

response = requests.put('URL_PREFIX/build/v1/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/builder/conversation_states/$CONVERSATION_ID',
                        json={'language': 'en'},
                        headers={'Authorization': 'Token DEVELOPER_TOKEN',
                                 'Content-type': 'application/json'}
                        )

print(response.text)

const request = require("superagent");

request
  .put("URL_PREFIX/build/v1/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/builder/conversation_states/$CONVERSATION_ID")
  .send({ language: "en"})
  .set("Authorization", "Token DEVELOPER_TOKEN")
  .set("Content-type", "application/json")
  .end((err, res) => console.log(res.text));

PUT URL_PREFIX/build/v1/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/builder/conversation_states/$CONVERSATION_ID

This call returns a conversation model in the results field.

Delete a conversation

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -X DELETE 
     "URL_PREFIX/build/v1/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/builder/conversation_states/$CONVERSATION_ID"

require 'json'
require 'httparty'

result = HTTParty.delete('URL_PREFIX/build/v1/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/builder/conversation_states/$CONVERSATION_ID',
  headers: {
    'Authorization' => 'Token DEVELOPER_TOKEN'
  }
)

puts JSON.parse(result.body)

import requests

response = requests.delete('URL_PREFIX/build/v1/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/builder/conversation_states/$CONVERSATION_ID',
                           headers={'Authorization': 'Token DEVELOPER_TOKEN'}
                           )

print(response.text)

const request = require("superagent");

request
  .delete("URL_PREFIX/build/v1/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/builder/conversation_states/$CONVERSATION_ID")
  .send()
  .set("Authorization", "Token DEVELOPER_TOKEN")
  .end((err, res) => console.log(res.text))

DELETE URL_PREFIX/build/v1/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/builder/conversation_states/$CONVERSATION_ID

Bot Testing API

/specs

This endpoint manages bot testing documents. A test document contains a set of test cases that can be executed for a specific version of a bot.

Spec Model

Variable	Type	Description
`id`	`UUID`	A unique spec ID
`name`	`String`	The spec name
`total_test_cases`	`Integer`	Number of test cases in the spec
`last_successful_run`	`Run`	The last successfully executed run of this spec
`executed_run`	`Run`	The currently executed run of this spec

Creating a Spec

curl --location --request POST URL_PREFIX/bottesting/v1/users/$USER_SLUG/bots/$BOT_SLUG/specs \
--header 'Authorization: Token DEVELOPER_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name" : "new spec name 2"
}'

POST URL_PREFIX/bottesting/v1/users/$USER_SLUG/bots/$BOT_SLUG/specs

Path Parameters

Name	Type	Description
user_slug	`String`	The `slug` of the user
bot_slug	`String`	The `slug` of the bot

Body Parameters

Name	Type	Description
name	`String`	The name of the spec

Listing Specs

curl --location --request GET URL_PREFIX/bottesting/v1/users/$USER_SLUG/bots/$BOT_SLUG/specs?page=1&per_page=10 \
--header 'Authorization: Token DEVELOPER_TOKEN'

GET URL_PREFIX/bottesting/v1/users/$USER_SLUG/bots/$BOT_SLUG/specs

Path Parameters

Name	Type	Description
user_slug	`String`	The `slug` of the user
bot_slug	`String`	The `slug` of the bot

URL Parameters

Name	Type	Description
page	`Integer`	(Optional) The `page` index for pagination
per_page	`Integer`	(Optional) The number of items per page

Fetching a Spec

curl --location --request GET URL_PREFIX/bottesting/v1/users/$USER_SLUG/bots/$BOT_SLUG/specs/$SPEC_ID \
--header 'Authorization: Token DEVELOPER_TOKEN'

GET URL_PREFIX/bottesting/v1/users/$USER_SLUG/bots/$BOT_SLUG/specs/$SPEC_ID

Name	Type	Description
user_slug	`String`	The `slug` of the user
bot_slug	`String`	The `slug` of the bot
spec_id	`String`	The `id` of the spec

Deleting a Spec

curl --location --request DELETE URL_PREFIX/bottesting/v1/users/$USER_SLUG/bots/$BOT_SLUG/specs/$SPEC_ID \
--header 'Authorization: Token DEVELOPER_TOKEN'

DELETE URL_PREFIX/bottesting/v1/users/$USER_SLUG/bots/$BOT_SLUG/specs/$SPEC_ID

Path Parameters

Name	Type	Description
user_slug	`String`	The `slug` of the user
bot_slug	`String`	The `slug` of the bot
spec_id	`String`	The `id` of the spec

Deleting All Specs

curl --location --request DELETE URL_PREFIX/bottesting/v1/users/$USER_SLUG/bots/$BOT_SLUG/specs \
--header 'Authorization: Token DEVELOPER_TOKEN'

DELETE URL_PREFIX/bottesting/v1/users/$USER_SLUG/bots/$BOT_SLUG/specs

Path Parameters

Name	Type	Description
user_slug	`String`	The `slug` of the user
bot_slug	`String`	The `slug` of the bot

/test_cases

This endpoint manages the test cases that are included in a test document.

Test Case Model

Variable	Type	Description	Constraints
`id`	`UUID`	A unique test case ID
`inputs.expression`	`String`	The expression under test	Required, a valid expression, max 255 characters
`outputs.intent`	`String`	The expected intent of the expression
`outputs.skill`	`String`	The expected skill of the expression
`outputs.language`	`String`	The expected language of the expression
`outputs.entities`	`Array` of `Entity`	The expected entities of the expression

Creating test cases

curl --location --request POST URL_PREFIX/bottesting/v1/users/$USER_SLUG/bots/$BOT_SLUG/specs/$SPEC_ID/test_cases \
--header 'Authorization: Token DEVELOPER_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
    "test_cases":[{        
       "inputs": {
           "expression": "I want to go to Paris"
       },
       "outputs": {
           "intent": "book-flight",
            "skill": "book-flight",
            "language": "en",
            "entities": [
                {
                    "raw": "I",
                    "type": "PRONOUN"
                },
                {
                    "raw": "Paris",
                    "type": "LOCATION"
                }
            ]
       }
    }]
}'

POST URL_PREFIX/bottesting/v1/users/$USER_SLUG/bots/$BOT_SLUG/specs/$SPEC_ID/test_cases

Path Parameters

Name	Type	Description
user_slug	`String`	The `slug` of the user
bot_slug	`String`	The `slug` of the bot
spec_id	`String`	The `id` of the spec

Body Parameters

The test cases to create

Creating a test case from inputs

curl --location --request POST URL_PREFIX/bottesting/v1/users/$USER_SLUG/bots/$BOT_SLUG/specs/$SPEC_ID/test_cases/sync_add \
--header 'Authorization: Token DEVELOPER_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
    "infer_outputs_from_version_id": "VERSION_ID",
    "inputs": {
        "expression": "I want to go to Paris"
    }
}'

POST URL_PREFIX/bottesting/v1/users/$USER_SLUG/bots/$BOT_SLUG/specs/$SPEC_ID/test_cases/sync_add

Path Parameters

Name	Type	Description
user_slug	`String`	The `slug` of the user
bot_slug	`String`	The `slug` of the bot
spec_id	`String`	The `id` of the spec

Body Parameters

Name	Type	Description
infer_outputs_from_version_id	`String`	The version ID of the bot
inputs.expression	`String`	The input expression of the test case

Listing test cases in a spec

curl --location --request GET URL_PREFIX/bottesting/v1/users/$USER_SLUG/bots/$BOT_SLUG/specs/$SPEC_ID/test_cases?page=1&per_page=10 \
--header 'Authorization: Token DEVELOPER_TOKEN' \
--header 'Content-Type: application/json'

GET URL_PREFIX/bottesting/v1/users/$USER_SLUG/bots/$BOT_SLUG/specs/$SPEC_ID/test_cases

Path Parameters

Name	Type	Description
user_slug	`String`	The `slug` of the user
bot_slug	`String`	The `slug` of the bot
spec_id	`String`	The `id` of the spec

URL Parameters

Name	Type	Description
page	`Integer`	(Optional) The `page` index for pagination
per_page	`Integer`	(Optional) The number of items per page

Fetching a test case

curl --location --request GET URL_PREFIX/bottesting/v1/users/$USER_SLUG/bots/$BOT_SLUG/specs/$SPEC_ID/test_cases/$TEST_CASE_ID \
--header 'Authorization: Token DEVELOPER_TOKEN' \
--header 'Content-Type: application/json'

GET URL_PREFIX/bottesting/v1/users/$USER_SLUG/bots/$BOT_SLUG/specs/$SPEC_ID/test_cases/$TEST_CASE_ID

Path Parameters

Name	Type	Description
user_slug	`String`	The `slug` of the user
bot_slug	`String`	The `slug` of the bot
spec_id	`String`	The `id` of the spec
test_case_id	`String`	The `id` of the test case

Updating a test case

curl --location --request PUT URL_PREFIX/bottesting/v1/users/$USER_SLUG/bots/$BOT_SLUG/specs/$SPEC_ID/test_cases/$TEST_CASE_ID \
--header 'Authorization: Token DEVELOPER_TOKEN' \
--header 'Content-Type: application/json'
--data-raw '{    
    "inputs": {
        "expression": "I want to go to Paris"
    },
    "outputs": {
        "intent": "suggest-flight",
        "skill": "suggest-flight",
        "language": "en",
        "entities": [
            {
                "raw": "Paris",
                "type": "LOCATION"
            }
        ]
    }    
}'

PUT URL_PREFIX/bottesting/v1/users/$USER_SLUG/bots/$BOT_SLUG/specs/$SPEC_ID/test_cases/$TEST_CASE_ID

Path Parameters

Name	Type	Description
user_slug	`String`	The `slug` of the user
bot_slug	`String`	The `slug` of the bot
spec_id	`String`	The `id` of the spec
test_case_id	`String`	The `id` of the test case

Body Parameters

A TestCase object

Deleting a test case

curl --location --request DELETE URL_PREFIX/bottesting/v1/users/$USER_SLUG/bots/$BOT_SLUG/specs/$SPEC_ID/test_cases/$TEST_CASE_ID \
--header 'Authorization: Token DEVELOPER_TOKEN' \
--header 'Content-Type: application/json'

DELETE URL_PREFIX/bottesting/v1/users/$USER_SLUG/bots/$BOT_SLUG/specs/$SPEC_ID/test_cases/$TEST_CASE_ID

Path Parameters

Name	Type	Description
user_slug	`String`	The `slug` of the user
bot_slug	`String`	The `slug` of the bot
spec_id	`String`	The `id` of the spec
test_case_id	`String`	The `id` of the test case

Bulk deleting test cases

curl --location --request POST URL_PREFIX/bottesting/v1/users/$USER_SLUG/bots/$BOT_SLUG/specs/$SPEC_ID/test_cases/bulk_delete \
--header 'Authorization: Token DEVELOPER_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
    "test_cases": [
        {
            "id": "TEST_CASE_ID_1"
        },
        {
            "id": "TEST_CASE_ID_2"
        }
    ]
}'

POST URL_PREFIX/bottesting/v1/users/$USER_SLUG/bots/$BOT_SLUG/specs/$SPEC_ID/test_cases/bulk_delete

Path Parameters

Name	Type	Description
user_slug	`String`	The `slug` of the user
bot_slug	`String`	The `slug` of the bot
spec_id	`String`	The `id` of the spec

Body Parameters

List of test case IDs to be deleted | Name | Type | Description | |:——————|:———–|:————————————–| | id | String |

The id of the test case

/runs

This endpoint manages the test runs of a bot testing document.

Run Model

Variable	Type	Description
`id`	`UUID`	A unique run ID
`created_at`	`String`	The timestamp of the run initiation
`status`	`IN_PROGRESS, FAILED, FINISHED`	The current status of the test run
`version_id`	`String`	Version ID
`results.total_test_cases`	`Integer`	Total test cases of the run
`results.total_test_cases_failed`	`Integer`	Total failed test cases of the run

Creating a run

This API triggers a new test run against the bot version specified in target_version_id.

curl --location --request POST URL_PREFIX/bottesting/v1/users/$USER_SLUG/bots/$BOT_SLUG/specs/$SPEC_ID/runs \
--header 'Authorization: Token DEVELOPER_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
    "target_version_id" : "VERSION_UUID"
}'

POST URL_PREFIX/bottesting/v1/users/$USER_SLUG/bots/$BOT_SLUG/specs/$SPEC_ID/runs

Path Parameters

Name	Type	Description
user_slug	`String`	The `slug` of the user
bot_slug	`String`	The `slug` of the bot
spec_id	`String`	The `id` of the spec

Body Parameters

Name	Type	Description
target_version_id	`String`	The `id` of the version

Listing Runs

curl --location --request POST URL_PREFIX/bottesting/v1/users/$USER_SLUG/bots/$BOT_SLUG/specs/$SPEC_ID/runs?page=1&per_page=10&status="FINISHED" \
--header 'Authorization: Token DEVELOPER_TOKEN' \
--header 'Content-Type: application/json'

GET URL_PREFIX/bottesting/v1/users/$USER_SLUG/bots/$BOT_SLUG/specs/$SPEC_ID/runs

Path Parameters

Name	Type	Description
user_slug	`String`	The `slug` of the user
bot_slug	`String`	The `slug` of the bot
spec_id	`String`	The `id` of the spec

URL Parameters

Name	Type	Description
page	`Integer`	(Optional) The `page` index for pagination
per_page	`Integer`	(Optional) The number of items per page
status	`IN_PROGRESS, FAILED, FINISHED`	(Optional) The status of the test run

Deleting a Test Run

curl --location --request DELETE URL_PREFIX/bottesting/v1/users/$USER_SLUG/bots/$BOT_SLUG/specs/$SPEC_ID/runs/$RUN_ID \
--header 'Authorization: Token DEVELOPER_TOKEN'

DELETE URL_PREFIX/bottesting/v1/users/$USER_SLUG/bots/$BOT_SLUG/specs/$SPEC_ID/runs/$RUN_ID

Path Parameters

Name	Type	Description
user_slug	`String`	The `slug` of the user
bot_slug	`String`	The `slug` of the bot
spec_id	`String`	The `id` of the spec
run_id	`String`	The `id` of the run

Bulk Delete Test Runs

curl --location --request POST URL_PREFIX/bottesting/v1/users/$USER_SLUG/bots/$BOT_SLUG/specs/$SPEC_ID/runs/bulk_delete \
--header 'Authorization: Token DEVELOPER_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
    "runs": [
        {
            "id": "RUN_ID_1"
        },
        {
            "id": "RUN_ID_2"
        }
    ]
}'

POST URL_PREFIX/bottesting/v1/users/$USER_SLUG/bots/$BOT_SLUG/specs/$SPEC_ID/runs/bulk_delete

Path Parameters

Name	Type	Description
user_slug	`String`	The `slug` of the user
bot_slug	`String`	The `slug` of the bot
spec_id	`String`	The `id` of the spec

Body Parameters

List of run IDs to be deleted | Name | Type | Description | |:—————-|:———–|:————————————–| | id | String |

The id of the test run

/test_case_results

This endpoint manages the test case results of the run.

Test Case Result model

Variable	Type	Description
`id`	`UUID`	A unique test case ID
`validation_failed`	`Boolean`	Boolean indicating validation failed or not.
`inputs.expression`	`String`	The input expression of the test case
`outputs.intent.actual`	`String`	The actual intent of the expression
`outputs.intent.expected`	`String`	The expected intent of the expression
`outputs.intent.errors`	`Errors`	The errors of the intent validation
`outputs.skill.actual`	`String`	The actual skill of the expression
`outputs.skill.expected`	`String`	The expected skill of the expression
`outputs.skill.errors`	`Errors`	The errors of the skill validation
`outputs.language.actual`	`String`	The actual language of the expression
`outputs.language.expected`	`String`	The expected language of the expression
`outputs.language.errors`	`Errors`	The errors of the language validation
`outputs.entities.actual`	`Entity`	The actual entities of the expression
`outputs.entities.expected`	`Entity`	The expected entities of the expression
`outputs.entities.errors`	`Errors`	The errors of the entities validation

Listing test case results

curl --location --request GET URL_PREFIX/bottesting/v1/users/$USER_SLUG/bots/$BOT_SLUG/specs/$SPEC_ID/runs/$RUN_ID/test_case_results?page=1&per_page=10&validation_failed=true  \
--header 'Authorization: Token DEVELOPER_TOKEN' \
--header 'Content-Type: application/json'

GET URL_PREFIX/bottesting/v1/users/$USER_SLUG/bots/$BOT_SLUG/specs/$SPEC_ID/runs/$RUN_ID/test_case_results

Path Parameters

Name	Type	Description
user_slug	`String`	The `slug` of the user
bot_slug	`String`	The `slug` of the bot
spec_id	`String`	The `id` of the spec
run_id	`String`	The `id` of the run

URL Parameters

Name	Type	Description
page	`Integer`	(Optional) The `page` index for pagination
per_page	`Integer`	(Optional) The number of items per page
validation_failed	`Boolean`	(Optional) Boolean indicating validation failed or not

Bot Connector API

/connectors

This endpoint manages connectors.

Connector model

Variable	Type	Description
`id`	`String`	An unique connector uuid
`botId`	`String`	The bot’s id linked to the connector
`name`	`String`	The connector’s name
`url`	`String`	The connector’s endpoint
`channels`	`Array` of `Channel`	The connector’s Channels
`conversations`	`Array` of `Conversation`	The connector’s Conversations

Showing a connector

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -X GET "URL_PREFIX/connect/v1/connectors/$BOT_ID"

require 'json'
require 'httparty'

result = HTTParty.get("URL_PREFIX/connect/v1/connectors/$BOT_ID",
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.get('URL_PREFIX/connect/v1/connectors/$BOT_ID',
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

request
  .get(`URL_PREFIX/connect/v1/connectors/${BOT_ID}`)
  .send()
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end((err, res) => console.log(res.text));

GET URL_PREFIX/connect/v1/connectors/${BOT_ID}

This call returns a connector model in the results field.

Updating a connector

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"name":NAME, "url":URL}' \
     -X PUT "URL_PREFIX/connect/v1/connectors/$BOT_ID"

require 'json'
require 'httparty'

result = HTTParty.put("URL_PREFIX/connect/v1/connectors/$BOT_ID",
  body: { name: NAME, url: URL },
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.put('URL_PREFIX/connect/v1/connectors/$BOT_ID',
  json={'name': NAME, 'url': URL},
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

request
  .put(`URL_PREFIX/connect/v1/connectors/${BOT_ID}`)
  .send({ url: 'URL' })
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end((err, res) => console.log(res.text));

PUT URL_PREFIX/connect/v1/connectors/${BOT_ID}

This call returns a connector model in the results field.

Parameter	Type	Description	Constraints
`url`	`String`	The connector’s endpoint	Required, a valid url
`botEnvironmentId`	`String`	Environment to use when using bot builder	Optional

Deleting a connector

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -X DELETE "URL_PREFIX/connect/v1/connectors/$BOT_ID"

require 'json'
require 'httparty'

result = HTTParty.delete("URL_PREFIX/connect/v1/connectors/$BOT_ID",
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.delete('URL_PREFIX/connect/v1/connectors/$BOT_ID',
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

request
  .delete(`URL_PREFIX/connect/v1/connectors/${BOT_ID}`)
  .send()
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end((err, res) => console.log(res.text));

DELETE URL_PREFIX/connect/v1/connectors/${BOT_ID}

This call does not return any content.

/channels

This endpoint manages channels.

Channel model

Variable	Type	Description
`id`	`String`	An unique channel uuid
`connector`	`String`	The connector uuid
`slug`	`String`	The channel’s name
`isActivated`	`Boolean`	The channel’s state
`type`	`String`	The channel’s type
`webhook`	`String`	The channel’s webhook to receive a message

The channel contains various other fields, depending on its type, among the followings:

Showing a channel

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -X GET "URL_PREFIX/connect/v1/channels/$CHANNEL_SLUG"

require 'json'
require 'httparty'

result = HTTParty.get("URL_PREFIX/connect/v1/channels/$CHANNEL_SLUG",
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.get('URL_PREFIX/connect/v1/channels/$CHANNEL_SLUG',
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

request
  .get(`URL_PREFIX/connect/v1/channels/${CHANNEL_SLUG}`)
  .send()
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end((err, res) => console.log(res.text));

GET URL_PREFIX/connect/v1/channels/$CHANNEL_SLUG

This call returns a channel model in the results field.

Indexing channels

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -X GET "URL_PREFIX/connect/v1/channels"

require 'json'
require 'httparty'

result = HTTParty.get("URL_PREFIX/connect/v1/channels",
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.get('URL_PREFIX/connect/v1/channels',
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

request
  .get('URL_PREFIX/connect/v1/channels')
  .send()
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end((err, res) => console.log(res.text));

GET URL_PREFIX/connect/v1/channels

This call returns a collection of channel models in the results field.

Creating a channel

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"isActivated":true, "slug":SLUG, "type":TYPE}' \
     -X POST "URL_PREFIX/connect/v1/channels"

require 'json'
require 'httparty'

result = HTTParty.post("URL_PREFIX/connect/v1/channels",
  body: { isActivated: true, slug: SLUG, type: TYPE },
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.post('URL_PREFIX/connect/v1/channels',
  json={'isActivated': true, 'slug': SLUG, 'type': TYPE },
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

request
  .post('URL_PREFIX/connect/v1/channels')
  .send({
    isActivated: true,
    slug: 'SLUG',
    type: 'TYPE',
  })
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end((err, res) => console.log(res.text));

POST URL_PREFIX/connect/v1/channels

This call returns a channel model in results variable.

Parameter	Type	Description	Constraints
`type`	`String`	The channel’s type	Required, one of the supported integrations
`slug`	`String`	The channel’s slug	Required
`isActivated`	`Boolean`	Weither the channel is active or not	Required

Updating a channel

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"isActivated":true, "slug":SLUG, "type":TYPE}' \
     -X PUT "URL_PREFIX/connect/v1/channels/$CHANNEL_SLUG"

require 'json'
require 'httparty'

result = HTTParty.put("URL_PREFIX/connect/v1/channels/$CHANNEL_SLUG",
  body: { isActivated: true, slug: SLUG, type: TYPE },
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.put('URL_PREFIX/connect/v1/channels/$CHANNEL_SLUG',
  json={'isActivated': true, 'slug': SLUG, 'type': TYPE},
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

request
  .put(`URL_PREFIX/connect/v1/channels/${CHANNEL_SLUG}`)
  .send({
    isActivated: ISACTIVATED,
    slug: 'SLUG',
    type: 'TYPE',
  })
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end((err, res) => console.log(res.text));

PUT URL_PREFIX/connect/v1/channels/$CHANNEL_SLUG

This call returns a channel model in results variable.

Parameter	Type	Description	Constraints
`type`	`String`	The channel’s type	One of the supported integrations
`slug`	`String`	The channel’s slug
`isActivated`	`Boolean`	Whether the channel is active or not

Deleting a channel

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -X DELETE "URL_PREFIX/connect/v1/channels/$CHANNEL_SLUG"

require 'json'
require 'httparty'

result = HTTParty.delete("URL_PREFIX/connect/v1/channels/$CHANNEL_SLUG",
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.delete('URL_PREFIX/connect/v1/channels/$CHANNEL_SLUG',
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

request
  .delete(`URL_PREFIX/connect/v1/channels/${CHANNEL_SLUG}`)
  .send()
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end((err, res) => console.log(res.text));

DELETE URL_PREFIX/connect/v1/channels/${CHANNEL_SLUG}

This call does not return any content.

/conversations

This endpoint manages conversations.

Conversation model

Variable	Type	Description
`id`	`String`	The conversation’s uuid
`connector`	`String`	The connector’s uuid
`channel`	`String`	The channel’s uuid
`chatId`	`String`	The native ChatId
`createdAt`	`String`	The conversation’s creation date
`participants`	`Array` of `Participant`	An array of participants
`messages`	`Array` of `Message`	An array of messages

Showing a conversation

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -X GET "URL_PREFIX/connect/v1/conversations/$CONVERSATION_ID"

require 'json'
require 'httparty'

result = HTTParty.get("URL_PREFIX/connect/v1/conversations/$CONVERSATION_ID",
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.get('URL_PREFIX/connect/v1/conversations/$CONVERSATION_ID',
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

request
  .get(`URL_PREFIX/connect/v1/conversations/${CONVERSATION_ID}`)
  .send()
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end((err, res) => console.log(res.text));

GET URL_PREFIX/connect/v1/conversations/${CONVERSATION_ID}

This call returns a conversation model in results variable.

Indexing conversations

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -X GET "URL_PREFIX/connect/v1/conversations"

require 'json'
require 'httparty'

result = HTTParty.get("URL_PREFIX/connect/v1/conversations",
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.get('URL_PREFIX/connect/v1/conversations',
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

request
  .get('URL_PREFIX/connect/v1/conversations')
  .send()
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end((err, res) => console.log(res.text));

GET URL_PREFIX/connect/v1/conversations

This call returns a collection of conversation models in results variable.

Query Parameters

This call supports the following optional query parameters:

Name	Type	Description
`from`	`Date`	A date in the format `YYYY-MM-DD`. Conversations created before the `from` date will not be returned.
`to`	`Date`	A date in the format `YYYY-MM-DD`. Conversations created after the `to` date will not be returned.
`skipEmpty`	`Boolean`	Accepts `true` or `false`. Conversations with no messages will not be returned when set to `true`.

As an example, the following call will return the conversations created between April 10, 2020 and April 23, 2020, omitting conversations that contain no messages.

GET [<URL Prefix>]/connect/v1/conversations?from=2020-04-10&to=2020-04-23&skipEmpty=true

The date range defined by from and to has a maximum length of 3 months. When using only from or to as query parameters, the date range, by default, will be a period of 3 months.

Deleting a conversation

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -X DELETE "URL_PREFIX/connect/v1/conversations/$CONVERSATION_ID"

require 'json'
require 'httparty'

result = HTTParty.delete("URL_PREFIX/connect/v1/conversations/$CONVERSATION_ID",
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.delete('URL_PREFIX/connect/v1/conversations/$CONVERSATION_ID',
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

request
  .delete(`URL_PREFIX/connect/v1/conversations/${CONVERSATION_ID}`)
  .send()
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end((err, res) => console.log(res.text));

DELETE URL_PREFIX/connect/v1/conversations/$CONVERSATION_ID

This call does not return any content.

/participants

This endpoint manages participants.

Participant model

Variable	Type	Description
`id`	`String`	The participant’s id
`senderId`	`String`	The native sender’s id
`isBot`	`Boolean`	The participant’s state

Showing a participant

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -X GET "URL_PREFIX/connect/v1/participants/$PARTICIPANT_ID"

require 'json'
require 'httparty'

result = HTTParty.get("URL_PREFIX/connect/v1/participants/$PARTICIPANT_ID",
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.get('URL_PREFIX/connect/v1/participants/$PARTICIPANT_ID',
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

request
  .get(`URL_PREFIX/connect/v1/participants/${PARTICIPANT_ID}`)
  .send()
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end((err, res) => console.log(res.text));

GET URL_PREFIX/connect/v1/participants/${PARTICIPANT_ID}

This call returns a participant model in results variable.

Indexing participants

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -X GET "URL_PREFIX/connect/v1/participants"

require 'json'
require 'httparty'

result = HTTParty.get("URL_PREFIX/connect/v1/participants",
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.get('URL_PREFIX/connect/v1/participants',
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

request
  .get('URL_PREFIX/connect/v1/participants')
  .send()
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end((err, res) => console.log(res.text));

GET URL_PREFIX/connect/v1/participants

This call returns a collection of participant models in results variable.

Showing participant history

curl -H "Authorization: Token DEVELOPER_TOKEN" \  
     -X GET "URL_PREFIX/usage-metrics/v2/message_logs/participant_history?sender_id=$SENDER_ID&origin=$CHANNEL_SLUG"

require 'json'
require 'httparty'

result = HTTParty.get("URL_PREFIX/usage-metrics/v2/message_logs/participant_history?sender_id=$SENDER_ID&origin=$CHANNEL_SLUG",
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.get('URL_PREFIX/usage-metrics/v2/message_logs/participant_history?sender_id=$SENDER_ID&origin=$CHANNEL_SLUG',
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

  .get(`URL_PREFIX/usage-metrics/v2/message_logs/participant_history?sender_id=${SENDER_ID}&origin=${CHANNEL_SLUG}`)
  .send()
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end((err, res) => console.log(res.text));

GET URL_PREFIX/usage-metrics/v2/message_logs/participant_history?sender_id=${SENDER_ID}&origin=${CHANNEL_SLUG}

Query Parameters

Name	Type	Description
sender_id	`String`	The native sender’s id
origin	`String`	Channel Type

Erase participant history

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -d '{
      "sender_id": "Sender-Id",
      "origin": "Channel-Type"
      }' \
     -X POST "URL_PREFIX/usage-metrics/v2/message_logs/erase_participant_history"

require 'json'
require 'httparty'

result = HTTParty.post("URL_PREFIX/usage-metrics/v2/message_logs/erase_participant_history",
  body: {sender_id: "Sender-Id",
      origin: "Channel-Type"}
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.post('URL_PREFIX/usage-metrics/v2/message_logs/erase_participant_history',
  json={'sender_id': 'Sender-Id',
      'origin': 'Channel-Type'}
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

request
  .post(`URL_PREFIX/usage-metrics/v2/message_logs/erase_participant_history`)
  .send({sender_id: "Sender-Id",
      origin: "Channel-Type"})
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end((err, res) => console.log(res.text));

POST URL_PREFIX/usage-metrics/v2/message_logs/erase_participant_history

Body Parameters

{
  "sender_id": "Sender-Id",
  "origin": "Channel-Type"
}

Name	Type	Description
sender_id	`String`	The native sender’s id
origin	`String`	Channel Type

/messages

Send a message

This endpoint sends a message on a specific conversation.

curl -X POST -H "Authorization: Token REQUEST_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"messages": [{ "type": "text", "content": "Hello world!"}]}' \
     "URL_PREFIX/connect/v1/conversations/$CONVERSATION_ID/messages"

require 'json'
require 'httparty'

result = HTTParty.post("URL_PREFIX/connect/v1/conversations/$CONVERSATION_ID/messages",
  body: { messages: [{ type: "text", content: "Hello World !" }]},
  headers: { 'Authorization' => 'Token REQUEST_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.post('URL_PREFIX/connect/v1/conversations/$CONVERSATION_ID/messages',
  json={ "messages": [{ "type": "text", "content": "Hello World !" }]},
  headers={'Authorization': 'Token REQUEST_TOKEN'}
)

print(response.text)

const request = require('superagent');

request
  .post('URL_PREFIX/connect/v1/conversations/$CONVERSATION_ID/messages')
  .send({ messages: [{ type: 'text', content: 'Hello, world!' }] })
  .set('Authorization', 'Token REQUEST_TOKEN')
  .end(function(err, res) {
    console.log(res);
  });

POST URL_PREFIX/connect/v1/conversations/$CONVERSATION_ID/messages

Name	Type	Description	Constraints
`messages`	`Array` of `Message`	Check the Message format here

Check Hello world in the concepts guide to receive and send messages easily.

Response

We return a 201 when the message has been successfully posted.

Errors

We will return an error (400: bad_request) if any of these cases is met:

The messages parameter is not well formated.

We will return an error (401: unauthorized) if the following case is met:

The token provided in your request is not linked to any of your bots.

We will return an error (503: service_unavailable) if any of these cases is met:

The service you try to send the message to is unavailable.

Broadcast a message

This endpoint sends a message on every connector’s conversations.

curl -X POST -H "Authorization: Token REQUEST_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"messages": [{ "type": "text", "content": "Hello world!"}]}' \
     "URL_PREFIX/connect/v1/messages"

require 'json'
require 'httparty'

result = HTTParty.post("URL_PREFIX/connect/v1/messages",
  body: { messages: [{ type: "text", content: "Hello World !" }]},
  headers: { 'Authorization' => 'Token REQUEST_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.post('URL_PREFIX/connect/v1/messages',
  json={ "messages": [{ "type": "text", "content": "Hello World !" }]},
  headers={'Authorization': 'Token REQUEST_TOKEN'}
)

print(response.text)

const request = require('superagent');

request
  .post('URL_PREFIX/connect/v1/messages')
  .send({ messages: [{ type: 'text', content: 'Hello, world!' }] })
  .set('Authorization', 'Token REQUEST_TOKEN')
  .end(function(err, res) {
    console.log(res);
  });

POST URL_PREFIX/connect/v1/messages

Name	Type	Description	Constraints
`messages`	`Array` of `Message`	Check the Message format here

Response

We return a 201 when the message has been successfully posted.

Errors

We will return an error (400: bad_request) if any of these cases is met:

The messages parameter is not well formated.

We will return an error (401: unauthorized) if the following case is met:

The token provided in your request is not linked to any of your bots.

We will return an error (503: service_unavailable) if any of these cases is met:

The service you try to send the message to is unavailable.

Conversational Logs API

/bulk_delete endpoint

This API takes a timestamp as input along with developer token in request header, checks for write permissions on bot level and deletes the conversation logs for a bot based on the provided timestamp. The API responds error message if the token is not the developer token.

This deletion is done asynchronously via a batch job. Successful submission will be returned with 200 status.

Variable	Type	Description	Constraints
`before`	`Date`	The data earlier than provided date is deleted considering minimal retention period of 1 year from current system date.

curl --location --request DELETE 'URL_PREFIX/logs/v2/messages_logs/bulk_delete?before='2018-06-12T11:49:21.674Z' \
--header 'Authorization: Token <bot-dev-token>' \
--data-raw ''

Errors

Gives 403 Forbidden with Version Req token in Authorization header
Gives 403 Forbidden with Env Req token in Authorization header
Gives 401 Unauthorized without bot-dev-token in Authorization header
Gives 400 Bad Request Parameter is missing if timestamp missing
Gives 400 if Parameter date hasn’t happen yet
Gives 400 if Parameter date is less than a year from TODAY
Gives 400 if Date parameter is incorrect format

FAQ Bot API

/Answers

This endpoint manages answers.

Creating An Answer

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"value":"You send this post request", "questions_attributes":[{"value": "How do I add an answer?"}]}' \
     -X POST
     "URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/qna/topic/knowledge_sources/$KNOWLEDGE_SOURCE_SLUG/answers"

result = HTTParty.post("URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/qna/topic/knowledge_sources/$KNOWLEDGE_SOURCE_SLUG/answers",
  body: { value: "You send this post request", questions_attributes:[{value: "How do I add an answer?"}] },
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.post('URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/qna/topic/knowledge_sources/$KNOWLEDGE_SOURCE_SLUG/answers',
  json={'value': 'You send this post request', 'questions_attributes':[{'value': 'How do I add an answer?'}]},
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

const request = require('superagent');

request
  .post(`URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/qna/topic/knowledge_sources/$KNOWLEDGE_SOURCE_SLUG/answers`)
  .send({
    value: "You send this post request",
    questions_attributes:[{value: "How do I add an answer?"}]
  })
  .set("Authorization", "Token DEVELOPER_TOKEN")
  .end((err, res) => console.log(res.text));

POST URL_PREFIX/train/v2/users/:user_id/bots/:bot_id/versions/:version_id/qna/topic/knowledge_sources/:knowledge_source_id/answers

Path Parameters

Name	Type	Description
user_id	`String`	The `slug` of the user
bot_id	`String`	The `slug` of the bot
version_id	`String`	The `slug` of the version
knowledge_source_id	`String`	The `slug` of the knowledge source

Body Parameters

{
  "value": "My answer",
  "disabled": true,
  "questions_attributes": [
    {
      "value": "A question?"
    }
  ]
}

Name	Type	Description
value	`String`	The text of the answer
questions_attributes	`JSON`	JSON array of questions to be added

Deleting An Answer

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -X DELETE "URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/qna/topic/knowledge_sources/$KNOWLEDGE_SOURCE_SLUG/answers/$ANSWER_ID"

result = HTTParty.delete("URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/qna/topic/knowledge_sources/$KNOWLEDGE_SOURCE_SLUG/answers/$ANSWER_ID",
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.delete('URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/qna/topic/knowledge_sources/$KNOWLEDGE_SOURCE_SLUG/answers/$ANSWER_ID',
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

request
  .delete(`URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/qna/topic/knowledge_sources/$KNOWLEDGE_SOURCE_SLUG/answers/$ANSWER_ID`)
  .send()
  .set("Authorization", "Token DEVELOPER_TOKEN")
  .end((err, res) => console.log(res.text));

DELETE URL_PREFIX/train/v2/users/:user_id/bots/:bot_id/versions/:version_id/qna/topic/knowledge_sources/:knowledge_source_id/answers/:id

Path Parameters

Name	Type	Description
user_id	`String`	The `slug` of the user
bot_id	`String`	The `slug` of the bot
version_id	`String`	The `slug` of the version
knowledge_source_id	`String`	The `slug` of the knowledge source
id	`String`	The `id` of the answer

Indexing An Answer

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -X GET "URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/qna/topic/knowledge_sources/$KNOWLEDGE_SOURCE_SLUG/answers"

require 'json'
require 'httparty'

result = HTTParty.get("URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/qna/topic/knowledge_sources/$KNOWLEDGE_SOURCE_SLUG/answers",
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.get('URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/qna/topic/knowledge_sources/$KNOWLEDGE_SOURCE_SLUG/answers',
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

request
  .get(`URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/qna/topic/knowledge_sources/$KNOWLEDGE_SOURCE_SLUG/answers`)
  .send()
  .set("Authorization", "Token DEVELOPER_TOKEN")
  .end((err, res) => console.log(res.text));

GET URL_PREFIX/train/v2/users/:user_id/bots/:bot_id/versions/:version_id/qna/topic/knowledge_sources/:knowledge_source_id/answers

Path Parameters

Name	Type	Description
user_id	`String`	The `slug` of the user
bot_id	`String`	The `slug` of the bot
version_id	`String`	The `slug` of the version
knowledge_source_id	`String`	The `slug` of the knowledge source

Query Parameters - Pagination Parameters

Name	Type	Description
page	`Integer`	optional Optional current page index Size range: 0..
per_page	`Integer`	optional Optional number of items to display per page Size range: 0..

Query Parameters - Filtering Parameters

Name	Type	Description
query	`String`	optional The `query` to search items with Size range: 0..512
flagged	`Boolean`	optional Filter by flagged property Allowed values: true,false
enabled	`Boolean`	optional Filter by flagged property Allowed values: true,false

Showing An Answer

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -X GET "URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/qna/topic/knowledge_sources/$KNOWLEDGE_SOURCE_SLUG/answers/$ANSWER_ID"

require 'json'
require 'httparty'

result = HTTParty.get("URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/qna/topic/knowledge_sources/$KNOWLEDGE_SOURCE_SLUG/answers/$ANSWER_ID",
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.get('URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/qna/topic/knowledge_sources/$KNOWLEDGE_SOURCE_SLUG/answers/$ANSWER_ID',
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

request
  .get(`URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/qna/topic/knowledge_sources/$KNOWLEDGE_SOURCE_SLUG/answers/$ANSWER_ID`)
  .send()
  .set("Authorization", "Token DEVELOPER_TOKEN")
  .end((err, res) => console.log(res.text));

GET URL_PREFIX/train/v2/users/:user_id/bots/:bot_id/versions/:version_id/qna/topic/knowledge_sources/:knowledge_source_id/answers/:id

Path Parameters

Name	Type	Description
user_id	`String`	The `slug` of the user
bot_id	`String`	The `slug` of the bot
version_id	`String`	The `slug` of the version
knowledge_source_id	`String`	The `slug` of the knowledge source
id	`String`	The `id` of the answer

Updating An Answer

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"disabled": true}]}' \
     -X PUT "URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/qna/topic/knowledge_sources/$KNOWLEDGE_SOURCE_SLUG/answers/$ANSWER_ID"

result = HTTParty.put("URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/qna/topic/knowledge_sources/$KNOWLEDGE_SOURCE_SLUG/answers/$ANSWER_ID",
  body: { disabled: true },
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.put('URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/qna/topic/knowledge_sources/$KNOWLEDGE_SOURCE_SLUG/answers/$ANSWER_ID',
  json={'disabled': True},
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

const request = require('superagent');

request
  .put(`URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/qna/topic/knowledge_sources/$KNOWLEDGE_SOURCE_SLUG/answers/$ANSWER_ID`)
  .send({disabled: true})
  .set("Authorization", "Token DEVELOPER_TOKEN")
  .end((err, res) => console.log(res.text));

PUT URL_PREFIX/train/v2/users/:user_id/bots/:bot_id/versions/:version_id/qna/topic/knowledge_sources/:knowledge_source_id/answers/:id

Path Parameters

Name	Type	Description
user_id	`String`	The `slug` of the user
bot_id	`String`	The `slug` of the bot
version_id	`String`	The `slug` of the version
knowledge_source_id	`String`	The `slug` of the knowledge source
id	`String`	The `id` of the answer

Body Parameters

{
  "value": "My updated answer",
  "disabled": false,
  "flagged": true
}

Name	Type	Description
value	`String`	The text of the answer to be updated
disabled	`Boolean`	The text of the answer to be updated Allowed values: true,false
flagged	`Boolean`	The text of the answer to be updated Allowed values: true,false

/Knowledge Sources

This endpoint manages knowledge sources.

Knowledge Source Model

Variable	Type	Description
`id`	`UUID`	A unique knowledge source ID
`name`	`String`	The knowledge source name
`slug`	`String`	The knowledge source slug
`content_type`	`String`	The content type of the knowledge source
`content_hash`	`String`	The hash of the knowledge source
`language`	`Language`	The language of the knowledge source
`data_type`	`String`	The data type of the knowledge source; always ‘faq’
`faq_items_count`	`Integer`	Number of FAQ items in the knowledge source

Creating A Knowledge Source

curl -X POST URL_PREFIX/train/v2/users/$USER_SLUG/bots/$USER_BOT/versions/$VERSION_SLUG/qna/topic/knowledge_sources \
-H 'Authentication: Token DEVELOPER_TOKEN' \
-H 'Content-Type: multipart/form-data' \
-F file=@/path/to/file.csv \
-F language=en \

require "uri"
require "net/http"

url = URI("URL_PREFIX/train/v2/users/$USER_SLUG/bots/$USER_BOT/versions/$VERSION_SLUG/qna/topic/knowledge_sources")

https = Net::HTTP.new(url.host, url.port);
https.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authentication"] = "Token DEVELOPER_TOKEN"
request["Content-Type"] = "multipart/form-data"
form_data = [['file', '@/path/to/file.csv'],['language', 'en']]
request.set_form form_data, 'multipart/form-data'
response = https.request(request)
puts response.read_bodypreview

import requests

response = requests.post('URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/qna/topic/knowledge_sources/$KNOWLEDGE_SOURCE_SLUG/answers',
  data={'file': '@/path/to/file.csv', 'language': 'en'},
  headers={'Authorization': 'Token DEVELOPER_TOKEN', 'Content-Type': 'multipart/form-data'}
)

const request = require('superagent');

request
  .post(`URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/qna/topic/knowledge_sources/$KNOWLEDGE_SOURCE_SLUG/answers`)
  .set("Authorization", "Token DEVELOPER_TOKEN")
  .field("language", "en")
  .attach("file", "@/path/to/file.csv")
  .end((err, res) => console.log(res.text));

POST URL_PREFIX/train/v2/users/:user_id/bots/:bot_id/versions/:version_id/qna/topic/knowledge_sources

Path Parameters

Name	Type	Description
user_id	`String`	The `slug` of the user
bot_id	`String`	The `slug` of the bot
version_id	`String`	The `slug` of the version

Body Parameters

Name	Type	Description
language	`String`	The user specified language of the QnA file as isocode Allowed values: {{ISO,3166-1,alpha-2}}
file	`File`	The `file` containing the knowledge

Deleting A Knowledge Source

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -X DELETE "URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/qna/topic/knowledge_sources/$KNOWLEDGE_SOURCE_SLUG"

result = HTTParty.delete("URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/qna/topic/knowledge_sources/$KNOWLEDGE_SOURCE_SLUG",
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.delete('URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/qna/topic/knowledge_sources/$KNOWLEDGE_SOURCE_SLUG',
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

request
  .delete(`URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/qna/topic/knowledge_sources/$KNOWLEDGE_SOURCE_SLUG`)
  .send()
  .set("Authorization", "Token DEVELOPER_TOKEN")
  .end((err, res) => console.log(res.text));

DELETE URL_PREFIX/train/v2/users/:user_id/bots/:bot_id/versions/:version_id/qna/topic/knowledge_sources/:id

Path Parameters

Name	Type	Description
user_id	`String`	The `slug` of the user
bot_id	`String`	The `slug` of the bot
version_id	`String`	The `slug` of the version
id	`String`	The `slug` of the knowledge source

Downloading A Knowledge Source

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -X GET "URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/qna/topic/knowledge_sources/$KNOWLEDGE_SOURCE_SLUG/download"

require 'json'
require 'httparty'

result = HTTParty.get("URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/qna/topic/knowledge_sources/$KNOWLEDGE_SOURCE_SLUG/download",
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.get('URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/qna/topic/knowledge_sources/$KNOWLEDGE_SOURCE_SLUG/download',
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

request
  .get(`URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/qna/topic/knowledge_sources/$KNOWLEDGE_SOURCE_SLUG/download`)
  .send()
  .set("Authorization", "Token DEVELOPER_TOKEN")
  .end((err, res) => console.log(res.text));

GET URL_PREFIX/train/v2/users/:user_id/bots/:bot_id/versions/:version_id/qna/topic/knowledge_sources/:id/download

Path Parameters

Name	Type	Description
user_id	`String`	The `slug` of the user
bot_id	`String`	The `slug` of the bot
version_id	`String`	The `slug` of the version
id	`String`	The `slug` of the knowledge source

Indexing A Knowledge Source

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -X GET "URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/qna/topic/knowledge_sources"

require 'json'
require 'httparty'

result = HTTParty.get("URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/qna/topic/knowledge_sources",
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.get('URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/qna/topic/knowledge_sources',
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

request
  .get(`URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/qna/topic/knowledge_sources`)
  .send()
  .set("Authorization", "Token DEVELOPER_TOKEN")
  .end((err, res) => console.log(res.text));

GET URL_PREFIX/train/v2/users/:user_id/bots/:bot_id/versions/:version_id/qna/topic/knowledge_sources

Path Parameters

Name	Type	Description
user_id	`String`	The `slug` of the user
bot_id	`String`	The `slug` of the bot
version_id	`String`	The `slug` of the version

Query Parameters - Pagination Parameters

Name	Type	Description
page	`Integer`	optional Optional current page index Size range: 0..
per_page	`Integer`	optional Optional number of items to display per page Size range: 0..

Showing A Knowledge Source

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -X GET "URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/qna/topic/knowledge_sources/$KNOWLEDGE_SOURCE_SLUG"

require 'json'
require 'httparty'

result = HTTParty.get("URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/qna/topic/knowledge_sources/$KNOWLEDGE_SOURCE_SLUG",
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.get('URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/qna/topic/knowledge_sources/$KNOWLEDGE_SOURCE_SLUG',
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

request
  .get(`URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/qna/topic/knowledge_sources/$KNOWLEDGE_SOURCE_SLUG`)
  .send()
  .set("Authorization", "Token DEVELOPER_TOKEN")
  .end((err, res) => console.log(res.text));

GET URL_PREFIX/train/v2/users/:user_id/bots/:bot_id/versions/:version_id/qna/topic/knowledge_sources/:id

Path Parameters

Name	Type	Description
user_id	`String`	The `slug` of the user
bot_id	`String`	The `slug` of the bot
version_id	`String`	The `slug` of the version
knowledge_source_id	`String`	The `slug` of the knowledge source
id	`String`	The `slug` of the knowledge source

/Questions

This endpoint manages questions.

Creating A Question

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"value":"How do I add another question?"}' \
     -X POST "URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/qna/topic/knowledge_sources/$KNOWLEDGE_SOURCE_SLUG/answers/$ANSWER_ID/questions"

result = HTTParty.post("URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/qna/topic/knowledge_sources/$KNOWLEDGE_SOURCE_SLUG/answers/$ANSWER_ID/questions",
  body: { value: "How do I add another question?" },
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.post('URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/qna/topic/knowledge_sources/$KNOWLEDGE_SOURCE_SLUG/answers/$ANSWER_ID/questions',
  json={'value': 'How do I add another question?'},
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

const request = require('superagent');

request
  .post(`URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/qna/topic/knowledge_sources/$KNOWLEDGE_SOURCE_SLUG/answers/$ANSWER_ID/questions`)
  .send({value: "How do I add another question?"})
  .set("Authorization", "Token DEVELOPER_TOKEN")
  .end((err, res) => console.log(res.text));

POST URL_PREFIX/train/v2/users/:user_id/bots/:bot_id/versions/:version_id/qna/topic/knowledge_sources/:knowledge_source_id/answers/:answer_id/questions

Path Parameters

Name	Type	Description
user_id	`String`	The `slug` of the user
bot_id	`String`	The `slug` of the bot
version_id	`String`	The `slug` of the version
knowledge_source_id	`String`	The `slug` of the knowledge source
answer_id	`String`	The `id` of the answer

Body Parameters

{
  "value": "Another question",
  "display": false
}

Name	Type	Description
value	`String`	The text of the question
display	`Boolean`	optional Marks if the question can be used for responses to the end-user Default value: false Allowed values: true,false

Deleting A Question

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -X DELETE "URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/qna/topic/knowledge_sources/$KNOWLEDGE_SOURCE_SLUG/answers/$ANSWER_ID/questions/$QUESTION_ID"

result = HTTParty.delete("URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/qna/topic/knowledge_sources/$KNOWLEDGE_SOURCE_SLUG/answers/$ANSWER_ID/questions/$QUESTION_ID",
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.delete('URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/qna/topic/knowledge_sources/$KNOWLEDGE_SOURCE_SLUG/answers/$ANSWER_ID/questions/$QUESTION_ID',
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

request
  .delete(`URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/qna/topic/knowledge_sources/$KNOWLEDGE_SOURCE_SLUG/answers/$ANSWER_ID/questions/$QUESTION_ID`)
  .send()
  .set("Authorization", "Token DEVELOPER_TOKEN")
  .end((err, res) => console.log(res.text));

DELETE URL_PREFIX/train/v2/users/:user_id/bots/:bot_id/versions/:version_id/qna/topic/knowledge_sources/:knowledge_source_id/answers/:answer_id/questions/:id

Path Parameters

Name	Type	Description
user_id	`String`	The `slug` of the user
bot_id	`String`	The `slug` of the bot
version_id	`String`	The `slug` of the version
knowledge_source_id	`String`	The `slug` of the knowledge source
answer_id	`String`	The `id` of the answer
id	`String`	The `id` of the question

Indexing A Question

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -X GET "URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/qna/topic/knowledge_sources/$KNOWLEDGE_SOURCE_SLUG/answers/$ANSWER_ID/questions"

require 'json'
require 'httparty'

result = HTTParty.get("URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/qna/topic/knowledge_sources/$KNOWLEDGE_SOURCE_SLUG/answers/$ANSWER_ID/questions",
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.get('URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/qna/topic/knowledge_sources/$KNOWLEDGE_SOURCE_SLUG/answers/$ANSWER_ID/questions',
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

request
  .get(`URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/qna/topic/knowledge_sources/$KNOWLEDGE_SOURCE_SLUG/answers/$ANSWER_ID/questions`)
  .send()
  .set("Authorization", "Token DEVELOPER_TOKEN")
  .end((err, res) => console.log(res.text));

GET URL_PREFIX/train/v2/users/:user_id/bots/:bot_id/versions/:version_id/qna/topic/knowledge_sources/:knowledge_source_id/answers/:answer_id/questions

Path Parameters

Name	Type	Description
user_id	`String`	The `slug` of the user
bot_id	`String`	The `slug` of the bot
version_id	`String`	The `slug` of the version
knowledge_source_id	`String`	The `slug` of the knowledge source
answer_id	`String`	The `id` of the Question

Query Parameters - Pagination Parameters

Name	Type	Description
page	`Integer`	optional Optional current page index Size range: 0..
per_page	`Integer`	optional Optional number of items to display per page Size range: 0..

Updating A Question

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"value": "New question text"}' \
     -X PUT "URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/qna/topic/knowledge_sources/$KNOWLEDGE_SOURCE_SLUG/answers/$ANSWER_ID/questions/$QUESTION_ID"

result = HTTParty.put("URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/qna/topic/knowledge_sources/$KNOWLEDGE_SOURCE_SLUG/answers/$ANSWER_ID/questions/$QUESTION_ID",
  body: { value: "New question text" },
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.put('URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/qna/topic/knowledge_sources/$KNOWLEDGE_SOURCE_SLUG/answers/$ANSWER_ID/questions/$QUESTION_ID',
  json={'value': "New question text"},
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

const request = require('superagent');

request
  .put(`URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/qna/topic/knowledge_sources/$KNOWLEDGE_SOURCE_SLUG/answers/$ANSWER_ID/questions/$QUESTION_ID`)
  .send({value: "New question text"})
  .set("Authorization", "Token DEVELOPER_TOKEN")
  .end((err, res) => console.log(res.text));

PUT URL_PREFIX/train/v2/users/:user_id/bots/:bot_id/versions/:version_id/qna/topic/knowledge_sources/:knowledge_source_id/answers/:answer_id/questions/:id

Path Parameters

Name	Type	Description
user_id	`String`	The `slug` of the user
bot_id	`String`	The `slug` of the bot
version_id	`String`	The `slug` of the version
knowledge_source_id	`String`	The `slug` of the knowledge source
answer_id	`String`	The `id` of the answer
id	`String`	The `id` of the question

Body Parameters

{
  "value": "Another question",
  "display": false
}

Name	Type	Description
value	`String`	The text of the question
display	`Boolean`	optional Marks if the question can be used for responses to the end-user Default value: false Allowed values: true,false

/Requests

This endpoint manages requests.

Request Model

|            Variable           |        Type        |                                         Description                                          | Constraints |
|-------------------------------|--------------------|----------------------------------------------------------------------------------------------|-------------|
| `uuid`                        | `String`           | <p>The universally unique id for this request</p>                                                   |             |
| `source`                      | `String`           | <p>The text we processed</p>                                                                        |             |
| `disambiguations`             | `Array`            | <p>Our guess for what the text is asking.</p>                                                       |             |
| `processing_language`         | `String`           | <p>The language used to process the sentence, follows the ISO 639-1 standard</p>                    |             |
| `language` | `String` | <p>The language detected (or given) from the processed sentence, follows the ISO 639-1 standard</p> |             |
| `timestamp` | `String` | <p>The UTC timestamp at the end of our processing, follows the ISO 8601 standard</p>                |             |
| `status`                      | `Integer`          | <p>The status of our Natural Language processor</p>                                                 |             |
| `faq`                         | `Object`           | <p>The FAQ results we have found</p>                                                                |             |
| `faq.max_confidence`          | `Float`            | <p>The highest confidence from the set of answer we have found</p>                                  |             |
| `faq.min_confidence`          | `Float`            | <p>The lowest confidence from the set of answer we have found</p>                                   |             |
| `faq.answers`                 | `Array` of Answers | <p>The answers we have found</p>                                                                    |             |
| `faq.answers.question`        | `String`           | <p>The question text that belongs to this answer</p>                                                |             |
| `faq.answers.answer`          | `String`           | <p>The answer text</p>                                                                              |             |
| `faq.answers.answer`          | `Float`            | <p>The confidence of the system in this answer</p>                                                  |             |
| `faq.answers.document_source` | `String`           | <p>The slug of the knowledge source the answer originates from</p>    

### Asking A Question

```shell
curl -H "Authorization: Token REQUEST_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"text":"What's the meaning of life?", "language":"en"}' \
     -X POST "URL_PREFIX/train/v2/request/ask"

result = HTTParty.post("URL_PREFIX/train/v2/request/ask",
  body: { text: "What's the meaning of life?" },
  headers: { 'Authorization' => 'Token REQUEST_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.post('URL_PREFIX/train/v2/request/ask',
  json={'text': 'What\'s the meaning of life?'},
  headers={'Authorization': 'Token REQUEST_TOKEN'}
)

const request = require('superagent');

request
  .post(`URL_PREFIX/train/v2/request/ask`)
  .send({text: "What's the meaning of life?"})
  .set('Authorization', 'Token REQUEST_TOKEN')
  .end((err, res) => console.log(res.text));

Body Parameters

{
  "text": "How do I use the API?,
  "number_of_answers": 1,
  "language": "en"
}

Name	Type	Description
text	`String`	The `text` representing the question
language	`String`	The language of the current conversation as isocode Allowed values: {{LANGUAGE-ISOCODE}}
number_of_answers	`Integer`	optional The number of answers to retrieve for the question Default value: 3 Size range: 1..
fallback_language	`String`	optional The language to use as a fallback in case the expected language is not supported Allowed values: {{LANGUAGE-ISOCODE}}
output_format	`String`	optional The type of the response format Default value: simple Allowed values: simple,extended

/Topic

This endpoint manages topics.

Topic Model

Variable	Type	Description
`id`	`UUID`	A unique topic ID
`name`	`String`	The topic name
`slug`	`String`	The topic slug
`description`	`String`	A short description of the topic
`language`	`Language`	The language of the topic
`custom_normalizations`	`JSON`	A JSON dictionary of word normalizations
`knowledge_sources`	`Array`	An array of knowledge sources available in the topic

Showing A Topic

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -X GET "URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/qna/topic"

require 'json'
require 'httparty'

result = HTTParty.get("URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/qna/topic",
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.get('URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/qna/topic',
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

request
  .get(`URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/qna/topic`)
  .send()
  .set("Authorization", "Token DEVELOPER_TOKEN")
  .end((err, res) => console.log(res.text));

GET URL_PREFIX/train/v2/users/:user_id/bots/:bot_id/versions/:version_id/qna/topic/

Path Parameters

Name	Type	Description
user_id	`String`	The `slug` of the user
bot_id	`String`	The `slug` of the bot
version_id	`String`	The `slug` of the version

Updating A Topic

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"en": {"term1": ["synonym for term1", "another synonym"]}}' \
     -X PUT "URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/qna/topic"

result = HTTParty.put("URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/qna/topic",
  body: {
    custom_normalizations: {
      en: {
        term1: ["synonym for term1", "another synonym"]
      }
    }
  },
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.put('URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/qna/topic',
  json={
    'custom_normalizations': {
      'en': {
        'term1': ['synonym for term1', 'another synonym']
      }
    }
  },
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

const request = require('superagent');

request
  .put(`URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/qna/topic`)
  .send({
    custom_normalizations: {
      en: {
        term1: ["synonym for term1", "another synonym"]
      }
    }
  })
  .set("Authorization", "Token DEVELOPER_TOKEN")
  .end((err, res) => console.log(res.text));

PUT URL_PREFIX/train/v2/users/:user_id/bots/:bot_id/versions/:version_id/qna/topic

Path Parameters

Name	Type	Description
user_id	`String`	The `slug` of the user
bot_id	`String`	The `slug` of the bot
version_id	`String`	The `slug` of the version

Body Parameters

{
  "custom_normalizations": {
    "en": {
      "term1": ["synonym for term1", "another synonym"],
    },
    "fr": {
      "term1": ["synonym for term1"]
    }
  }
}

Name	Type	Description
custom_normalizations	`String`	Custom normalizations dictionary

Indexing trainings

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -X GET "URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/qna/topic/trainings"

require 'json'
require 'httparty'

result = HTTParty.get("URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/qna/topic/trainings",
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.get('URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/qna/topic/trainings',
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

request
  .get(`URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/qna/topic/trainings`)
  .send()
  .set("Authorization", "Token DEVELOPER_TOKEN")
  .end((err, res) => console.log(res.text));
``

<span class="label label-get">GET</span> `URL_PREFIX/train/v2/users/:user_id/bots/:bot_id/versions/:version_id/qna/topic/trainings`

#### Path Parameters
| Name     | Type       | Description                           |
|:---------|:-----------|:--------------------------------------|
| user_id | `String` | <p>The <code>slug</code> of the user</p> |
| bot_id | `String` | <p>The <code>slug</code> of the bot</p> |
| version_id | `String` | <p>The <code>slug</code> of the version</p> |
#### Query Parameters - Pagination Parameters
| Name     | Type       | Description                           |
|:---------|:-----------|:--------------------------------------|
| page | `Integer` | **optional**<p>Optional current page index</p>_Size range: 0.._<br> |
| per_page | `Integer` | **optional**<p>Optional number of items to display per page</p>_Size range: 0.._<br> |

Glossary

Sentence acts

We currently detect 4 acts of a sentence, as defined in the section 8.7 of Natural Language Understanding, 1995, James Allen. Those 4 categories are defined as surface speech acts, which indicate how the proposition described is intended to be used to update the discourse situation.

Type	Examples	Description
`assert`	The man ate a peach.	The proposition is being asserted
`command`	Eat a peach.	The proposition describes an action to perform
`wh-query`	What did the man eat?	The proposition describes an object to be identified
`yn-query`	Did the man eat a peach?	The proposition is being queried

Sentence types

The type of a sentence comes from the task of question classification in the domain of Question Answering Systems. Detecting the type of a question helps you define what the answer to your user’s request needs to be. Below are the exhaustive list of classes we detect, their description, and an example of sentence each type.

Class	Subclass	Description	Example
ABBR	abb	abbreviation	What is the acronym for the Federal Bureau of Investigation?
	exp	expression abbreviated	What does BMW stands for?
DESC	def	definition of something	Define the cosmology.
	desc	description of something	What are the differences between 1980 and 1990?
	manner	manner of an action	How can I find a list of celebrities?
	reason	reasons	Explain why she said you were late.
ENTY	animal	animals	A corgi is a kind of what?
	body	organs of body	What is the longest bone in the human body?
	color	colors	What color are crickets?
	cremat	inventions, books and other creative pieces	In which films acted Jude Law?
	currency	currency names	What money do Italians use?
	dis.med.	diseases and medicine	What are the 10 plagues of Egypt?
	event	events	In what war was the first submarine used?
	food	food	What are the top vegetable crops in the world?
	instru	musical instrument	What kind of trumpet is the loudest?
	lang	languages	Name a Gaelic language.
	letter	letters like a-z	Name a consonant.
	other	other entities	To what does Microsoft’s Windows 3 owe its success?
	plant	plants	What is the state tree of Nebraska?
	product	products	Germany is the largest productor of what?
	religion	religions	A cardinal is a rank among which religion?
	sport	sports	Garry kasparov played what game?
	substance	elements and substances	What are cigarettes made of?
	symbol	symbols and signs	How are named the signs done in crops?
	techmeth	techniques and methods	What are common methods used to regulate monopolies?
	termeq	equivalent terms	What was another name for East Germany?
	veh	vehicles	Name a French car.
	word	words with a special property	Give a synonym for “alphabet”.
HUM	desc	description of a person	Can you tell me who she is?
	gr	a group or organization of persons	How are called the employes of Google?
	ind	an individual	CNN is owned by whom?
	title	title of a person	What is her profession?
LOC	city	cities	Give me the name of Paraguay’s capital.
	country	countries	In which state would you find the Catskill Mountains?
	mount	mountains	What is the name of the highest peak of Africa?
	other	other locations	Name a civil war battlefield.
NUM	code	postcodes or other codes	Give me the country code of France.
	count	number of something	About how many soldiers died in World War II?
	date	dates	CNN began broadcasting in what year?
	dist	linear measures	What is the wingspan of a condor?
	money	prices	How much do drugs to treat tuberculosis cost?
	ord	ranks	Tell me my final ranking!
	other	other numbers	How loud is thunder?
	period	the lasting time of something	For how long is an elephant pregnant?
	perc	fractions	At what percentage are you right now?
	speed	speed	How fast can cheetahs run?
	temp	temperature	What is the temperature at the center of the earth?
	volsize	size, area and volume	What is the size of Argentina?
	weight	weight	How much did a knight’s armor weigh?

Sentence sentiments

Sentiment detection is an important part of analyzing an user’s input. We decided to follow guidelines suggesting a higher granularity of sentiments that you may be used to. This allows you to treat different levels of positive, and negative inputs .

Polarity	Examples
`vpositive`	That was awesome to see that man eat a peach.
`positive`	The man ate a peach.
`neutral`	peach.
`negative`	Sadly, the man did not eat a peach.
`vnegative`	That was awful to see this man ate a peach.

List of Entities

This is the list of the current entities we detect, with examples and formatted information for each one. Keep an eye on it, we are always improving detection for current entities, adding new entities or improving the information we extract from them.

Cardinal

{
  "bearing": 45.0,
  "raw": "northeast",
  "confidence": 0.99
}

Entity	Examples
`cardinal`	north, southeast, north-west, south south east
Key	Comments
`bearing`	Float, the cardinal point bearing in degrees
`raw`	The raw value extracted from the sentence
`confidence`	The confidence score between 0 and 1 for the detection

Color

{
  "rgb": "rgb(0,0,255)",
  "hex": "#0000ff",
  "raw": "blue",
  "confidence": 0.99
}

Entity	Examples
`color`	blue, red, orange, dark blue, light green
Key	Comments
`rgb`	String, the rgb code of the color
`hex`	String, the hexadecimal value of the color
`raw`	The raw value extracted from the sentence
`confidence`	The confidence score between 0 and 1 for the detection

Datetime

{
  "formatted": "Thursday, 06 October 2016 at 09:00:00 AM",
  "iso": "2016-10-06T09:00:00Z",
  "accuracy": "day",
  "chronology": "future",
  "state": "relative",
  "raw": "next Thursday",
  "confidence": 0.92
}

Entity	Examples
`datetime`	the next friday, today, September 7 2016, 12/12/1992, this evening, mid-november, eoy
Key	Comments
`formatted`	String, the written format of the datetime
`iso`	String, the ISO-8601 standard of the datetime in UTC
`accuracy`	String, the accuracy of the explicitly given datetime
	Can be composed of one or more of `year`, `month`, `week`, `day`, `halfday`, `hour`, `min`, `sec`, `now` separated by a comma (`,`)
`chronology`	String, the point in time referenced by the datetime
	Can be `past`, `present`, or `future`
`state`	String, the type of the datetime
	Can be `relative`, or `absolute`
`raw`	The raw value extracted from the sentence
`confidence`	The confidence score between 0 and 1 for the detection

Distance

{
  "scalar": 24.0,
  "unit": "mi",
  "meters": 38624.159999999996,
  "raw": "twenty-four miles",
  "confidence": 0.97
}

Entity	Examples
`distance`	20 meters, seven miles, ten kms, 156 centimeters, .8 foot
Key	Comments
`scalar`	Float, the countable
`unit`	String, the quantifier
	Can be `km` (kilometers), `m` (meters), `mi` (miles), `ft` (feet), `in` (inches), etc.
`meters`	Float, the distance in meters
`raw`	The raw value extracted from the sentence
`confidence`	The confidence score between 0 and 1 for the detection

Duration

{
  "chrono": "02:00:00:00",
  "years": 0.005478757133798352,
  "months": 0.06575342465753424,
  "days": 2.0,
  "hours": 48.0,
  "minutes": 2880.0,
  "seconds": 172800.0,
  "raw": "two days",
  "confidence": 0.99
}

Entity	Examples
`duration`	five days, one year, 27 seconds, two days and 3 hours, 72 weeks
Key	Comments
`chrono`	String, a formatted representation of the duration in the form of `:xx:xx:`
`years`	Float, the number of years in this duration
`months`	Float, the number of months in this duration
`days`	Float, the number of days in this duration
`hours`	Float, the number of hours in this duration
`minutes`	Float, the number of minutes in this duration
`seconds`	Float, the number of seconds in this duration
`raw`	The raw value extracted from the sentence
`confidence`	The confidence score between 0 and 1 for the detection

Email

{
  "local": "paul",
  "tag": null,
  "domain": "sap.com",
  "raw": "paul@sap.com",
  "confidence": 0.99
}

Entity	Examples
`email`	helloconversationalai@sap.com
Key	Comments
`local`	String, the local part of the email
`tag`	String, the tag part of the email
`domain`	String, the domain of the email
`raw`	The raw value extracted from the sentence
`confidence`	The confidence score between 0 and 1 for the detection

Emoji

{
    "formatted": "happy",
    "feeling": "happy",
    "tags": [
        "eye",
        "face",
        "mouth",
        "open",
        "smile"
    ],
    "unicode": "U+1F604",
    "description": "smiling face with open mouth & smiling eyes",
    "raw": ":)",
    "confidence": 0.99
}

Entity	Examples
`emoji`	:), :heart:, 🙂
Key	Comments
`formatted`	String, the localized feeling of the emoji
`feeling`	String, the expressed sentiment of the emoji
`tags`	Array of String, a list of word related to the emoji
`unicode`	String, the unicode codepoint of the emoji
`description`	String, a fully-written sentence describing the emoji
`raw`	The raw value extracted from the sentence
`confidence`	The confidence score between 0 and 1 for the detection

IP

{
  "formatted": "Fontenay-sous-Bois, Île-de-France, FR",
  "lat": 48.8544,
  "lng": 2.4827,
  "raw": "82.121.114.213",
  "confidence": 0.99
}

Entity	Examples
`ip`	127.0.0.1, 192.157.0.54, 153.34.43.0
Key	Comments
`formatted`	String, the full denomination of the ip’s location
`lat`	Float, the latitude of the ip’s location
`lng`	Float, the longitude of the ip’s location
`raw`	The raw value extracted from the sentence
`confidence`	The confidence score between 0 and 1 for the detection

Interval

{
  "begin": "2016-10-31T09:00:00Z",
  "end": "2016-11-06T09:00:00Z",
  "begin_accuracy": "day",
  "end_accuracy": "day",
  "begin_chronology": "future",
  "end_chronology": "future",
  "timespan": 518400.0,
  "raw": "from monday to sunday",
  "confidence": 0.96
}

Entity	Examples
`interval`	between today and tomorrow, from now to next week, wednesday the 3rd between 2pm and 3pm, starting sunday ending monday
Key	Comments
`begin`	String, the ISO-8601 standard of the start point in UTC
`end`	String, the ISO-8601 standard of the end point in UTC
`begin_chronology`	String, comma separated points in time referenced by the begin field
	Can be `past`, `present`, or `future`
`end_chronology`	String, comma separated points in time referenced by the end field
	Can be `past`, `present`, or `future`
`begin_accuracy`	String, the accuracy of the explicitly given begin datetime
	Can be composed of one or more of `year`, `month`, `week`, `day`, `halfday`, `hour`, `min`, `sec`, `now` separated by a comma (`,`)
`end_accuracy`	String, the accuracy of the explicitly given end datetime
	Can be composed of one or more of `year`, `month`, `week`, `day`, `halfday`, `hour`, `min`, `sec`, `now` separated by a comma (`,`)
`timespan`	Float, the duration of the interval
`raw`	The raw value extracted from the sentence
`confidence`	The confidence score between 0 and 1 for the detection

Job

{
    "raw": "web designer",
  "confidence": 0.85
}

Entity	Examples
`job`	CTO, farmer, financial accoutant, chief operator, actress
Key	Comments
`raw`	The raw value extracted from the sentence
`confidence`	The confidence score between 0 and 1 for the detection

Language

{
  "short": "NL",
  "long": "NLD",
  "raw": "Dutch",
  "confidence": 0.76
}

Entity	Examples
`language`	French, Hindi, Russian,
Key	Comments
`short`	String, the ISO 639-1 standard language code
`long`	String, the ISO 639-2 standard language code
`raw`	The raw value extracted from the sentence
`confidence`	The confidence score between 0 and 1 for the detection

Location

{
  "formatted": "3410 Hillview Avenue, Palo Alto, CA 94304, United States",
  "lat": 37.399169,
  "lng": -122.146475,
  "type": "establishment",
  "place": "ChIJEyiYgJ66j4ARVZ9bxK83pSQ",
  "street_number": "3410",
  "street_name": "Hillview Avenue",
  "postal_code": "94304",
  "city": "Palo Alto",
  "state": "CA",
  "country": "us",
  "raw": "3410 hillview avenue",
  "confidence": 0.99  
}

Entity	Examples
`location`	San Francisco, Paris, East London, 123 Abbey Road
Key	Comments
`formatted`	String, the full denomination of the location
`lat`	Float, the latitude of the location
`lng`	Float, the longitude of the location
`type`	Float, the precision type of the location
	Can be one of `country`, `locality`, `sublocality`, `postal_code`, `route`, `intersection`, `political`, `neighborhood`, `premise`, `airport`, `park`, …
`place`	String, the Google Places ID of the location
`street_number`	String, the street number of the location
`street_name`	String, the street name of the location
`postal_code`	String, the ZIP or postal code of the location
`city`	String, the city of the location
`state`	String, the state or province of the location
`country`	String, the ISO 3166-2 code for the country in which the location is
`raw`	The raw value extracted from the sentence
`confidence`	The confidence score between 0 and 1 for the detection

Mass

{
  "value": 28.0,
  "unit": "lbs",
  "grams": 12700.576,
  "raw": "28 lbs",
  "confidence": 0.99
}

Entity	Examples
`mass`	45 pounds, twenty-one grams, thirty seven kgs, 0.98 mg, 23 kilograms
Key	Comments
`scalar`	Float, the countable
`unit`	String, the quantifier
	Can be `lbs` (pounds), `kg` (kilograms), `g` (grams), `oz` (ounces), etc.
`grams`	Float, the mass in grams
`raw`	The raw value extracted from the sentence
`confidence`	The confidence score between 0 and 1 for the detection

Money

{
  "amount": 16.0,
  "currency": "EUR",
  "dollars": 17.92,
  "raw": "sixteen euros",
  "confidence": 0.98
}

Entity	Examples
`money`	3.14 euros, eight millions dollars, $6, 56 ₩, seventy-eight zlotys
Key	Comments
`amount`	Float, the countable
`currency`	String, the ISO 4217 standard currency code
`dollars`	Float, the amount of money in dollars
`raw`	The raw value extracted from the sentence
`confidence`	The confidence score between 0 and 1 for the detection

Nationality

{
  "short": "PT",
  "long": "PRT",
  "country": "Portugal",
  "raw": "Portuguese",
  "confidence": 0.97
}

Entity	Examples
`nationality`	French, Spanish, Australian
Key	Comments
`short`	String, the ISO 3166-1 alpha2 standard country code
`long`	String, the ISO 3166-1 alpha3 standard country code
`country`	String, the name of the country for which the nationality refers to
`raw`	The raw value extracted from the sentence
`confidence`	The confidence score between 0 and 1 for the detection

Number

{
  "scalar": 27000,
  "raw": "twenty-seven thousand",
  "confidence": 0.83
}

Entity	Examples
`number`	one thousand, 3, 9,000, seven million
Key	Comments
`scalar`	Integer, the number
`raw`	The raw value extracted from the sentence
`confidence`	The confidence score between 0 and 1 for the detection

Ordinal

{
  "rank": -1,
  "raw": "last",
  "confidence": 0.98
}

Entity	Examples
`ordinal`	3rd, 158th, last, seventh
Key	Comments
`rank`	Integer, the number behind the ordinal
`raw`	The raw value extracted from the sentence
`confidence`	The confidence score between 0 and 1 for the detection

Organization

{
  "raw": "Apple",
  "confidence": 0.99
}

Entity	Examples
`organization`	Lehman Brothers, NASA, Apple
Key	Comments
`raw`	The raw value extracted from the sentence
`confidence`	The confidence score between 0 and 1 for the detection

Percent

{
  "scalar": 86.0,
  "unit": "%",
  "percent": 86.0,
  "raw": "86 percent",
  "confidence": 0.99
}

Entity	Examples
`percent`	99%, 2 percent, seventy-seven percents, 12 permyriad
Key	Comments
`scalar`	Float, the countable
`unit`	String, the quantifier
	Can be `%` (percent), `‰` (permil), `‱` (permyriad), `ppb` (part per billion), etc.
`raw`	The raw value extracted from the sentence
`confidence`	The confidence score between 0 and 1 for the detection

Person

{
  "fullname": "Dave Pitterson",
  "raw": "Dave Pitterson",
  "confidence": 0.97
}

Entity	Examples
`person`	John Smith, David H. Doe, Dave
Key	Comments
`fullname`	String, the full name of the person
`raw`	The raw value extracted from the sentence
`confidence`	The confidence score between 0 and 1 for the detection

Phone

{
  "number": "3612374040",
  "raw": "(361) 237 4040",
  "confidence": 0.88
}

Entity	Examples
`phone`	+91-22-265 9000, 64 4 437-4746, 0682753582, (123) 123 1234
Key	Comments
`number`	String, the normalized phone extracted
`raw`	The raw value extracted from the sentence
`confidence`	The confidence score between 0 and 1 for the detection

Pronoun

{
  "person": 1,
  "number": "singular",
  "gender": "unkown",
  "raw": "I",
  "confidence": 0.99
}

Entity	Examples
`pronoun`	I, we, it, you, us
Key	Comments
`person`	Integer, the person of the pronoun
	Can be 1, 2 or 3
`number`	String, the number of the pronoun
	Can be singular or plural
`gender`	String, the gender of the pronoun
	Can be unknown, neutral, male of female
`raw`	The raw value extracted from the sentence
`confidence`	The confidence score between 0 and 1 for the detection

Set

{
  "next": "2016-12-02T18:18:02Z",
  "frequency": "monthly",
  "interval": 2,
  "rrule": "RRULE:FREQ=MONTHLY;INTERVAL=2",
  "raw": "every two months",
  "confidence": 0.99
}

Entity	Examples
`set`	every Sunday, each day, monthly, every 2 weeks
Key	Comments
`next`	String, the ISO-8601 representation of the next occurence in UTC
`frequencey`	String, the frequency this event is repeating
	Can be `yearly`, `monthly`, `weekly`, `daily`, `hourly`, `minutely`, `secondly`
`interval`	Integer, the interval between two occurences relative to the frequency
`rrule`	String, the RFC 5545 compliant recurence rule
`raw`	The raw value extracted from the sentence
`confidence`	The confidence score between 0 and 1 for the detection

Sort

{
  "order": "DESC",
  "criterion": "expensive",
  "raw": "least expensive",
  "confidence": 0.96
}

Entity	Examples
`sort`	most valuable, best, least affordable, cheapest
Key	Comments
`order`	String, the order to sort (MySQL inspired)
`criterion`	String, the criterion to sort
`raw`	The raw value extracted from the sentence
`confidence`	The confidence score between 0 and 1 for the detection

Speed

{
  "scalar": 37.0,
  "unit": "km/h",
  "mps": 10.277777777777779,
  "raw": "thirty-seven kilometers per hour",
  "confidence": 0.57
}

Entity	Examples
`speed`	7 mph, 10 km/h, seven meters per second
Key	Comments
`scalar`	Float, the countable
`unit`	String, the quantifier
	Can be `km/h` (kilometer per hour), `mi/s` (miles per second), `kt` (knots), etc.
`mps`	Float, the speed in meters per second
`raw`	The raw value extracted from the sentence
`confidence`	The confidence score between 0 and 1 for the detection

Temperature

{
  "scalar": 9.0,
  "unit": "F",
  "celsius": -12.777777777777777,
  "raw": "9 degree Farhenheit",
  "confidence": 0.97
}

Entity	Examples
`temperature`	25 degrees Celcius, 70° F, seven degC, 5 rankines
Key	Comments
`scalar`	Float, the countable
`unit`	String, the quantifier
	Can be `C` (Celsius), `K` (Kelvin), `F` (Fahrenheit), `R` (Rankine), etc.
`celsius`	Float, the temperature in celsius
`raw`	The raw value extracted from the sentence
`confidence`	The confidence score between 0 and 1 for the detection

Url

{
  "scheme": "https",
  "host": "pokebot.cai.tools.sap",
  "path": "/register",
  "params": null,
  "query": null,
  "fragment": null,
  "raw": "https://pokebot.cai.tools.sap/register",
  "confidence": 0.99
}

Entity	Examples
`url`	https://cai.tools.sap, localhost:9000, api.cai.tools.sap/v2/request
Key	Comments
`scheme`	String, the URL scheme
	Can be `http`, `https`, `mailto`, `ssh`, `git`, etc.
`host`	String, the host of the URL
`path`	String, the URL path
`params`	String, the parameters of the URL
`query`	String, the query parameters of the URL
`fragment`	String, the anchor of the URL
`raw`	The raw value extracted from the sentence
`confidence`	The confidence score between 0 and 1 for the detection

Volume

{
  "scalar": 90.0,
  "unit": "hl",
  "liters": 9000.0,
  "raw": "90 hectoliters",
  "confidence": 0.96
}

Entity	Examples
`volume`	30 liters, two barrels, ½ tbsp
Key	Comments
`scalar`	Float, the countable
`unit`	String, the quantifier
	Can be `l` (liters), `tsp` (teaspoons), `pt` (pints), etc.
`liters`	Float, the volume in liters
`raw`	The raw value extracted from the sentence
`confidence`	The confidence score between 0 and 1 for the detection

Deprecated APIs and Other API Changes

Deprecated APIs

API Name
SDKs`

Description
As of January 2021, please note that the SDKs will not be available anymore and the public repository of the project will be archived from GitHub. For more information, please see the README of each SDK.

Date of Deprecation
2101 release

API Name
Endpoint /gazettes

Description
As of 2008 release, the endpoint that manages gazettes (/gazettes) will be removed. Use the endpoint /entities to carry out all the actions associated with /gazettes. In the entities JSON the key gazettes will be replaced by entities.

Date of Deprecation
2008 release

API Name
All routes starting with /v2 that are not prefaced with /train

Description
As of 1911 release, all routes starting with /v2 that are not prefaced with /train cannot be used. Please use /train/v2 instead. For example, URL_PREFIX/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/bulk_creations

Date of Deprecation
1911 release

API Names
/Request (Text) and /Dialog (Text)

Description
As of April 2020 release, act and type detection will not longer be supported for the following API’s:

URL_PREFIX/train/v2/request

URL_PREFIX/build/v1/dialog

Date of Deprecation
April 2020 release

API Name
Indexing Global Entities

Description
This route is deprecated. It will be removed from January 2020. Entities used to be global, but now belong to bots. URL_PREFIX/train/v2/entities

Date of Deprecation
1912 release

API Name
Creating A Global Entity

Description
This route is deprecated. It will be removed from January 2020. Entities used to be global, but now belong to bots. URL_PREFIX/train/v2/entities

Date of Deprecation
1912 release

Other API Changes

Other Changes
Version one (v1) of the Builder

Description
As of December 2019 release, version one of the builder (Builder v1) is no more available. All bots using builder v1 are deleted from the SAP Conversational AI platform.

Date of Deprecation
1912 release

Changelogs

For information about new features and changes for each release of SAP Conversational AI, see What’s New for SAP Conversational AI.