Introduction

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 Recast 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. If you are using the versioning feature (you can enable it in the settings of your bot) you will have one request token by version and by environment.

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.

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

Recast.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	`3.1.0`	Github - Pypi
NodeJS	`3.3.0`	Github - NPM
Ruby	`3.1.0`	Github - Rubygems
PHP	`3.1.0`	Github - Packagist
Golang	`3.2.0`	Github - GoDoc
Android	`4.1.0`	Github - Bintray
Swift	`4.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 Recast", "language":"en"}' \
     -X POST "https://api.recast.ai/train/v2/request"

require 'recastai'

request = RecastAI::Request.new(REQUEST_TOKEN, 'en')
response = request.analyse_text('Hello Recast')

puts response.raw

import recastai

request = recastai.Request(REQUEST_TOKEN, 'en')
response = request.analyse_text('Hello Recast')

print(response.raw)

var recastai = require('recastai').default

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

request.analyseText('Hello Recast')
  .then(function(res) {
    console.log(res.raw)
  })

Text request works with any raw text.

POST https://api.recast.ai/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",
          "lng": -0.1277583,
          "lat": 51.5073509,
          "type": "locality",
          "place": "ChIJdd4hrwug2EcRmSrV3Vo6llI",
          "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 8061 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 "https://api.recast.ai/train/v2/request"

require 'recastai'

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

puts response.raw

import recastai

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

print(response.raw)

var request = new recastai.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 https://api.recast.ai/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",
          "lng": -0.1277583,
          "lat": 51.5073509,
          "type": "locality",
          "place": "ChIJdd4hrwug2EcRmSrV3Vo6llI",
          "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 8061 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 Recast","type":"text"}, "conversation_id": "CONVERSATION_ID"}' \
     -X POST "https://api.recast.ai/build/v1/dialog"

require 'recastai'

build = RecastAI::Build.new(REQUEST_TOKEN, 'en')
response = build.dialog({ type: 'text', content: 'Hello Recast' }, "CONVERSATION_ID")

puts response

import recastai

build = recastai.Build(REQUEST_TOKEN, 'en')
response = build.dialog({'type': 'text', 'content': 'Hello Recast'}, 'CONVERSATION_ID')

print(response)

var recastai = require('recastai').default

var build = new recastai.build('YOUR_TOKEN', 'en')

build.dialog({ type: 'text', content: 'Hello Recast'}, { conversationId: 'CONVERSATION_ID' })
  .then(function(res) {
    console.log(res)
  })

POST https://api.recast.ai/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 Recast",
        "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`	`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 8061 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`	Is the bot has private data?
`public`	`Boolean`	Is the bot public?
`is_privatisable`	`Boolean`	Is the bot privatisable?
`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 "https://api.recast.ai/auth/v1/users/$USER_SLUG/bots/$BOT_SLUG"

require 'json'
require 'httparty'

result = HTTParty.get("https://api.recast.ai/auth/v1/users/$USER_SLUG/bots/$BOT_SLUG",
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)

import requests

response = requests.get('https://api.recast.ai/auth/v1/users/$USER_SLUG/bots/$BOT_SLUG',
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

request
  .get(`https://api.recast.ai/auth/v1/users/${USER_SLUG}/bots/${BOT_SLUG}`)
  .send()
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end((err, res) => console.log(res.text));

GET https://api.recast.ai/auth/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 "https://api.recast.ai/auth/v1/users/$USER_SLUG/bots/$BOT_SLUG"

require 'json'
require 'httparty'

