NAV
shell ruby python javascript

Introduction

Quick start

Create Bots

Create from scratch

To create a new bot, go on your profile section by clicking on the ‘BOT’ tab. Then, clic the blue button “+ NEW BOT”.

create bot

Import bots

import bot

We provide an easy way for you to import a bot via CSV files.

To assure a maximum reliability, your CSV file must follow the following directives:

Template

"intent";"description";"expressions"
"intent name";"intent description";"first expression;;second expression;;third expression"
intent description expressions
“intent name” “intent description” “first expression;; second expression;; third expression;;”

Requirements

Best practices

Create intents

Everything your bot knows is in the intents. Intents are boxes including expressions that mean the same thing but are constructed differently. Each intent correspond to one action your user want to perform. for exemple, an intent ‘greetings’ make your bot understand when a user say ‘Hello’.

empty bot

Fork intents

As the platform is collaborative, there are a lot of intents already created. We recommend you to first search in the community if the intent you need already exists by using the ‘SEARCH’ function. If you find one you like, just click on the ‘FORK’ button on the right. fork intent

Create from scratch

If you don’t find what you need or you want to create an intent yourself, just clic the “CREATE” button

create intent

Add expressions

You have a new intent in your bot! Click on it. Here, you can see all the expressions you have in your intent. The optimal setting for a great intent is around 20 different expressions with unique constructions. Think of anything your user can ask your bot to create your intent, and add them with to the field ‘Add an expression’.

add expression

Use entities

‘Greetings’ is a simple intent. Some of them are a little more complex. Let’s take the example of a food ordering intent: the user provides a location and a meal, and these information have to be extracted from the message.

That’s why we have entities: they’re keywords detected in expressions.

location entity

We automatically detect 31 different entities. If you need another entity, like a meal, just select what you want to tag as your new entity and type a name. The more examples you provide, the better the detection will be ;)

meal entity

Use the console

Once you’ve setup your bot, you can test it with the console. Click on the chat bubble icon on the top right to make it appear. The answer is in JSON format and contains many useful information about the message you’ve sent.

Notice that an intent has been matched and entities has been found.

console

Make your request

This JSON returned in the console is what you receive when making a request to your bot. To get that response, you need to make a request to your bot. How? First, get your bot token: click on the little gear icon to go to the settings of your bot.

curl -H "Authorization: Token REQUEST_TOKEN" \
     -d "{text=TEXT}" \
     "https://api.recast.ai/v2/request"
require 'httparty'
require 'json'
result = HTTParty.post("https://api.recast.ai/v2/request",
  body: { text: TEXT },
  headers: { 'Authorization' => 'Token REQUEST_TOKEN' }
)
puts JSON.parse(result.body)
import requests
response = requests.post('https://api.recast.ai/v2/request',
  params={'text': TEXT},
  headers={'Authorization': 'Token REQUEST_TOKEN'}
)
print(response.text)
var request = require('superagent')

request
  .post('https://api.recast.ai/v2/request')
  .send({
    text: TEXT
  })
  .set('Authorization', 'Token REQUEST_TOKEN')
  .end(function(err, res) {
    console.log(res)
  })

token

Here, you’ll find you request access token. Then you’re ready to make your request! * REQUEST_TOKEN is the token you just got * TEXT is the message you want to send to your bot

Train your bot

When your message doesn’t match any intent, you have to train your bot. Go to the ‘train’ tab on your bot page.

Here are the logs of your bots. Select the expressions that did not match and redirect them to the good intent. After that, check that your custom entities have been automatically tagged. If not, do it. They need some training too ;)

train

Later, when your bot starts to have a lot of users, keep an eye on your train section cause there will be a huge amount of logs. Take the time to archive good matches, and to redirect mismatches. This will only make your bot smarter ;)

Build your first bot

alt text

the interface

alt text

Create an Action

An action is a step in your conversation. It is triggered by a user input and completed by a bot response. An action is always paired with an intent.

alt text

Add notions

A notion is an information required by your bot to complete an action and continue the conversation. The notion is stored in the memory of the bot and is available at all time. * To create an action with two notions, create your action, click on the pen, stay on the “Overview” tab and click on “ADD NOTION". * Select an entity in the list or search it.

alt text

alt text

alt text

alt text

A link connects actions to create your conversation flow.

alt text

alt text

alt text

Conversation flow

alt text

With our Bot Builder, the conversion can start at any different green-linked action. (cf. first step above).
However, red-linked actions require all notions to move on to the next step (cf. second step above).
Each action can be the end of the conversation.When it ends, the conversation resets, just like the bot memory (cf. end of the conversation).

Test your bot

At the top of your console you have two switches. The first one is the language your bot understands, either english, french, or automatic detection.

The ON and ALL switch is a little trickier. When ALL is selected, your bot answers to queries touching all actions in your conversation flow. When ONE is selected, your bot only focuses on one single action and its answers.

alt text

Launch your bot

Chose one of the starter kits, follow the Readme, and easily connect your bot to one (or many) of the following messaging applications.

A step further:

If you like to go further with our Bot Builder, check this section of the man

Starter kits

Recast.AI provides several Starter kits. They all are open-source and hosted on Github.

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

Language Platform Repositories
NodeJS Facebook Messenger Github
NodeJS Kik Github
NodeJS Slack Github
NodeJS Twillio Github
NodeJS CiscoSpark Github
NodeJS Smooch Github
NodeJS Telegram Github
NodeJS Line Github
NodeJS Microsoft Bot Connector Github

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
Ruby 2.1.1 Github - Rubygems
Python 2.2.3 Github - Pypi
NodeJS 2.2.1 Github - NPM
Golang 2.1.0 Github - GoDoc
Scala 2.0.0 Github - Scaladex
Swift 2.0.0 Github - Cocoapods
Android 3.0.0 Github - Bintray
PHP 2.0.0 Github - Packagist

Basics

By using our platform, you’ll see words that you’ve never really used before. Here are some basics that you should read to get ready! If you wish to have more tips before diving into the platform, we recommand you to visit this article.

Intent

Definition

An intent is a box of expressions that mean the same thing but are constructed in different ways. Intents are the heart of your bot understanding. Each one of your intents represents one thing your bot is able to understand.

Example

you want your bot to understand when someone asks for help. Just create an intent called ‘help’ and fill it with every expressions a user would say when asking for guidance.

Tips

Schema_intents

Expression

Definition

An expression is a sentence your bot can understand: basically your users’ inputs. Expressions are organized in intents and constitute the entire knowledge of your bot. The more expressions you have, the more accurate your bot will be. In an expression, you can tag entities to make them appear in the Recast.AI response in your code.

Tips

Entity

Definition

An entity is a keyword extracted from an expression. We automatically detect 31 different entities such as datetimes, names, locations, etc. We call them Gold entities. But you are not limited to these Gold entities: you can also tag your own custom entities to detect keywords depending on your bot context, such as metro stations if you are building a transport assistant. To bring you a precise service with a true added value, we are enriching each of our Gold entities with core information.

Example

When « tomorrow » is detected in a sentence, a formatted version of the datetime that you can use as a reply is returned.

datetime json

Tips

Gazette

Definition

A gazette is a list of words that belong to an entity. You can define your own gazettes for your custom entities to improve the quality of the entity recognition

A gazette can either be open or closed. An open gazette will be used as an additional information for the named entity recognition. A closed gazette ensure that no word can be recognized as an entity if it doesn’t appear in the gazette.

For each gazette, you can define a strictness parameter that will be used to determine if a word matches the gazette.

Tips

"value";"language"
"example value";"en"
"example de valeur;"fr"
value language
“value” “language isocode”

Language

Definition

We currently understand French and English. Bots are multilingual, which means you can speak both languages with the same bot. To do that, add expressions in both language tabs located in each intents. Recast.AI will automatically detect what the input language is so you can adapt your answers.

Tips

Bot Builder lexic

Action

An action is a step in your conversation. It is triggered by a user input and completed by a bot response.

Create an action

First and foremost an action is a wrapper around an intent.
Select an intent you’ve created before. One action is created with one intent.

create action

You can create as many actions as you want with the same intent:

multiple actions

It’s important to name your action, to identify where your user is in your conversation flow. By default, the name of your action is the intent slug associated to your action.

Edit your action slug:

edit click

Once the configuration modal is opened, click on the pen on the right of your intent name, edit it and press enter.

edit slug

This action slug appears in the JSON we return to you when you run your bot.

Check the Code section to have more information.

End of your conversation:

If you check the radio button “This is the end of my conversation” in an action, each time the user will trigger the action, it will reset the conversation and the memory of your bot for this user.

A link connects actions to create your conversation flow.

A green link creates an action flow where the user is guided in one direction, but remains free to start at any other step of the conversation.

conversation flow A user can say hello or order a sandwitch first. It’s up to him!

A red link creates an action flow where the user has to follow a defined path.

required If a user asks about the payment procedure but hasn’t make an order before, your bot will ask him to complete the order first.

color Toggle the colored dot to select the type of link you want to create. Click on the round output connector of your action.

link actions

Then click on one of the orange round connector on the other card to complete the link

link ok

Click on the link, then toggle the color tool-box to change it.

To delete a link, click on it and then click either on the “trash” button in the tool-box or your delete key.

Special case:

An action can’t have two different colored links as an input.

forbidden

Your conversation will be smarter with this flow:

do this

A link condition is set when an action requires more than one action. It will only appear on a red link.

AND / OR

You have two possible link conditions, AND and OR.

and

Here, the user will pay-flower after he order-flower AND set a delivery-adress.

or

Here, he’ll have to confirm OR cancel his order to pay it.

By clicking on the red piece, you can change the conditional type, from AND to OR - or - from OR to AND.

Notion

A notion is a required information needed by your bot to complete an action and continue the conversation.

How it works?

A notion is a wrapper around an entity. One that you’ve created before or that Recast.AI detects automatically.

These entities are extracted from you user input.

My birthday is 21st November

Let’s say you’ve configured your bot with one notion:

datetime

If a datetime is detected in your user input, it is stored in your bot memory as a “birthdate”. We call this memory case an alias. You may want to have the same entity detected twice, so you will associate the entity with two different aliases to make the difference. And you will be able to trigger some action and reuse this memory.

Create a notion:

add notion

Hover over your action and click on the pen, then click on the button: ADD NOTION

Select an entity in the list or search for one.

add entity

Add an alias to your notion. It can be the same as your entity name, it’s up to you!

add entity 2

You can re-use the same notion alias in different actions. If you do so, it will refer to the same information in your bot, at any step of your conversation flow.

notion memory

Create a notion with multiple entities

mutli entities

You can add as many entities as you want in one notion. It will be processed like an “OR” condition.

notion or

Here the bot needs to have a cheese OR a vegetable to complete the action and continue the conversation.

Notion condition

Notion conditions can be added to actions to restrict the path of the conversation flow of your bot. There are 2 types of conditions: “is” and “is not”.

“IS” condition

The “IS” condition allows conversation to go through the action only if the notion is equal to one on the list.

mutli entities

This action will be triggered if the notion called “name” equals “victor” or “georges”.

“IS NOT” condition

The “IS NOT” condition allows conversation to go through the action only if the notion is not equal to one on the list.

mutli entities

This action will be triggered if the notion called “name” does not equal “victor” or “georges”.

Multiple notion conditions

Multiple notion conditions can be added to an action. That means the action will be triggered if all conditions are completed.

mutli entities

This action will be triggered if the notion called “name” equals “victor” or “georges” AND the notion called “color” equals “blue”. If the notion called “name” equals “victor” and the notion called “color” equals “red”, this action will not be triggered in the conversation flow.

Create a notion condition

To create a condition, a notion must be added to one of the bot action.

mutli entities

Hover over your action and click on the pen, then click on the button: “ADD CONDITION” button

mutli entities

Select which type of notion condition you want to add to this action: “is” or “is not”.

mutli entities

Write one or more choices for this notion condition.

mutli entities

Make an IF/ELSE branch

Notion conditions allow you to create an IF/ELSE branch between actions. In this example, the “get-name” action gets the “name” notion from user input:

mutli entities

Notion condition of the “if” action:

mutli entities

Notion condition of the “else” action:

mutli entities

After triggering the “get-name” action, the conversation will go through the “if” action if name is “victor” or “georges”. Otherwise, conversation will go through “else” action.

Reply

Your have to set all your bot replies. Your bot responds differently if it’s missing mandatory notions or if a required action is incomplete.

Add a reply

For each action, click on the pen icon and click on the tab “Bot Replies”.

replies

You always have an If this action is done section. It’s the final reply that guides the conversation to the next action.

You can have as many sections as you have notions and actions required by your current step

replies details

The more replies you add, the more your bot replies randomly.

Add variables:

variables

You can add variables in your replies, by clicking on the button ADD A VARIABLE, or by typing {{ }}.

A variable can be a notion name or directly an entity. We replace it with the value of your notion or entity detected. If it’s a gold entity, you can use the enrichement fields like {{location.lat}} to have the location latitude.

Memory

Your bot has a memory used to store notions extracted from your user’s input during a conversation. The memory depens on how you configure the notions of your bot.

Init

At the beginning of a conversation, an empty memory is created. Each time your bot detects an entity needed by a notion, it is stored in the memory.

Memory structure

The memory is an object of notions. You will find each notion you have defined for each action.

Object keys will be your notions aliases.

You have two actions with one notion in each of them.

{
  "memory": {
    "birthdate": null,
    "city": null
  }
}

memory example

Your memory will be like the one displayed on the right-hand side:

{
  "memory":{
    "birthdate": null,
    "city": {
      "formatted": "Paris, France",
      "lat": 48.856614,
      "lng": 2.3522219,
      "type": "locality",
      "place": "ChIJD7fiBh9u5kcRYJSMaMOCCwQ",
      "raw": "Paris",
      "confidence": 0.99
    }
  }
}

If a user says to your bot “I live in Paris”, the bot stores the information like this:

Override