result = HTTParty.put("https://api.recast.ai/auth/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('https://api.recast.ai/auth/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(`https://api.recast.ai/auth/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 https://api.recast.ai/auth/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`	An 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 "https://api.recast.ai/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset"

require 'json'
require 'httparty'

result = HTTParty.get("https://api.recast.ai/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('https://api.recast.ai/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(`https://api.recast.ai/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 https://api.recast.ai/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://api.recast.ai/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset"

require 'json'
require 'httparty'

result = HTTParty.put("https://api.recast.ai/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('https://api.recast.ai/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(`https://api.recast.ai/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 https://api.recast.ai/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 "https://api.recast.ai/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/entities"

require 'json'
require 'httparty'

result = HTTParty.get("https://api.recast.ai/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('https://api.recast.ai/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(`https://api.recast.ai/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 https://api.recast.ai/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

/trainings

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

This endpoint manages trainings.

Training model

Variable	Type	Description
`enqueued_at`	`DateTime`	The time at which the training was scheduled
`started_at`	`DateTime`	The time at which the training was started
`status`	`String`	The training status
`language`	`Language`	The training language

Indexing trainings

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -X GET "https://api.recast.ai/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/trainings"

require 'json'
require 'httparty'

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

puts JSON.parse(result.body)

import requests

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

print(response.text)

const request = require('superagent');

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

GET https://api.recast.ai/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/trainings

This call returns an array of training 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 languages’ isocodes	Optional, valid isocode

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

/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 "https://api.recast.ai/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/bulk_creations"

require 'json'
require 'httparty'

result = HTTParty.get("https://api.recast.ai/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('https://api.recast.ai/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(`https://api.recast.ai/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 https://api.recast.ai/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 languages’ isocodes	Optional, valid isocode

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`	An 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`	An 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 "https://api.recast.ai/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/intents"

require 'json'
require 'httparty'

result = HTTParty.get("https://api.recast.ai/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('https://api.recast.ai/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(`https://api.recast.ai/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 https://api.recast.ai/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 "https://api.recast.ai/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/intents/$INTENT_SLUG"

require 'json'
require 'httparty'

result = HTTParty.get("https://api.recast.ai/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('https://api.recast.ai/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(`https://api.recast.ai/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 https://api.recast.ai/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 "https://api.recast.ai/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/intents"

require 'json'
require 'httparty'

result = HTTParty.post("https://api.recast.ai/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('https://api.recast.ai/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(`https://api.recast.ai/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 https://api.recast.ai/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 15 000 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 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 "https://api.recast.ai/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/intents/$INTENT_SLUG"

require 'json'
require 'httparty'

result = HTTParty.put("https://api.recast.ai/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('https://api.recast.ai/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(`https://api.recast.ai/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 https://api.recast.ai/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 "https://api.recast.ai/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/intents/$INTENT_SLUG"

require 'json'
require 'httparty'

result = HTTParty.delete("https://api.recast.ai/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('https://api.recast.ai/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(`https://api.recast.ai/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 https://api.recast.ai/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/intents/$INTENT_SLUG

This call does not 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 "https://api.recast.ai/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/intents/$INTENT_SLUG/entities"

require 'json'
require 'httparty'

result = HTTParty.get("https://api.recast.ai/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('https://api.recast.ai/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(`https://api.recast.ai/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 https://api.recast.ai/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`	An 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`	An unique expression id
`source`	`String`	The expression source
`language`	`Language`	The expression language

Indexing expressions

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

require 'json'
require 'httparty'

result = HTTParty.get("https://api.recast.ai/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('https://api.recast.ai/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(`https://api.recast.ai/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 https://api.recast.ai/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 languages’ isocodes	Optional, valid isocode

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 "https://api.recast.ai/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("https://api.recast.ai/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('https://api.recast.ai/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(`https://api.recast.ai/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 https://api.recast.ai/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 "https://api.recast.ai/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/intents/$INTENT_SLUG/expressions"

require 'json'
require 'httparty'

result = HTTParty.post("https://api.recast.ai/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('https://api.recast.ai/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(`https://api.recast.ai/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 https://api.recast.ai/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 "https://api.recast.ai/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("https://api.recast.ai/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('https://api.recast.ai/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(`https://api.recast.ai/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 https://api.recast.ai/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 "https://api.recast.ai/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("https://api.recast.ai/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('https://api.recast.ai/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(`https://api.recast.ai/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 https://api.recast.ai/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

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 "https://api.recast.ai/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("https://api.recast.ai/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('https://api.recast.ai/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(`https://api.recast.ai/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 https://api.recast.ai/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/intents/$INTENT_SLUG/expressions/$EXPRESSION_ID

This call does not 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`	An unique token id
`space`	`Boolean`	Is the token followed by a space?
`word`	`Word`	The token word
`entity`	`Entity`	The token entity

/words

{
  "id": 1,
  "name": "Paris",
  "slug": "paris"
}

This endpoint manages words.

Word model

Variable	Type	Description
`id`	`Integer`	An unique word id
`name`	`String`	The word name
`slug`	`String`	The word slug

/entities

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

This endpoint manages entities.

Entity model

Variable	Type	Description
`id`	`Integer`	An 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 "https://api.recast.ai/train/v2/entities"

require 'json'
require 'httparty'

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

puts JSON.parse(result.body)

import requests

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

print(response.text)

const request = require('superagent');

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

GET https://api.recast.ai/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 an entity

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

require 'json'
require 'httparty'

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

puts JSON.parse(result.body)

import requests

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

print(response.text)

const request = require('superagent');

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

POST https://api.recast.ai/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 endpoints manages logs.

Log model

Variable	Type	Description	Constraints
`id`	`Integer`	An 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`	An 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 "https://api.recast.ai/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/logs"

require 'json'
require 'httparty'

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

puts JSON.parse(result.body)

import requests

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

print(response.text)

const request = require('superagent');

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

GET https://api.recast.ai/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 languages isocodes
`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 did not matched 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 "https://api.recast.ai/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/logs/$LOG_ID"

require 'json'
require 'httparty'

result = HTTParty.get("https://api.recast.ai/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('https://api.recast.ai/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(`https://api.recast.ai/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 https://api.recast.ai/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/logs/$LOG_ID

This call returns an log model in results variable.

Deleting a log

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -X DELETE "https://api.recast.ai/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/logs/$LOG_ID"

require 'json'
require 'httparty'

result = HTTParty.delete("https://api.recast.ai/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('https://api.recast.ai/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(`https://api.recast.ai/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 https://api.recast.ai/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/logs/$LOG_ID

This call does not 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 "https://api.recast.ai/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/logs/bulk_destroy"

require 'json'
require 'httparty'

result = HTTParty.post("https://api.recast.ai/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('https://api.recast.ai/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(`https://api.recast.ai/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 https://api.recast.ai/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/logs/bulk_destroy

This call does not 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 endpoints manages gazettes.

Gazette model

Variable	Type	Description	Constraints
`id`	`Integer`	An 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`	An 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 "https://api.recast.ai/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/gazettes"

require 'json'
require 'httparty'

result = HTTParty.get("https://api.recast.ai/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('https://api.recast.ai/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(`https://api.recast.ai/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 https://api.recast.ai/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 gazettes’ 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 "https://api.recast.ai/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/gazettes/$GAZETTE_SLUG"

require 'json'
require 'httparty'

result = HTTParty.get("https://api.recast.ai/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('https://api.recast.ai/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(`https://api.recast.ai/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 https://api.recast.ai/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 "https://api.recast.ai/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/gazettes"

require 'json'
require 'httparty'

result = HTTParty.post("https://api.recast.ai/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('https://api.recast.ai/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(`https://api.recast.ai/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 https://api.recast.ai/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/gazettes

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
`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 "https://api.recast.ai/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/gazettes/$GAZETTE_SLUG"

require 'json'
require 'httparty'

result = HTTParty.put("https://api.recast.ai/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('https://api.recast.ai/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(`https://api.recast.ai/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 https://api.recast.ai/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 "https://api.recast.ai/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/gazettes/$GAZETTE_SLUG"

require 'json'
require 'httparty'

result = HTTParty.delete("https://api.recast.ai/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('https://api.recast.ai/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(`https://api.recast.ai/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 https://api.recast.ai/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/gazettes/$GAZETTE_SLUG

This call does not 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 endpoints manages synonyms.

Synonym model

Variable	Type	Description
`id`	`Integer`	An 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 "https://api.recast.ai/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/gazettes/$GAZETTE_SLUG/synonyms"

require 'json'
require 'httparty'

result = HTTParty.get("https://api.recast.ai/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('https://api.recast.ai/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(`https://api.recast.ai/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 https://api.recast.ai/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 "https://api.recast.ai/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("https://api.recast.ai/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('https://api.recast.ai/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(`https://api.recast.ai/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 https://api.recast.ai/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 "https://api.recast.ai/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/gazettes/$GAZETTE_SLUG/synonyms"

require 'json'
require 'httparty'

result = HTTParty.post("https://api.recast.ai/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('https://api.recast.ai/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(`https://api.recast.ai/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 https://api.recast.ai/train/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/gazettes/$GAZETTE_SLUG/synonyms

Parameter	Type	Description	Constraints
`value`	`String`	The synoym 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 "https://api.recast.ai/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("https://api.recast.ai/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('https://api.recast.ai/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(`https://api.recast.ai/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 https://api.recast.ai/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 "https://api.recast.ai/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("https://api.recast.ai/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('https://api.recast.ai/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(`https://api.recast.ai/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 https://api.recast.ai/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 synoym 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 "https://api.recast.ai/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("https://api.recast.ai/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('https://api.recast.ai/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(`https://api.recast.ai/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 https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/dataset/gazettes/$GAZETTE_SLUG/synonyms/$SYNONYM_SLUG

This call does not 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`	An unique language id
`name`	`String`	The language name
`slug`	`String`	The language slug
`isocode`	`String`	The language isocode, follows the ISO 639-1 standard
`is_supported`	`Boolean`	Is the language fully handled by the platform (advanced level) or not (standard level)?

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`	`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

Show a conversation

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

require 'recastai'

build = RecastAI::Build.new(DEVELOPER_TOKEN)
response = build.get_conversation("USER_SLUG", "BOT_SLUG", "CONVERSATION_ID")

puts response

import recastai

build = recastai.Build(DEVELOPER_TOKEN)
response = build.get_conversation("USER_SLUG", "BOT_SLUG", "CONVERSATION_ID")

print(response)

var recastai = require('recastai').default

var build = new recastai.build('DEVELOPER_TOKEN')

build.getConversation("USER_SLUG", "BOT_SLUG", "CONVERSATION_ID")
  .then(function(res) {
    console.log(res)
  })

GET https://api.recast.ai/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.

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

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 "https://api.recast.ai/build/v1/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/builder/conversation_states/$CONVERSATION_ID"

require 'recastai'

build = RecastAI::Build.new(DEVELOPER_TOKEN)
conversation = build.update_conversation("USER_SLUG", "BOT_SLUG", "CONVERSATION_ID", { 'language': 'en' })

puts conversation

import recastai

build = recastai.Build(DEVELOPER_TOKEN)
conversation = build.update_conversation("USER_SLUG", "BOT_SLUG", "CONVERSATION_ID", { 'language': 'en' })

print(conversation)

var recastai = require('recastai').default

var build = new recastai.build('DEVELOPER_TOKEN')

build.updateConversation("USER_SLUG", "BOT_SLUG", "CONVERSATION_ID", { language: "en" })
  .then(function(res) {
    console.log(res)
  })

PUT https://api.recast.ai/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.

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

Delete a conversation

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

require 'recastai'

build = RecastAI::Build.new(DEVELOPER_TOKEN)
response = build.delete_conversation("USER_SLUG", "BOT_SLUG", "CONVERSATION_ID")

puts response

import recastai

build = recastai.Build(DEVELOPER_TOKEN)
response = build.delete_conversation("USER_SLUG", "BOT_SLUG", "CONVERSATION_ID")

print(response)

var recastai = require('recastai').default

var build = new recastai.build('DEVELOPER_TOKEN')

build.deleteConversation("USER_SLUG", "BOT_SLUG", "CONVERSATION_ID")
  .then(function(res) {
    console.log(res)
  })

DELETE https://api.recast.ai/build/v1/users/$USER_SLUG/bots/$BOT_SLUG/versions/$VERSION_SLUG/builder/conversation_states/$CONVERSATION_ID

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

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 "https://api.recast.ai/connect/v1/connectors/$BOT_ID"

require 'json'
require 'httparty'

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

puts JSON.parse(result.body)

import requests

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

print(response.text)

const request = require('superagent');

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

GET https://api.recast.ai/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 "https://api.recast.ai/connect/v1/connectors/$BOT_ID"

require 'json'
require 'httparty'

result = HTTParty.put("https://api.recast.ai/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('https://api.recast.ai/connect/v1/connectors/$BOT_ID',
  json={'name': NAME, 'url': URL},
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

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

PUT https://api.recast.ai/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 "https://api.recast.ai/connect/v1/connectors/$BOT_ID"

require 'json'
require 'httparty'

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

puts JSON.parse(result.body)

import requests

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

print(response.text)

const request = require('superagent');

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

DELETE https://api.recast.ai/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 "https://api.recast.ai/connect/v1/channels/$CHANNEL_SLUG"

require 'json'
require 'httparty'

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

puts JSON.parse(result.body)

import requests

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

print(response.text)

const request = require('superagent');

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

GET https://api.recast.ai/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 "https://api.recast.ai/connect/v1/channels"

require 'json'
require 'httparty'

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

puts JSON.parse(result.body)

import requests

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

print(response.text)

const request = require('superagent');

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

GET https://api.recast.ai/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 "https://api.recast.ai/connect/v1/channels"

require 'json'
require 'httparty'

result = HTTParty.post("https://api.recast.ai/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('https://api.recast.ai/connect/v1/channels',
  json={'isActivated': true, 'slug': SLUG, 'type': TYPE },
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

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

POST https://api.recast.ai/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 "https://api.recast.ai/connect/v1/channels/$CHANNEL_SLUG"

require 'json'
require 'httparty'

result = HTTParty.put("https://api.recast.ai/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('https://api.recast.ai/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(`https://api.recast.ai/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 https://api.recast.ai/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 "https://api.recast.ai/connect/v1/channels/$CHANNEL_SLUG"

require 'json'
require 'httparty'

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

puts JSON.parse(result.body)

import requests

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

print(response.text)

const request = require('superagent');

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

DELETE https://api.recast.ai/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
`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 "https://api.recast.ai/connect/v1/conversations/$CONVERSATION_ID"

require 'json'
require 'httparty'

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

puts JSON.parse(result.body)

import requests

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

print(response.text)

const request = require('superagent');

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

GET https://api.recast.ai/connect/v1/conversations/${CONVERSATION_ID}

This call returns a conversation model in results variable.

Indexing conversations

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -X GET "https://api.recast.ai/connect/v1/conversations"

require 'json'
require 'httparty'

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

puts JSON.parse(result.body)

import requests

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

print(response.text)

const request = require('superagent');

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

GET https://api.recast.ai/connect/v1/conversations

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

Deleting a conversation

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -X DELETE "https://api.recast.ai/connect/v1/conversations/$CONVERSATION_ID"

require 'json'
require 'httparty'

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

puts JSON.parse(result.body)

import requests

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

print(response.text)

const request = require('superagent');

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

DELETE https://api.recast.ai/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 "https://api.recast.ai/connect/v1/participants/$PARTICIPANT_ID"

require 'json'
require 'httparty'

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

puts JSON.parse(result.body)

import requests

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

print(response.text)

const request = require('superagent');

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

GET https://api.recast.ai/connect/v1/participants/${PARTICIPANT_ID}

This call returns a participant model in results variable.

Indexing participants

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -X GET "https://api.recast.ai/connect/v1/participants"

require 'json'
require 'httparty'

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

puts JSON.parse(result.body)

import requests

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

print(response.text)

const request = require('superagent');

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

GET https://api.recast.ai/connect/v1/participants/$PARTICIPANT_ID

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

/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!"}]}' \
     "https://api.recast.ai/connect/v1/conversations/$CONVERSATION_ID/messages"

require 'json'
require 'httparty'

result = HTTParty.post("https://api.recast.ai/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('https://api.recast.ai/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('https://api.recast.ai/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 https://api.recast.ai/connect/v1/conversations/$CONVERSATION_ID/messages

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

Check the Hello world 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!"}]}' \
     "https://api.recast.ai/connect/v1/messages"

require 'json'
require 'httparty'

result = HTTParty.post("https://api.recast.ai/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('https://api.recast.ai/connect/v1/messages',
  json={ "messages": [{ "type": "text", "content": "Hello World !" }]},
  headers={'Authorization': 'Token REQUEST_TOKEN'}
)

print(response.text)

const request = require('superagent');

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

POST https://api.recast.ai/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.

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": "recast.ai",
  "raw": "paul@recast.ai",
  "confidence": 0.99
}

Entity	Examples
`email`	hello@recast.ai, hello+devs@recast.ai, hello.you+devs@recast.co.uk
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": "41000 Blois, France",
  "lat": 47.58609209999999,
  "lng": 1.3359475,
  "place": "ChIJXdLII5VX40cRsCk4BdfIDQQ",
  "type": "locality",
  "country": "fr",
  "raw": "Blois",
  "confidence": 0.84
}

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
`place`	String, the Google Places id 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`, …
`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.recast.ai",
  "path": "/register",
  "params": null,
  "query": null,
  "fragment": null,
  "raw": "https://pokebot.recast.ai/register",
  "confidence": 0.99
}

Entity	Examples
`url`	https://recast.ai, localhost:9000, api.recast.ai/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

Changelogs

2.15.0

Please find below the changelog for Recast.AI v2.15.0, 23/04/2018:

TRAIN

Introducing Context Awareness for gold and custom entity detection!
- When using Bot Builder through skills, our entity detection system will use the previous interactions to improve its accuracy
- Misunderstanding related to uncommon names, ambiguous words and complex entities will be drastically reduced

MISC

Added a stronger password policy for all new users
Added a reset password form in the user’s settings
Updated the Privacy Policy page to reflect GDPR-related information

2.14.0

You can read below the changelog for Recast.AI v2.14.0, 01/04/2018:

BUILD

Fixed the requirements behaviour: When you create an OR group with two requirements and all the requirements are missing, the bot replies the message you set when the both requirements are missing and not both messages for both requirements missing.
Messages in the the Actions and Requirements tab and be reordered through drag and drop.
A list view has been added to the Builder interface. You can toggle between the current graphical view and the new list view to search and filter skills.
Debugging can be done in a webchat-embedded console to diagnose why a bot doesn’t reply in a appropriate way

TRAIN

Intents can be reordered in the Train tab.
Training can be triggered on demand. In your bot settings, you can switch the training mode from automatic to manual to only train when you want.

MISC

Added a new verification in your bot creation process to be sure that every public bot is not trained with personnel and private data. If so, your bot will be private.

2.13.0

You can read below the changelog for Recast.AI v2.13.0, 01/03/2018:

BUILD

Added a new action type, Fallback action to be able to fallback the conversation to a support channel like Intercom
Added a new action in the conversation update type: Switch the conversation language to another
Added a new action in the conversation update type: Edit the memory by resetting all the memory or just set or unset some fields.

CONNECT

Improve the Webchat channel
- Improve the history retrieval with 3 different possibilities: No history, Unlimited time, or time in hours defined by the developer.
- Added a new configuration: The webchat status. It can be always open, or close, or stay in the same state as the last user visite state.
- Added a new configuration to set a welcome message
- Added a new notification when the message was not successfully sent because of a poor internet connection
- Improve the responsive behaviour and the Mobile usage
Addded support for Intercom as a fallback channel

2.12.0

You can read below the changelog for Recast.AI v2.12.0, 01/02/2018:

TRAIN

Improved performance of the intent classification by 25%
- Better native support of synonyms and typos
- This new classification will be used for new bots only. Old bots will not be impacted by this change since it can modify the bot performance
Reduced training time by 70% for complex and/or large bots
Fixed an issue where expressions were ignored when merging two intents with override set to true

BUILD

Added a new webchat console to test your bot with all rich messaging
Added a new action to let you change the conversation language in a skill
Added a new indicator about messages restrictions in all message actions
Improved the Bot Skills interface:
- The requirements section now has a new box that represents what’s stored in your conversation memory
- The condition selector has been reworked to offer a better UI to visualize all the possibilities
Replaced the settings section by in-place edition of a skill type and name directly in the main view
Fixed the variables replacement in Skills actions by stripping spaces, you can now write {{ var }} or {{var}}
Fixed the carousel message edition, change the close button by a SAVE button
Fixed the loading performance of the BUILD tab when too many skills were linked each other

CONNECT

Added support for two new channels: Line, and Webchat
- The webchat lets you embed your bot directly into your website
Re-wrote the Microsoft integration steps, due to an update of the Microsoft Bot Framework.

SDKs

Added /dialog support in the Golang SDK

MISC

Reworked the bot page loading, we wait now with an empty state to know if the bot contain a Connector, a Builder etc ..
Added a footer in the BUILD section

2.11.0

You can read below the changelog for Recast.AI v2.11.0, 01/12/2017:

TRAIN

Improved performance of the intent page:
- Implemented a lazy-loading strategy for expressions
- Entities contained in intents and those intents are now fetched at the same time
Slightly reduced the time taken to fork (and merge) a bot, a gazette, or an intent
Drastically reduced the time taken to create an expression for a bot with very large conversation history
Reduced by 25% the training time for large bots
Fixed a case where the default language of a bot was not returned when indexing a bot’s languages - thanks jerome
Fixed a synchronisation issue with the training indicator and the actual training state
Fixed an issue with the entity creation returning a bad request when it’s name was not pre-slugified - thanks lb
Fixed a parameter issue with the gazettes’ creation and update: - thanks lb
- The API reference said those endpoints required a entity object with an id attribute to create/update a gazette, this is now true

BUILD

Introduced a brand new version of Bot Builder by Recast.AI!
- This version introduces Skills, which are like lego bricks that manage a specific part of the conversation
- It also integrates rich messaging, as available on channels
- You can also define webhooks to make use ping your custom code when you need to
- Skills are forkable, just like bots and intents

CONNECT

Fixed various inoffensive but annoying bugs
Fixed an message parsing issue with Facebook Messenger when a user sends a raw link:
- Messenger sometimes adds fallback attachment to unfurl the linked url
Improved the setup processes for Slack and Messenger

MONITOR

Added a new pending state for the logs to return the inverse of archived logs:
- Logs appearing in the All section of the MONITOR tab will be filtered with the pending state

REQUEST

Made log creation when calling /request, /converse and /dialog 3 times faster
Fixed a concurrency issue for log creation when calling /request, /converse or /dialog
Reduced inference time for the question type classification by 2 folds

MISC

Reworked the UI to show at most 6 tabs: TRAIN, BUILD, CODE, CONNECT, HOST, and MONITOR:
- TRAIN, CODE, and MONITOR are default tabs
- BUILD, CONNECT, and HOST tabs can be activated via the bot’s settings

2.10.1

Please find below the changelog for Recast.AI v2.10.1, 11/10/2017:

TRAIN

Improved error message when invalid languages objects are received

RUN

Fixed several minor bugs in enriched message handling

REQUEST

Improved edge-cases detection for the following entities: DATETIMEs, PERSONs, LOCATIONs and NUMBERs
Fixed a few enrichment issue for DATETIMEs
- après-midi without modifier is now always treated as 1pm
- differents spellings of week-end are now treated the same way

2.10.0

Please find below the changelog for Recast.AI v2.10.0, 28/09/2017:

TRAIN

Introduced expressions suggestions! (beta)
- When you add an expression to your bot, at most 5 suggestions are proposed
- You can either accept or refuse the suggestions, which will add them to or blacklist them from your intent
- To learn more about using this feature, head to our developer guide
Fixed an issue preventing the merge of two intents when the override was not activated and an expression from intent A was already in intent B
Fixed an ordering issue with the logs contained in the Log Feed
Fixed the gazette’s matching strictness not being equal to the original gazette when forking a bot - thanks adminmatcha

BUILD

Improved response-time for large builders flow

REQUEST

Optimized our Language Detection service making it several orders of magnitude faster!
- The language detection performance will suffer small changes on very short sentences
Fixed a bug in MONEY enrichment where the euro currency written as e or E was mistaken as a power of ten without value
Fixed some datetime enrichment errors in French - thanks dominik

MISC

Set preflight request max_age to 86400s - thanks kazi-rashid
Fixed a deconnexion issue when reloading a few specific pages

2.9.0

You can read below the changelog for Recast.AI v2.9.0, 12/07/2017:

TRAIN

Added support for 28 new languages!
- Amharic, Azerbaidjani, Belarusian, Bengali, Burmese, Czech, Filipono, Greek, Hausa, Hebrew, Hugarian, Indonesian, Khmer, Laotian, Malay, Nepali, Persian, Punjabi, Romanian, Serbian, Singhalese, Thai, Turkish, Ukrainian, Urdu, Uzbek, Vietnamese, Yoruba
- We now have three levels of support: Advanced, Standard, and Basic as explained here
Added a new merge feature!
- Merging two intents will copy the expressions of the intent A into intent B
- The handling of similar expressions between the source intent and the target intent is done with two strategies: keep source or override
Added the ability to choose a language when forking an intent or merging two intents
- Only expressions in this language will be forked/merged to your intent

REQUEST

Bot Connector will now populate an origin field with the name of the channel the message comes from
Reduced the request time by 110% for bots with a large number of conversations

2.8.0

Please find below the changelog for Recast.AI v2.8.0, 07/07/2017:

TRAIN

Added support for 16 new languages!
- Arabic, Catalan, Chinese, Danish, Dutch, Finnish, German, Hindi, Italian, Japanese, Korean, Norwegian, Polish, Portuguese, Russian, Swedish
- We now have two levels of support: Advanced and Standard as explained here
Reworked the bulk creation of expressions by processing them in backgound
- The impacted endpoints are: bulk creation of expressions, intent creation, and csv import of a bot
- The maximum number of expressions per request for those endpoints is set to 15 000
- A new endpoint to get the status of sentence processing is available here
Improved error messages in CSV import
- We are now more specific about potential format or encoding errors
- We now return the column, row and expression’s id when an error occurs

RUN

Added support for Twitch channel!

REQUEST

Improved interval parsing using 12/12/2012 format
Updated the Gold NER detection (English, French, and Spanish) to handle more complex names

2.7.1

You can read below the changelog for Recast.AI v2.7.1, 20/06/2017:

REQUEST

Fixed an entity detection issue where a synonym has a trailing whitespace - thanks thisisritz
Fixed an enrichment issue in French DATETIMEs where a non-accentued a was confused with a short-hand year unit
Improved DATETIMEs parsing for a few French cases:
- 18 juillet dernier, le 4 mars prochain the day number is no longer forgotten when applying the time modifier

2.7.0

Please find below the changelog for Recast.AI v2.7.0, 09/06/2017:

RUN

Added Twitter channel, based on their new Direct Message API
Added Microsoft Bot Framework channel, which grants the access to Skype, Microsoft Teams, Cortana, …
Added the isTyping parameter which, if activated, sends a typing indicator on Messenger, Kik and Twitter when the bot receives a message
Added Slack teams the bot is connected to under the field children in the json returned by https://api.recast.ai/connect/v1/channels/:channel_slug
Added two new message formats: list and carousel
Added support for Gitlab.com and Gitlab CE/EE for Bot Hosting

REQUEST

Reduced processing time by 50%!
Released a new caseless NER model for English, French and Spanish
Added the field state in the DATETIME enrichment, qualifiying the DATETIME as absolute or relative
- in two days, two days ago, the day after tomorrow will be tagged as relative
- 24/10/2017, monday, march 20, 2017, july 5 at 5pm will be tagged as absolute

2.6.0

Here is the changelog for Recast.AI v2.6.0, 20/04/2017:

TRAIN

Added support for Spanish language!
Fixed a few bugs with intent detection

REQUEST

Added the sentiment field to the JSON response of the /converse endpoint
Added a new field called processing\_language to expose the language used to process the request in both the /converse and /request JSON responses.

2.5.0

Please read the changelog for Recast.AI v2.5.0 below, 30/03/2017:

TRAIN

Renamed the LEARN tab to TRAIN
Added a search bar to filter intents
Reworked the TRAIN tab to propose two modes, view and edit:
- View mode displays informations of intents: entities contained, number of expressions
- Edit mode lets you rename, disable, enable and destroy intents
Added a panel to display the total number of expressions, the number of expressions by language, the occurences of entities for the current intent
Removed the ability to label gold entities in the expression view
Bundled together the gold entities in the Your bot entities part of the tab
Added a panel to display the total number of synonyms, and the number of synonyms per language for the current gazette
Added a settings panel to open/close your gazette, and change its strictness
Added a format example to import synonyms with a .csv file (finally!)

RUN

Introduced the RUN tab, to allow bot connection, code, deployment, and sharing:
- Bot Connector is a standardized messaging API that lets you configure multiple channels (Messenger, Slack, Kik, Callr, Telegram and Twilio for now) for your bot - more
- Code is a collection of snippets to quickly start coding your bot (Javascript, Python, Ruby and PHP for now) - more
- Bot Hosting is an easy-to-use hosting service tightly integrated with your git provider flow (Github only for now) that deploy, run, and monitor your bot - more
- Share will become your toolbox to make people discover and test your bot

MONITOR

Introduced the MONITOR tab, which displays your log feed, usage metrics, training analysis, conversations logs, and conversation metrics:
- Log Feed is the old TRAIN, and lists the raw sentences your bot received, to let you correct the intent prediction
- Usage Metrics displays useful information about the usage of your bot: average number of interactions per day/week, summed number of interactions per hour/day, average words per interaction, entities usage and intents usage
- Training Analytics helps your judge your bot quality by displaying your training balance and quality, your intents’ size, and the intents lacking expressions
- Conversation Logs will be the contextualized Log Feed, where you will find complete conversation your bot had with your users
- Conversation Metrics will display useful information about the conversation your bot has
Added filters to select logs by language, matched intent, and paginate them by 20, 50, or 100

REQUEST

Reworked the console design to make it stand out a bit more
Replaced the language selector by a dropdown to prepare for future language additions
Merged the two consoles in two tabs Converse and Analyse text:
- Converse uses your Bot Builder configuration and Train to let you have a conversation with your bot
- Analyse Text applies NLP to your input to display a JSON full of useful information
Make each tab use two views, smart and JSON:
- Smart view either displays the conversation in a pretty messenger-like interface, or the main information extracted from your input
- JSON view displays the JSON response’s content for you to analyse
Modified the behavior of the type field of the Analyse Text to only return a value when the speech act is wh-type, increasing its usage simplicity and accuracy
Improved the classification accuracy by 30%
- This change is currently in beta and will be released platform-wide soon
Improved detection of DATETIMEs, NUMBERs, and LOCATIONs

MISC

Added a loader displaying whether your bot is training or not
Added one explanatory page per service (Language API, Bot Builder, Bot Connector, Bot Hosting, Bot Analytics)
Reworked the documentation to separate guides (directly accessible at recast.ai/docs) and API reference (accessible at man.recast.ai):
- Train guide here
- Build guide here
- Connector guide here
- Hosting guide here
Moved the support chat to the left of the screen, unblocking the console input field
Replaced the (?) helpers by more visible helpers featuring Bibi
Fixed a case where the fork count would go down to -1

2.4.0

Here is the changelog for Recast.AI v2.4.0 patch notes, 01/02/2017:

BOT BUILDER

Added the selection of an isolated action when several actions are available
Fixed an issue where the conditions were not validated by the current input
Fix an issue where the done field wasn’t correctly set in the next actions

PLATFORM

Fixed a case were the conditions were not forked with a bot

API

Added voice support on the /converse endpoint:
- See here for more information on usage
Updated the sentence length limit to 512!

ENTITIES

{
    "formatted": "happy",
    "feeling": "happy",
    "description": "smiling face with open mouth & smiling eyes",
    "unicode": "U+1F604",
    "tags": [
        "eye",
        "face",
        "mouth",
        "open",
        "smile"
    ],
    "raw": ":)",
    "confidence": 0.99
}

Added support for the EMOJI entity!
- We currently support 3 types of emojis: American (:)), Unicode (☺), and colon-style (:smile:)
- Enrichment is composed of a localized formatted feeling, a raw feeling, a name, a description, its unicode, and a list of tags (example on the right-hand side)

V1

Dropped support for /v1 endpoints
- 6 months after we rolled out the /v2 of our API, the /v1 endpoints were shutdown on January 31st
- Don’t hesitate to contact us if you need any help to migrate to the /v2 endpoints: jasmine@recast.ai

2.3.1

Recast.AI v2.3.0 patch notes, 26/01/2017:

ENTITIES

Reworked the INTERVAL detection to avoid confusions between it and DATETIMEs, NUMBERs and DURATIONs.

2.3.0

Below is Recast.AI v2.3.0’s changelog, 16/01/2017:

PLATFORM

Added the ability to add collaborators to your bot!
- Collaborators can do everything like they were the owner of the bot, except: edit the bot’s name, change its primary language, view the developer_token, refresh the request_token, manage collaborators, change the bot’s privacy, delete the bot
Added entities gazettes! They are list of words that should belong to an entity.
- Open gazettes will be used as additional information for the entity recognition
- Closed gazettes will ensure that no word can be recognized as an entity if it does not appear in the gazette
Reworked the content of the “LEARN” tab to display the entities contained in your bot

API

Added a new :image parameter in the /request endpoint to recognize contents of an image!
- This feature is in alpha: the response structure, response time, and tags returned can change at any time

ENTITIES

Fixed an issue with the INTERVALs enricher that confused days and months
Improved handling of edge cases in the enrichment of DATETIMEs

2.2.0

Here is the Recast.AI v2.2.0 changelog, 06/01/2017:

BOT BUILDER

Added “notions conditions”, a new way to help you build your conversation flow:
- You can link to a specific action when a notion is or is not equal to a set of expected values
Fixed several issues about the action selection:
- There is no more default action selection when several actions are possible
- Several actions are returned in the next_actions field when they are done
Fixed an issue concerning the filling of the bot memory when there is several entities in the sentence

TRAIN

Added a way to see the entites we detected directly inside the TRAIN tab

ENTITIES

Fixed an issue with the enrichment of unsupported metrics (20€/month -> money/time)
Fixed a crash where the system was not able to detect an entity boundary during the entity merging phase

2.1.4

Please find below the Recast.AI v2.1.4 changelog, 04/12/2016:

ENTITIES

Improved the detection of French entities by 33%
Improved the detection of English entities by 10%
Updated the behavior of the DATETIME enricher - thanks bassmanitram
- An absolute date (4th april 1966, sunday 6 december, …) has its time set to 00:00:00 unless a time is provided
- A relative date (in two days, last sunday, next week, …) has its time set to the current time
- As a side-effect, the enrichment of INTERVAL boundaries will be affected
Improved the parsing of INTERVALs by balancing them when they have unbalanced parts: - thanks nlaloum
- between december 14th and 15th’s boundaries are now december 14th and december 15th
- from monday 3pm until 4pm’s boundaries are now monday 3pm and monday 4pm
- january-february 2017’s boundaries are now january 2017 and february 2017
Fixed numerous issues concerning the DATETIME enrichement (the day before yesterday, weekend, today before 3pm, tomorrow 6.54, tuesday morning 9am are now all handled)- thanks pertoul, obiran, hugo-cherchi
Fixed an issue with the NUMBER enricher when handling un seul
Fixed an enrichment issue with negative ORDINALs

BOT BUILDER

Updated the behavior of actions: they can are now undone when associated notions are reset in the conversation

API

Smoothed the usage of the /request and /converse endpoints by ignoring the case when checking for a language validity

2.1.3

Recast.AI v2.1.3’s patch notes, 28/11/2016:

PLATFORM

Fixed an problem where the bot decision process forced a next action instead of not choosing - thanks bassmanitram
Fixed an issue where the end of conversation boolean was not correctly propagated after a builder fork

ENTITIES

Fixed an enrichment error on ORDINALs, from which resulted null in the rank field, when the ORDINAL was already numerized before being numerized by the parser
Improved the enrichment of DATETIMEs by treating meridian markers (am, du soir, …) as an halfday accuracy
Improved the handling of future modifiers (next, prochain, …) in DATETIMEs by applying a two days threshold:
- If the current time is two days or more before the target time, select the current week’s occurence
- Else select the occurence of the following week
Fixed an enrichment issue of DATETIMEs in the calendar format (dd/mm/yyyy, dd/mm/yy, dd/mm) - thanks bassmanitram
- If the expected mm is superior to 12, dd and mm are swapped before being processing

2.1.2

Below is the changelog for Recast.AI v2.1.2, 24/11/2016:

BOT BUILDER

Improved the action matching by using the notions contextually
Improved the memory of the bot by filling the notion which was asked in the last frame

ENTITIES

Added support for mid like DATETIME (mid-september, mid 2016, midday, …) - thanks mQment
Added begin_accuracy, begin_chronology, end_accuracy, end_chronology fields to INTERVAL (more info here)

2.1.1

Patch notes for Recast.AI v2.1.1, 18/10/2016:

ENTITIES

Improved French DATETIMEs enrichment
Fixed an error which made Recast.AI return GMT+2 datetimes, now returning UTC datetimes as expected

2.1.0

Recast.AI v2.1.0 changelog, 15/10/2016:

PLATFORM

Introduced the Bot Builder by Recast.AI!
- By using Bot Builder, you’ll be able to create complex conversation flows for your bot to handle
Added a new tab called “RUN” displaying bootstrap code for /request and /converse use
Improved the fork times, making them 2500% faster

API

Added a new endpoint called /converse which let you use the logic you built in the Bot Builder

2.0.0

Below is changelog for Recast.AI v2.0.0, 02/10/2016:

PLATFORM

Reworked the entities background and font colors to be smoother

JSON

You can view the new JSON architecture on the right side.

{
  "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",
          "lng": -0.1277583,
          "lat": 51.5073509,
          "type": "locality",
          "place": "ChIJdd4hrwug2EcRmSrV3Vo6llI",
          "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",
    "version": "2.0.0",
    "timestamp": "2016-09-30T10:29:54.211866Z",
    "status": 200
  },
  "message": "Request rendered with success"
}

Reworked the process of inputs to treat them all as a single sentence
Exposed uuid, a unique identifier for this request, for support purposes
Renamed the type field to act and make it behave like it is described in James Allen’s book, Natural Language Understanding
Added a type field describing the question type defined in this question classification taxonomy
Added the sentiment of a sentence, which can be either vpositive, positive, neutral, negative, or vnegative
Removed the action and agent fields
Removed the polarity field as it’s been replaced by sentiment
Reworked the intents to be an object with a slug and a confidence score, a float between 0 and 1 excluded
Added a confidence score (float value between 0 and 1 excluded) as another common field between all entities

ENTITIES

Below is the list of change for each entity and its enrichment in alphabetical order:

AGE
- Removed in favor of DURATION
CARDINAL
- Changed deg to bearing
COLOR
- Added rgb
DATETIME
- Changed value to iso
- Added formatted
- Added accuracy
- Added chronology
DISTANCE
- Changed value to scalar
- Added meters
DURATION
- Changed value to seconds
- Added chrono
- Added minutes
- Added hours
- Added days
- Added months
- Added years
EMAIL
- Removed value
- Added local
- Added tag
- Added domain
INTERVAL
- Added the entity
- Added begin
- Added end
- Added timespan
JOB
- Removed value
LANGUAGE
- Changed code to short
- Added long
LOCATION
- Changed formated to formatted
- Added type
- Added place
MASS
- Changed value to scalar
- Added grams
MISC
- Removed in favor of better detection of other entities
MONEY
- Changed value to amount
- Changed unit to currency
- Added dollars
NATIONALITY
- Changed code to short
- Added long and country
NUMBER
- Changed value to scalar
ORDINAL
- Changed value to rank
ORGANIZATION
- Removed value
PERCENT
- Changed value to scalar
- Added percent
PERSON
- Changed value to fullname
PHONE
- Changed value to number
SET
- Changed next to use ISO-8601 format
- Changed grain to frequency
- Added interval
- Added rrule
SORT
- Changed value to criterion
SPEED
- Changed value to scalar
- Added mps
TEMPERATURE
- Changed value to scalar
- Added celsius
URL
- Removed value
- Added scheme
- Added host
- Added path
- Added params
- Added query
- Added fragment
VOLUME
- Changed value to scalar
- Added liters

1.3.0

Here is the changelog for Recast.AI v1.3.0, 01/07/2016:

LANGUAGES

Added support for French language!

ENTITIES

Added detection of phones and jobs
Added enrichment of phones and jobs

MISC

Fixed a typo in enrichment of pronouns
Fixed an error in enrichment of ordinals (second and third not returning expected enrichment)
Improved overall stability
Improved overall detection

1.2.1

Please find below the Recast.AI v1.2.1 patch notes, 30/05/2016:

API

Removed worfklows, introducing the following changes:
- On all routes, removed the [...]workflows/$WORKFLOW_SLUG[...]
Removed release linked to a bot
Removed upgrade endpoint (bots/$BOT_SLUG/upgrade)
Lightened the bot model at Getting an user’s bot:
- The bot now contains light intents

1.2.0

Recast.AI v1.2.0, 02/04/2016:

PLATFORM

Added support for user-defined entities!
- You can now train you agent to detect entities specific to your use-case by highlighting a word and selecting the appropriate entity

ENTITIES

Improved detection of datetime, temperatures and money

1.1.1

You can find below the changelog for Recast.AI v1.1.1, 26/03/2016:

MISC

Fixed several bugs in entity detection and enrichment

1.1.0

Changelog for Recast.AI v1.1.0, 18/03/2016:

PLATFORM

Added support for audio!
- As of now, we only support audio files

INTENTS

Improved the baseline classifier in preparation of future additions

JSON

Improved the timestamp returned in the JSON (now ISO 8601 compliant)

MISC

Fixed several bugs

1.0.1

Here is the changelog for Recast.AI v1.0.1, 15/03/2016:

MISC

Fixed some error handling
Improved overall processing and stability

1.0.0

Below is the changelog for Recast.AI v1.0.0, 25/02/2016:

NLP

Added detection of sentences boundaries
Added detection of sentence polarity
Added detection for 9 types of sentences (assert, command, yes_no, what, where, who, when, how, why)
Added a baseline classifier

ENTITIES

Added detection of ages, cardinals, colors, datetimes, distances, durations, emails, IPs, languages, locations, masses, money, nationalities, numbers, ordinals, organizations, percents, persons, pronouns, sets, sorts, speeds, temperatures, urls, volumes, and miscellaneouses entities
Added enrichment for ages, cardinals, colors, datetimes, distances, durations, emails, IPs, languages, locations, masses, money, nationalities, numbers, ordinals, organizations, percents, persons, pronouns, sets, sorts, speeds, temperatures, urls, volumes, and miscellaneouses entities

MISC

Added versioning