request
  .put('https://api.recast.ai/v2/converse')
  .send({
    conversation_token: 'CONVERSATION_TOKEN',
    memory: {
      birthdate: {
        formatted: 'Thursday, 06 October 2016 at 09:00:00 AM',
      }
    }
  })
  .set('Authorization', 'Token REQUEST_TOKEN')
  .end(function(err, res) {
    console.log(res);
  })

It may happen that you, the bot developer, have access to information that the bot doesn’t know, such as a GPS location from a mobile phone. In that case, you need to update the bot’s memory so it can act on this information.

When you call

PUT https://api.recast.ai/v2/converse

with a memory parameter, you can override the memory to change information in a given conversation.

Each key and information you will put in the memory will override those the bot could have filled.

Reset

You can trigger a memory reset when an action is done. To do that, check “End of conversation” in the modal configuration of an action.

end conversation

Alternatively, you can call

PUT https://api.recast.ai/v2/converse

without the memory parameter to reset the memory on the default state.

Code

Each time you receive a user input, call this endpoint to guide the conversation

POST https://api.recast.ai/v2/converse

Converse

request
  .post('https://api.recast.ai/v2/converse')
  .send({
    text: 'YOUR_USER_INPUT',
    conversation_token: 'CONVERSATION_TOKEN',
  })
  .set('Authorization', 'Token REQUEST_TOKEN')
  .end(function(err, res) {
    console.log(res)
  })

The text parameter is basically your user’s input

The request token is in your bot settings (the little gear icon near the console)

The conversation token

Each time you want to start a new conversation, just call /converse without the optional conversation_token parameter. In the response, you’ll receive a new conversation_token, corresponding to a fresh new conversation.

Then, you can pass it to the following /converse calls to continue the previously started conversation and benefit from the information already extracted.

The response

.end(function(err, res) {
  if (res.action && res.action.done) {
    // Do some things, like call an external API...
  }
})

You can test the return of this endpoint in the console on the left, by clicking on this: {} in each message.

  .end(function(err, res) {
    console.log(res.replies[0])
  })

In the JSON, you will find a key action. It will indicate which action the user is currently doing. If this action is complete, the boolean done will be true.

The most important field in the JSON is the replies field. Depending the way you’ve configured your bot, you will need to print one reply or more. The first reply will always be a sentence coming from the current action. The next replies come from the following actions.

And finally, you can find the bot memory in the JSON memory key. You will find all the necessary information here.

Quick start

To start easily, we recommand you to use one of our starter kits. You can find all of them here.

API

Requests

Versioning

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

The current version for the API is: v2

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.

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

With your request token, you can make text, voice file, image file and websocket requests

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.

/bots

{
  "id": 1,
  "name": "My bot",
  "slug": "my-bot",
  "description": "My first bot",
  "public": true,
  "strictness": 65,
  "request_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "developer_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "children_count": 2,
  "parent": {},
  "intents": [],
  "actions": [],
  "gazettes": [],
  "language": {}
}

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 
public Boolean Is the bot public?
strictness Integer The bot strictness 
request_token String A 32-character unique token  Only for your own bot
developer_token String A 32-character unique token  Only for your own bot
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
intents Array of Intent The bot ligth intents
actions Array of Action The bot light actions
gazettes Array of Gazette The bot light gazettes
language Language The bot primary language

Light 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 
public Boolean Is the bot public?
request_token String A 32-character unique token  Only for your own bot
developer_token String A 32-character unique token  Only for your own bot
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

Showing a bot

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -X GET "https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG"
require 'httparty'
require 'json'

result = HTTParty.get("https://api.recast.ai/v2/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/v2/users/$USER_SLUG/bots/$BOT_SLUG',
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)
var request = require('superagent');

request
  .get('https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG')
  .send()
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end(function(err, res) {
    console.log(res);
  });

GET https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG

This call returns a light bot 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

Updating a bot

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -H 'Content-Type: application/json' \
     -d '{"name":NAME,"description":DESCRIPTION,"strictness":STRICTNESS}" \
     -X PUT "https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG"
require 'httparty'
require 'json'

result = HTTParty.put("https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG",
  body: { name: NAME, description: DESCRIPTION, strictness: STRICTNESS },
  headers: { 'Authorization' => 'Token DEVELOPER_TOKEN' }
)

puts JSON.parse(result.body)
import requests

response = requests.put('https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG',
  json={'name': NAME, 'description': DESCRIPTION, 'strictness': STRICTNESS},
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)
var request = require('superagent');

request
  .put('https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG')
  .send({
    name: NAME,
    description: DESCRIPTION,
    strictness: STRICTNESS
  })
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end(function(err, res) {
    console.log(res);
  });

PUT https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG

Parameters Type Description  Constraints
name String The bot name Not blank
description String The bot description
strictness Integer The bot strictness Only integer, greater than or equal to 0, less than or equal to 100, default: 0
public Boolean Whether the bot is public or not
language Language The bot language A valid language, with slug accessible

This call returns a bot model in results variable.

Indexing a bot’s entities

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -X GET "https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG/entities"
require 'httparty'
require 'json'

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

puts JSON.parse(result.body)
import requests

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

print(response.text)
var request = require('superagent');

request
  .get('https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG/entities')
  .send()
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end(function(err, res) {
    console.log(res);
  });

GET https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_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

/intents

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

This endpoint manages intents.

Intent model

Variable Type Description Constraints
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 Constraints
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/v2/users/$USER_SLUG/bots/$BOT_SLUG/intents"
require 'httparty'
require 'json'

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

puts JSON.parse(result.body)
import requests

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

print(response.text)
var request = require('superagent');

request
  .get('https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG/intents')
  .send()
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end(function(err, res) {
    console.log(res);
  });

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

Showing an intent

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -X GET "https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG/intents/$INTENT_SLUG"
require 'httparty'
require 'json'

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

puts JSON.parse(result.body)
import requests

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

print(response.text)
var request = require('superagent');

request
  .get('https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG/intents/$INTENT_SLUG')
  .send()
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end(function(err, res) {
    console.log(res);
  });

GET https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG/intents/$INTENT_SLUG

This call returns an intent model in results variable.

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/v2/users/$USER_SLUG/bots/$BOT_SLUG/intents"
require 'httparty'
require 'json'

result = HTTParty.post("https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG/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/v2/users/$USER_SLUG/bots/$BOT_SLUG/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)
var request = require('superagent');

request
  .post('https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG/intents')
  .send({
    name: NAME,
    description: DESCRIPTION,
    expressions: [
      {source: SOURCE, language:{isocode: ISOCODE}},
      {source: SOURCE, language:{isocode: ISOCODE}}
    ]
  })
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end(function(err, res) {
    console.log(res);
  });

POST https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG/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

This call returns an intent model in results variable.

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/v2/users/$USER_SLUG/bots/$BOT_SLUG/intents/$INTENT_SLUG"
require 'httparty'
require 'json'

result = HTTParty.put("https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG/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/v2/users/$USER_SLUG/bots/$BOT_SLUG/intents/$INTENT_SLUG',
  json={'name': NAME, 'description': DESCRIPTION},
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)
var request = require('superagent');

request
  .put('https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG/intents/$INTENT_SLUG')
  .send({
    name: NAME,
    description: DESCRIPTION
  })
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end(function(err, res) {
    console.log(res);
  });

PUT https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG/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.

Deleting an intent

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -X DELETE "https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG/intents/$INTENT_SLUG"
require 'httparty'
require 'json'

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

puts JSON.parse(result.body)
import requests

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

print(response.text)
var request = require('superagent');

request
  .delete('https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG/intents/$INTENT_SLUG')
  .send()
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end(function(err, res) {
    console.log(res);
  });

DELETE https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG/intents/$INTENT_SLUG

This call does not return any content.

Indexing an intent’s entities

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -X GET "https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG/intents/$INTENT_SLUG/entities"
require 'httparty'
require 'json'

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

puts JSON.parse(result.body)
import requests

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

print(response.text)
var request = require('superagent');

request
  .get('https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG/intents/$INTENT_SLUG/entities')
  .send()
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end(function(err, res) {
    console.log(res);
  });

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

/expressions

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

This endpoint manages expressions.

Expression model

Variable Type Description Constraints
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 Constraints
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/v2/users/$USER_SLUG/bots/$BOT_SLUG/intents/$INTENT_SLUG/expressions"
require 'httparty'
require 'json'

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

puts JSON.parse(result.body)
import requests

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

print(response.text)
var request = require('superagent');

request
  .get('https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG/intents/$INTENT_SLUG/expressions')
  .send()
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end(function(err, res) {
    console.log(res);
  });

GET https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG/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 The language of the expressions Optional, either fr or en

Showing an expression

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -X GET "https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG/intents/$INTENT_SLUG/expressions/$EXPRESSION_ID"
require 'httparty'
require 'json'

result = HTTParty.get("https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG/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/v2/users/$USER_SLUG/bots/$BOT_SLUG/intents/$INTENT_SLUG/expressions/$EXPRESSION_ID',
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)
var request = require('superagent');

request
  .put('https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG/intents/$INTENT_SLUG/expressions/$EXPRESSION_ID')
  .send()
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end(function(err, res) {
    console.log(res);
  });

GET https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG/intents/$INTENT_SLUG/expressions/$EXPRESSION_ID

This call returns an expression model in results variable.

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/v2/users/$USER_SLUG/bots/$BOT_SLUG/intents/$INTENT_SLUG/expressions"
require 'httparty'
require 'json'

result = HTTParty.post("https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG/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/v2/users/$USER_SLUG/bots/$BOT_SLUG/intents/$INTENT_SLUG/expressions',
  json={'source': SOURCE, 'language': {'isocode': ISOCODE}},
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)
var request = require('superagent');

request
  .post('https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG/intents/$INTENT_SLUG/expressions')
  .send({
    source: SOURCE,
    language: {isocode: ISOCODE}
  })
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end(function(err, res) {
    console.log(res);
  });

POST https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG/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.

Bulk Creating expressions

curl -H "Authorization: Token DEVELOPER_TOKEN" \                                                                                                                                                130
     -H 'Content-Type: application/json' \
     -d '{"expressions":[{"source":SOURCE,"language":{"isocode":ISOCODE}},{"source":SOURCE,"language":{"isocode":ISOCODE}}]}' \
     -X POST "https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG/intents/$INTENT_SLUG/expressions/bulk_create"
require 'httparty'
require 'json'

result = HTTParty.post("https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG/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/v2/users/$USER_SLUG/bots/$BOT_SLUG/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)
var request = require('superagent');

request
  .post('https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG/intents/$INTENT_SLUG/expressions/bulk_create')
  .send({
    expressions: [
      {source: SOURCE, language: {isocode: ISOCODE}},
      {source: SOURCE, language: {isocode: ISOCODE}}
      ]
  })
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end(function(err, res) {
    console.log(res);
  });

POST https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG/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

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

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/v2/users/$USER_SLUG/bots/$BOT_SLUG/intents/$INTENT_SLUG/expressions/$EXPRESSION_ID"
require 'httparty'
require 'json'

result = HTTParty.put("https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG/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/v2/users/$USER_SLUG/bots/$BOT_SLUG/intents/$INTENT_SLUG/expressions/$EXPRESSION_ID',
  json={'source': SOURCE, 'tokens': [TOKEN, TOKEN]},
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)
var request = require('superagent');

request
  .put('https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG/intents/$INTENT_SLUG/expressions/$EXPRESSION_ID')
  .send({
    source: SOURCE,
    tokens: [
      TOKEN,
      TOKEN
    ],
  })
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end(function(err, res) {
    console.log(res);
  });

PUT https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG/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.

Deleting an expression

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -X DELETE "https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG/intents/$INTENT_SLUG/expressions/$EXPRESSION_ID"
require 'httparty'
require 'json'

result = HTTParty.delete("https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG/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/v2/users/$USER_SLUG/bots/$BOT_SLUG/intents/$INTENT_SLUG/expressions/$EXPRESSION_ID',
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)
var request = require('superagent');

request
  .delete('https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG/intents/$INTENT_SLUG/expressions/$EXPRESSION_ID')
  .send()
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end(function(err, res) {
    console.log(res);
  });

DELETE https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG/intents/$INTENT_SLUG/expressions/$EXPRESSION_ID

This call does not return any content.

/tokens

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

This endpoint manages tokens.

Token model

Variable Type Description Constraints
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 Constraints
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 Constraints
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/v2/entities"
require 'httparty'
require 'json'

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

puts JSON.parse(result.body)
import requests

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

print(response.text)
var request = require('superagent');

request
  .get('https://api.recast.ai/v2/entities')
  .send()
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end(function(err, res) {
    console.log(res);
  });

GET https://api.recast.ai/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/v2/entities"
require 'httparty'
require 'json'

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

puts JSON.parse(result.body)
import requests

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

print(response.text)
var request = require('superagent');

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

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

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

Indexing logs

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -X GET "https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG/logs"
require 'httparty'
require 'json'

result = HTTParty.get("https://api.recast.ai/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/v2/users/$USER_SLUG/bots/$BOT_SLUG/logs',
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)
var request = require('superagent');

request
  .get('https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG/logs')
  .send()
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end(function(err, res) {
    console.log(res);
  });

GET https://api.recast.ai/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
filter String The language and/or status of the logs Optional, either fr or en and matched, mismatched, archived
Each filter should be coma-separated

Showing a log

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -X GET "https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG/logs/$LOG_ID"
require 'httparty'
require 'json'

result = HTTParty.get("https://api.recast.ai/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/v2/users/$USER_SLUG/bots/$BOT_SLUG/logs/$LOG_ID',
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)
var request = require('superagent');

request
  .get('https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG/logs/$LOG_ID')
  .send()
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end(function(err, res) {
    console.log(res);
  });

GET https://api.recast.ai/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/v2/users/$USER_SLUG/bots/$BOT_SLUG/logs/$LOG_ID"
require 'httparty'
require 'json'

result = HTTParty.delete("https://api.recast.ai/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/v2/users/$USER_SLUG/bots/$BOT_SLUG/logs/$LOG_ID',
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)
var request = require('superagent');

request
  .delete('https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG/logs/$LOG_ID')
  .send()
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end(function(err, res) {
    console.log(res);
  });

DELETE https://api.recast.ai/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/v2/users/$USER_SLUG/bots/$BOT_SLUG/logs/bulk_destroy"
require 'httparty'
require 'json'

result = HTTParty.post("https://api.recast.ai/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/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)
var request = require('superagent');

request
  .post('https://api.recast.ai/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(function(err, res) {
    console.log(res);
  });

POST https://api.recast.ai/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/v2/users/$USER_SLUG/bots/$BOT_SLUG/gazettes"
require 'httparty'
require 'json'

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

puts JSON.parse(result.body)
import requests

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

print(response.text)
var request = require('superagent');

request
  .get('https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG/gazettes')
  .send()
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end(function(err, res) {
    console.log(res);
  });

GET https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG/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 The openess and/or status of the gazette Optional, either open or closed and activated or deactivated
Each filter should be coma-separated

Showing a gazette

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -X GET "https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG/gazettes/$GAZETTE_SLUG"
require 'httparty'
require 'json'

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

puts JSON.parse(result.body)
import requests

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

print(response.text)
var request = require('superagent');

request
  .get('https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG/gazettes/$GAZETTE_SLUG')
  .send()
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end(function(err, res) {
    console.log(res);
  });

GET https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG/gazettes/$GAZETTE_SLUG

This call returns a gazette model in results variable.

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}' \
     -X POST "https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG/gazettes"
require 'httparty'
require 'json'

result = HTTParty.post("https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG/gazettes",
  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.post('https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG/gazettes',
  json={'entity_id': ENTITY_SLUG, 'is_activated': IS_ACTIVATED, 'is_open': IS_OPEN, 'strictness': STRICTNESS},
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)
var request = require('superagent');

request
  .post('https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG/gazettes')
  .send({
    entity_id: ENTITY_SLUG,
    is_activated: IS_ACTIVATED,
    is_open: IS_OPEN,
    strictness: STRICTNESS,
  })
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end(function(err, res) {
    console.log(res);
  });

POST https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG/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

This call returns a gazette model in results variable.

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 POST "https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG/gazettes/$GAZETTE_SLUG"
require 'httparty'
require 'json'

result = HTTParty.post("https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG/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.post('https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG/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)
var request = require('superagent');

request
  .post('https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG/gazettes/$GAZETTE_SLUG')
  .send({
    entity_id: ENTITY_SLUG,
    is_activated: IS_ACTIVATED,
    is_open: IS_OPEN,
    strictness: STRICTNESS,
  })
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end(function(err, res) {
    console.log(res);
  });

PUT https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG/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.

Deleting a gazette

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -X DELETE "https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG/gazettes/$GAZETTE_SLUG"
require 'httparty'
require 'json'

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

puts JSON.parse(result.body)
import requests

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

print(response.text)
var request = require('superagent');

request
  .delete('https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG/gazettes/$GAZETTE_SLUG')
  .send()
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end(function(err, res) {
    console.log(res);
  });

DELETE https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG/gazettes/$GAZETTE_SLUG

This call does not return any content.

/synonyms

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

This endpoints manages synonyms.

Synonym model

Variable Type Description Constraints
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/v2/users/$USER_SLUG/bots/$BOT_SLUG/gazettes/$GAZETTE_SLUG/synonyms"
require 'httparty'
require 'json'

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

puts JSON.parse(result.body)
import requests

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

print(response.text)
var request = require('superagent');

request
  .get('https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG/gazettes/$GAZETTE_SLUG/synonyms')
  .send()
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end(function(err, res) {
    console.log(res);
  });

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

Showing a synonym

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -X GET "https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG/gazettes/$GAZETTE_SLUG/synonyms/$SYNONYM_SLUG"
require 'httparty'
require 'json'

result = HTTParty.get("https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG/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/v2/users/$USER_SLUG/bots/$BOT_SLUG/gazettes/$GAZETTE_SLUG/synonyms/$SYNONYM_SLUG',
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)
var request = require('superagent');

request
  .get('https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG/gazettes/$GAZETTE_SLUG/synonyms/$SYNONYM_SLUG')
  .send()
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end(function(err, res) {
    console.log(res);
  });

GET https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG/gazettes/$GAZETTE_SLUG/synonyms/$SYNONYM_SLUG

This call returns a synonym model in results variable.

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/v2/users/$USER_SLUG/bots/$BOT_SLUG/gazettes/$GAZETTE_SLUG/synonyms"
require 'httparty'
require 'json'

result = HTTParty.post("https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG/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/v2/users/$USER_SLUG/bots/$BOT_SLUG/gazettes/$GAZETTE_SLUG/synonyms',
  json={'value': VALUE, 'language': {'isocode': ISOCODE}},
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)
var request = require('superagent');

request
  .post('https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG/gazettes/$GAZETTE_SLUG/synonyms')
  .send({
    value: VALUE,
    language: { isocode: ISOCODE }
  })
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end(function(err, res) {
    console.log(res);
  });

POST https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG/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.

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/v2/users/$USER_SLUG/bots/$BOT_SLUG/gazettes/$GAZETTE_SLUG/synonyms/bulk_create"
require 'httparty'
require 'json'

result = HTTParty.post("https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG/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/v2/users/$USER_SLUG/bots/$BOT_SLUG/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)
var request = require('superagent');

request
  .post('https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG/gazettes/$GAZETTE_SLUG/synonyms/bulk_create')
  .send({
    synonyms: [
      {value: VALUE, language: {isocode: ISOCODE}},
      {value: VALUE, language: {isocode: ISOCODE}},
    ]
  })
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end(function(err, res) {
    console.log(res);
  });

POST https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG/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.

Updating 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/v2/users/$USER_SLUG/bots/$BOT_SLUG/gazettes/$GAZETTE_SLUG/synonyms/$SYNONYM_SLUG"
require 'httparty'
require 'json'

result = HTTParty.post("https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG/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.post('https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG/gazettes/$GAZETTE_SLUG/synonyms/$SYNONYM_SLUG',
  json={value: VALUE, language: {'isocode': ISOCODE}},
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)
var request = require('superagent');

request
  .post('https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG/gazettes/$GAZETTE_SLUG/synonyms/$SYNONYM_SLUG')
  .send({
    value: VALUE,
    language: { isocode: ISOCODE }
  })
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end(function(err, res) {
    console.log(res);
  });

PUT https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG/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.

Deleting a synonym

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -X DELETE "https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG/gazettes/$GAZETTE_SLUG/synonyms/$SYNONYM_SLUG"
require 'httparty'
require 'json'

result = HTTParty.delete("https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG/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/v2/users/$USER_SLUG/bots/$BOT_SLUG/gazettes/$GAZETTE_SLUG/synonyms/$SYNONYM_SLUG',
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)
var request = require('superagent');

request
  .delete('https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG/gazettes/$GAZETTE_SLUG/synonyms/$SYNONYM_SLUG')
  .send()
  .set('Authorization', 'Token DEVELOPER_TOKEN')
  .end(function(err, res) {
    console.log(res);
  });

DELETE https://api.recast.ai/v2/users/$USER_SLUG/bots/$BOT_SLUG/gazettes/$GAZETTE_SLUG/synonyms/$SYNONYM_SLUG

This call does not return any content.

/languages

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

This endpoint manages languages.

Language model

Variable Type Description Constraints
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_activated Boolean Is the language handled by the platform?

/converse (Text)

This endpoint retrieves all metadata and intents from a sentence.

curl -X POST -H "Authorization: Token REQUEST_TOKEN" \
     -d "text='Hello Recast',language='en'" \
     "https://api.recast.ai/v2/converse"
require 'httparty'
require 'json'

result = HTTParty.post("https://api.recast.ai/v2/converse",
  body: { text: 'Hello Recast', language: 'fr' },
  headers: { 'Authorization' => 'Token REQUEST_TOKEN' }
)

puts JSON.parse(result.body)
import requests

response = requests.post('https://api.recast.ai/v2/converse',
  json={'text': 'Hello Recast', 'language': 'en'},
  headers={'Authorization': 'Token REQUEST_TOKEN'}
)

print(response.text)
var request = require('superagent');

request
  .post('https://api.recast.ai/v2/converse')
  .send({
    text: 'Hello Recast',
    language: 'fr'
  })
  .set('Authorization', 'Token REQUEST_TOKEN')
  .end(function(err, res) {
    console.log(res);
  });

Text request works with any raw text.

POST https://api.recast.ai/v2/converse

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. Optional, must be ‘en’ or 'fr’, if not provided a language detection will be performed

Response

{
 "uuid": "dd881cfc-dbcd-492c-9e99-84a68f915e1b",
 "source": "I would like to order sushi",
 "replies": [
   "Would you like to take out or to be delivered?"
 ],
 "action": {
   "slug": "order",
   "done": true,
   "reply": "Would you like to take out or to be delivered?"
 },
 "next_actions": [],
 "memory": {
   "name": null,
   "adress": null,
   "food": {
     "value": "sushi",
     "raw": "sushi",
     "confidence": 0.8
   }
 },
 "entities": {
   "pronoun": [
     {
       "person": 1,
       "number": "singular",
       "gender": "unknown",
       "raw": "I",
       "confidence": 0.95
     }
   ],
   "food": [
     {
       "value": "sushi",
       "raw": "sushi",
       "confidence": 0.8
     }
   ]
 },
 "intents": [
   {
     "confidence": 0.94,
     "slug": "order"
   }
 ],
 "conversation_token": "4c62a8b7addfa0a6b8b0b20ae8dce978",
 "language": "en",
 "timestamp": "2016-10-10T14:36:43.542475Z",
 "version": "2.4.0",
 "status": 200
}

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
replies Array of reply The replies we found, sorted by order
action Object The current action
action.slug String The slug of the current action
action.done Boolean If the action is finished or not
action.reply String What the bot will reply
next_actions Array of next_action The next_actions we found, sorted by order
next_action.slug String The slug of the next_action which matched
next_action.done Boolean If the next_action is finished or not
next_action.reply String What the bot will reply for this next_action
memory Object The content of all notion
entities Object Every keys are an array of entity, more infos in the glossary
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
conversation_token String The token of this conversation
language String The language detected (or given) from the processed sentence, follows the ISO 639-1 standard
timestamp String The UTC timestamp at the end of our processing, follows the ISO 8061 standard
version String The version of our JSON, follows the Semantic Versioning Specification
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:

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

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

/converse (voice file)

curl -X POST -H "Authorization: Token REQUEST_TOKEN" \
     -H "Content-Type: multipart/form-data" \
     -F "voice=@FILE;type=audio/wav" \
     -F "language=en" \
     "https://api.recast.ai/v2/converse"
require 'httparty'
require 'httmultiparty'
require 'json'

result = HTTMultiParty.post("https://api.recast.ai/v2/converse",
  body: { voice: File.new(FILE), language: 'fr' },
  headers: { 'Authorization' => 'Token REQUEST_TOKEN' }
)

puts JSON.parse(result.body)
import requests

response = requests.post('https://api.recast.ai/v2/converse',
  files={'voice': open(FILE, 'rb'), 'language': 'fr'},
  headers={'Authorization': 'Token REQUEST_TOKEN'}
)

print(response.text)
// Only for javascript, Content-Type needs to be set to undefined.
var request = require('superagent');

request
  .post('https://api.recast.ai/v2/converse')
  .attach('voice', FILE)
  .send({
      language: 'fr'
  })
  .set('Authorization', 'Token REQUEST_TOKEN')
  .set('Content-Type', '')
  .end(function(err, res) {
    console.log(res);
  });

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

POST https://api.recast.ai/v2/converse (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’ or 'fr’

Response

{
 "uuid": "dd881cfc-dbcd-492c-9e99-84a68f915e1b",
 "source": "I would like to order sushi",
 "replies": [
   "Would you like to take out or to be delivered?"
 ],
 "action": {
   "slug": "order",
   "done": true,
   "reply": "Would you like to take out or to be delivered?"
 },
 "next_actions": [],
 "memory": {
   "name": null,
   "adress": null,
   "food": {
     "value": "sushi",
     "raw": "sushi",
     "confidence": 0.8
   }
 },
 "entities": {
   "pronoun": [
     {
       "person": 1,
       "number": "singular",
       "gender": "unknown",
       "raw": "I",
       "confidence": 0.95
     }
   ],
   "food": [
     {
       "value": "sushi",
       "raw": "sushi",
       "confidence": 0.8
     }
   ]
 },
 "intents": [
   {
     "confidence": 0.94,
     "slug": "order"
   }
 ],
 "conversation_token": "4c62a8b7addfa0a6b8b0b20ae8dce978",
 "language": "en",
 "timestamp": "2016-10-10T14:36:43.542475Z",
 "version": "2.4.0",
 "status": 200
}

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
replies Array of reply The replies we found, sorted by order
action Object The current action
action.slug String The slug of the current action
action.done Boolean If the action is finished or not
action.reply String What the bot will reply
next_actions Array of next_action The next_actions we found, sorted by order
next_action.slug String The slug of the next_action which matched
next_action.done Boolean If the next_action is finished or not
next_action.reply String What the bot will reply for this next_action
memory Object The content of all notion
entities Object Every keys are an array of entity, more infos in the glossary
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
conversation_token String The token of this conversation
language String The language detected (or given) from the processed sentence, follows the ISO 639-1 standard
timestamp String The UTC timestamp at the end of our processing, follows the ISO 8061 standard
version String The version of our JSON, follows the Semantic Versioning Specification
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:

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

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

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

/converse (PUT)

This endpoint update memory.

curl -X PUT -H "Authorization: Token REQUEST_TOKEN" \
     -d "conversation_token=CONVERSATION_TOKEN" \
     "https://api.recast.ai/v2/converse"
require 'httparty'
require 'json'

result = HTTParty.put("https://api.recast.ai/v2/converse",
  body: { conversation_token: CONVERSATION_TOKEN },
  headers: { 'Authorization' => 'Token REQUEST_TOKEN' }
)

puts JSON.parse(result.body)
import requests

response = requests.put('https://api.recast.ai/v2/converse',
  json={'conversation_token': CONVERSATION_TOKEN},
  headers={'Authorization': 'Token REQUEST_TOKEN'}
)

print(response.text)
var request = require('superagent');

request
  .put('https://api.recast.ai/v2/converse')
  .send({
    conversation_token: CONVERSATION_TOKEN,
  })
  .set('Authorization', 'Token REQUEST_TOKEN')
  .end(function(err, res) {
    console.log(res);
  });

PUT https://api.recast.ai/v2/converse

Name Type Description Constraints
conversation_token String This the token of your conversation Required, not empty, not blank.

Response

{
  "results": {
    "memory": {
    "loc": null
    },
  "conversation_token": "fdec44b5ea35cd73b27e7190a6c41587",
  "timestamp": "2016-10-10T13:30:12.000Z",
  "version": "2.4.0",
  "status":200
  },
  "message": "Converses rendered with success"
}

We return a JSON containing your memory and actionable data extracted from the sentence.

Name Type Description
memory Object The content of all notion
conversation_token String The token of this conversation
timestamp String The UTC timestamp at the end of our processing, follows the ISO 8061 standard
version String The version of our JSON, follows the Semantic Versioning Specification
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:

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

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

/converse (DELETE)

This endpoint update memory.

curl -X DELETE -H "Authorization: Token REQUEST_TOKEN" \
     -d "conversation_token=CONVERSATION_TOKEN" \
     "https://api.recast.ai/v2/converse"
require 'httparty'
require 'json'

result = HTTParty.delete("https://api.recast.ai/v2/converse",
  body: { conversation_token: CONVERSATION_TOKEN },
  headers: { 'Authorization' => 'Token REQUEST_TOKEN' }
)

puts JSON.parse(result.body)
import requests

response = requests.delete('https://api.recast.ai/v2/converse',
  json={'conversation_token': CONVERSATION_TOKEN},
  headers={'Authorization': 'Token REQUEST_TOKEN'}
)

print(response.text)
var request = require('superagent');

request
  .delete('https://api.recast.ai/v2/converse')
  .send({
    conversation_token: CONVERSATION_TOKEN,
  })
  .set('Authorization', 'Token REQUEST_TOKEN')
  .end(function(err, res) {
    console.log(res);
  });

DELETE https://api.recast.ai/v2/converse

Name Type Description Constraints
conversation_token String This the token of your conversation Required, not empty, not blank.

Response

{
  "results": {
    "memory": {
    "loc": null
    },
  "conversation_token": "fdec44b5ea35cd73b27e7190a6c41587",
  "timestamp": "2016-10-10T13:30:12.000Z",
  "version": "2.4.0",
  "status":200
  },
  "message": "Converses rendered with success"
}

We return a JSON containing your memory and actionable data extracted from the sentence.

Name Type Description
memory Object The content of all notion
conversation_token String The token of this conversation
timestamp String The UTC timestamp at the end of our processing, follows the ISO 8061 standard
version String The version of our JSON, follows the Semantic Versioning Specification
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:

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

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

/request (text)

This endpoint retrieves all metadata and intents from a sentence.

curl -X POST -H "Authorization: Token REQUEST_TOKEN" \
     -d "text=Hello Recast" \
     -d "language=en" \
     "https://api.recast.ai/v2/request"
require 'httparty'
require 'json'

result = HTTParty.post("https://api.recast.ai/v2/request",
  body: { text: 'Hello Recast', language: 'fr' },
  headers: { 'Authorization' => 'Token REQUEST_TOKEN' }
)

puts JSON.parse(result.body)
import requests

response = requests.post('https://api.recast.ai/v2/request',
  json={'text': 'Hello Recast', 'language': 'en'},
  headers={'Authorization': 'Token REQUEST_TOKEN'}
)

print(response.text)
var request = require('superagent');

request
  .post('https://api.recast.ai/v2/request')
  .send({
    text: 'Hello Recast',
    language: 'fr'
  })
  .set('Authorization', 'Token REQUEST_TOKEN')
  .end(function(err, res) {
    console.log(res);
  });

Text request works with any raw text.

POST https://api.recast.ai/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. Optional, must be 'en’ or 'fr’, 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",
    "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
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:

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

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

/request (voice file)

curl -X POST -H "Authorization: Token REQUEST_TOKEN" \
     -H "Content-Type: multipart/form-data" \
     -F "voice=@FILE;type=audio/wav" \
     -F "language=en" \
     "https://api.recast.ai/v2/request"
require 'httparty'
require 'httmultiparty'
require 'json'

result = HTTMultiParty.post("https://api.recast.ai/v2/request",
  body: { voice: File.new(FILE), language: 'fr' },
  headers: { 'Authorization' => 'Token REQUEST_TOKEN' }
)

puts JSON.parse(result.body)
import requests

response = requests.post('https://api.recast.ai/v2/request',
  files={'voice': open(FILE, 'rb'), 'language': 'fr'},
  headers={'Authorization': 'Token REQUEST_TOKEN'}
)

print(response.text)
// Only for javascript, Content-Type needs to be set to undefined.
var request = require('superagent');

request
  .post('https://api.recast.ai/v2/request')
  .attach('voice', FILE)
  .send({
      language: 'fr'
  })
  .set('Authorization', 'Token REQUEST_TOKEN')
  .set('Content-Type', '')
  .end(function(err, res) {
    console.log(res);
  });

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

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

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",
    "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
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:

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

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

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

/request (image file)

curl -X POST -H "Authorization: Token REQUEST_TOKEN" \
     -H "Content-Type: multipart/form-data" \
     -F "image=@IMAGE_FILE;type=image/jpg" \
     "https://api.recast.ai/v2/request"
require 'httparty'
require 'httmultiparty'
require 'json'

result = HTTMultiParty.post("https://api.recast.ai/v2/request",
  body: { image: File.new(IMAGE_FILE) },
  headers: { 'Authorization' => 'Token REQUEST_TOKEN' }
)

puts JSON.parse(result.body)
import requests

response = requests.post('https://api.recast.ai/v2/request',
  files={'image': open(IMAGE_FILE, 'rb')},
  headers={'Authorization': 'Token REQUEST_TOKEN'}
)

print(response.text)
// Only for javascript, Content-Type needs to be set to undefined.
var request = require('superagent');

request
  .post('https://api.recast.ai/v2/request')
  .attach('image', IMAGE_FILE)
  .set('Authorization', 'Token REQUEST_TOKEN')
  .set('Content-Type', '')
  .end(function(err, res) {
    console.log(res);
  });

Image request works with .jpg, .png, .gif and .bmp files. You should send those images with multipart/form-data form (mostly automatically done). In addition, we handle urls sent as a string.

POST https://api.recast.ai/v2/request (multipart)

Name Type Description Constraints
image data This is your user image input. Required, not empty, no empty file, .jpg, .png, .gif and .bmp files or a url. max size: 5MB

Response

{
  "results": {
    "uuid": "21ec79d8-3865-40e3-be8b-f31d040efed8",
    "source": "hedgehog.jpg",
    "tags": [
        {
            "slug": "hedgehog",
            "confidence": 0.98268622
        },
        {
            "slug": "erinaceidae",
            "confidence": 0.98184586
        },
        {
            "slug": "domesticated hedgehog",
            "confidence": 0.96337247
        },
        {
            "slug": "mammal",
            "confidence": 0.94819778
        },
        {
            "slug": "vertebrate",
            "confidence": 0.93340057
        },
        {
            "slug": "fauna",
            "confidence": 0.8455444
        },
        {
            "slug": "virginia opossum",
            "confidence": 0.62462914
        },
        {
            "slug": "echidna",
            "confidence": 0.61264831
        }
    ],
    "version": "2.4.0",
    "timestamp": "2017-01-16T10:17:46+01:00",
    "status": 200
  },
  "message": "Requests rendered with success"
}

We return a JSON containing your image path and tags extracted from the image

Name Type Description
uuid String The universally unique id for this request
source String The image path we processed
tags Array of tag The tags we found, sorted by confidence
tag.slug String The slug of the extracted tag
tag.confidence Float The confidence of the extracted tag
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:

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

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

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

/request (websocket)

Example only in Javascript
Example only in Javascript
Example only in Javascript
ws = new WebSocket('wss://api.recast.ai/v2/request');

ws.onopen = function () {
  ws.send(JSON.stringify(['authorization', 'REQUEST_TOKEN']).toString());
};

ws.onmessage = function (evt) {
  var res = JSON.parse(evt.data);
  if (res['step'] == 'authorization' && res['status'] == 'OK') {
    // Authentication succeeded
    beginStream();
  } else if (res['step'] == 'action' && res['type'] == 'analyze') {
    if (res['status'] == 'OK') {
      // Request succeeded and json response is in res['message']
    } else if (res['status'] == 'KO') {
      // Request failed and json error is in res['message']
    }
  } else {
    // All others response
    console.log(res);
  }
};

ws.onclose = function () {
};

function beginStream() {
  // Initialize microphone here
  while (recording) {
    ws.send(binary_sound_data);
  }
}

function sendRequest() {
  ws.send(JSON.stringify(['action', 'analyze', 'fr']).toString());
}

We provide access to our websocket server to allow developpers to directly stream audio speeches from their apps using built-in microphone of devices.

WEBSOCKET wss://api.recast.ai/v2/request

How to talk with our websocket server ?

You must follow these steps to talk with our websocket server :

  1. In ws.onopen function, send a “json-stringify” message through the websocket with your token : '["authorization", "your-token"]'.
  2. If your token is invalid, socket is closed and we send you back this message : '{"message":"Wrong token. You shall not pass.","step":"authorization","status":"KO"}'.
  3. Otherwise, we send you back this message : '{"message":"Valid token. You can send us speech datas.","step":"authorization","status":"OK"}'.
  4. Now, you can send us binary audio data. Take care about format. More info in the Binary audio data format.
  5. To analyze your audio data, send us this message: '["action", "analyze", "en"]'.
  6. After analyzing, we will send you back response. If it succeed, response['status'] will be OK. Otherwise, it will be KO.

Request

All requests must be “json-stringified” before sending them!

Send that kind of message : ['TYPE_OF_REQUEST', 'PARAMETER_OF_REQUEST'[, 'SECOND_PARAMTER_OF_REQUEST']]

Type of request First Parameter Second Parameter Description
action analyze fr or en Start to analyze sent speech, return response and close the websocket.
action close Close the websocket without analyze sent speech.
authorization your-token Ask for authorization to communicate.

To send binary audio data : Send us your binary data array directly. More info in the Binary audio data format.

Response

All our websocket responses have the same format. We send you back a json formatted string that you can parse.

Type of actions :

Step Type Possible status Description
connection nil OK, KO Sent back when websocket is initialized
authorization nil OK, KO Sent back after authorization request
action analyze OK, RUNNING, KO  Sent back after analyze request
action close OK, KO Sent back after close request
action unknown OK, KO Sent back after an unknown action request
request nil OK, KO Sent back when other data have been sent (audio, unknown, etc…)

Binary Audio Data format

You must send this data format for audio :

32bps, 44.1khz audio, mono

Programmatically, it’s a [-1.0,1.0] float array, without [].

Example : -0.543534645, 0.2142342342, 0.213234, -0.22342, ...

For more information, you can read our blog post about How a developer can work with audio files.

Constraints

If your request exceeds these limitations, we don’t allow you to send more binary audio data. Then, we analyze your speech and send you back the response.

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 liste 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",
  "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 coma (,)
chronology String, the point in time referenced by the datetime
Can be past, present, or future
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 coma (,)
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 coma (,)
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",
  "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, …
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.4.0

Here is the changelog for Recast.AI v2.4.0 (Croissant):

BOT BUILDER

PLATFORM

API

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
}

V1

2.3.1

Please find below the changelog for Recast.AI v2.3.1 (Croissant):

ENTITIES

2.3.0

Below is the changelog of Recast.AI v2.3.0 (Croissant):

PLATFORM

API

ENTITIES

2.2.0

Here is the Recast.AI v2.2.0’s changelog (Croissant):

BOT BUILDER

TRAIN

ENTITIES

2.1.4

Please find below the Recast.AI v2.1.4’s changelog (Croissant):

ENTITIES

BOT BUILDER

API

2.1.3

Recast.AI v2.1.3’s changelog (Croissant):

PLATFORM

ENTITIES

2.1.2

Below lies the changelog for Recast.AI v2.1.2 (Croissant):

BOT BUILDER

ENTITIES

2.1.1

Please find below the changelog for Recast.AI v2.1.1 (Croissant):

ENTITIES

2.1.0

Below is the changelog for Recast.AI v2.1.0 (Croissant):

PLATFORM

API

2.0.0

Please find the Recast.AI v2.0.0 (Croissant) changelog below:

PLATFORM

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": "Resource rendered with success"
}

ENTITIES

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

1.3.0

Here is the changelog for Recast.AI v1.3.0 (Chouquette):

LANGUAGES

ENTITIES

MISC

1.2.1

Here is the changelog for Recast.AI v1.2.1 (Chouquette):

API

1.2.0

Recast.AI v1.2.0 (Chouquette):

PLATFORM

ENTITIES

1.1.1

You can find below the changelog for Recast.AI v1.1.1 (Chouquette):

MISC

1.1.0

Changelog for Recast.AI v1.1.0 (Chouquette):

PLATFORM

INTENTS

JSON

MISC

1.0.1

Here is the changelog for Recast.AI v1.0.1 (Chouquette):

MISC

1.0.0

Below is the changelog for Recast.AI v1.0.0 (Chouquette):

NLP

ENTITIES

MISC