NAV
DOCS
Guides Tutorial API reference SDKs Login
Sign up
shell ruby python javascript

Introduction

Endpoints

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

Responses

Renders a collection

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

Renders a resource

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

Renders an error

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

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

Format

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

In results, we provide the answer of your request.

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

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

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

Status codes

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

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

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

Authentication

Your can access to Recast API with your bots’ tokens.

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.

SDKs

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

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

Language Latest version Repositories
Python 3.1.0 Github - Pypi
NodeJS 3.3.0 Github - NPM
Ruby 3.1.0 Github - Rubygems
PHP 3.1.0 Github - Packagist
Golang 3.2.0 Github - GoDoc
Android 4.1.0 Github - Bintray
Swift 4.0.0 Github - Cocoapods

Runtime API

Analyse endpoints

/request (text)

This endpoint retrieves all metadata and intents from a sentence.

curl -H "Authorization: Token REQUEST_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"text":"Hello Recast", "language":"en"}' \
     -X POST "https://api.recast.ai/v2/request"

require 'recastai'

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

puts response.raw

import recastai

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

print(response.raw)

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

request.analyseText('hello')
  .then(function(res) {
    var intent = res.intent()
    console.log(intent)
  })

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’s language Optional, must be a valid language isocode, if not provided a language detection will be performed

Response

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

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

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

Errors

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

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 -H "Authorization: Token REQUEST_TOKEN" \
     -H "Content-Type: multipart/form-data" \
     -F "voice=@hello.wav;type=audio/wav" \
     -F "language=en" \
     -X POST "https://api.recast.ai/v2/request"

require 'recastai'

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

puts response.raw

import recastai

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

print(response.raw)

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

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

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

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

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

Response

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

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

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

Errors

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

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

const ws = new WebSocket('wss://api.recast.ai/v2/request');

ws.onopen = () =>
  ws.send(JSON.stringify(['authorization', 'REQUEST_TOKEN']));

ws.onmessage = evt => {
  const 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.text);
  }
};

// When socket is closed
ws.onclose = () => {};

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

const sendRequest () =>
  ws.send(JSON.stringify(['action', 'analyze', 'fr']));

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.

Dialog endpoints

/dialog (text)

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

curl -H "Authorization: Token REQUEST_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"message": {"content":"Hello Recast","type":"text"}, "conversation_id": "CONVERSATION_ID"}' \
     -X POST "https://api.recast.ai/build/v1/dialog"

require 'recastai'

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

puts response

import recastai

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

print(response)

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

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

POST https://api.recast.ai/build/v1/dialog

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

Conversation Id

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

Response

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

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

The nlp section contains actionable data extracted from the input.

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

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

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

The conversation section contains information about the current conversation.

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

Errors

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

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:

Messages endpoints

Send a message

This endpoint sends a message on a specific conversation.

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

var request = require('superagent');

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

POST https://api.recast.ai/connect/v1/conversations/$CONVERSATION_ID/messages

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

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

Response

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

Errors

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

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:

Broadcast a message

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

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

var request = require('superagent');

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

POST https://api.recast.ai/connect/v1/messages

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

Response

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

Errors

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

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:

NLP API

/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

Training model

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

Bulk creation model

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

Showing a bot

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

require 'json'
require 'httparty'

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)

const request = require('superagent');

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

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

This call returns a bot model in results variable.

Updating a bot

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

require 'json'
require 'httparty'

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)

const 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((err, res) => console.log(res.text));

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 'json'
require 'httparty'

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)

const request = require('superagent');

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

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

Indexing a bot’s trainings

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

require 'json'
require 'httparty'

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

print(response.text)

const request = require('superagent');

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

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

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

Parameter Type  Description Constraints
page Integer The current page Optional, superior to 0
per_page Integer The number of items per page Optional, superior to 0
filter String A coma-separated list of languages’ isocodes Optional, valid isocode

Indexing a bot’s bulk creations

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

require 'json'
require 'httparty'

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

print(response.text)

const request = require('superagent');

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

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

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

Parameter Type  Description Constraints
page Integer The current page Optional, superior to 0
per_page Integer The number of items per page Optional, superior to 0
filter String A coma-separated list of languages’ isocodes Optional, valid isocode

/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
id Integer An unique intent id 
name String The intent name
slug String The intent slug 
description String The intent description 

Indexing intents

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

require 'json'
require 'httparty'

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)

const request = require('superagent');

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

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 'json'
require 'httparty'

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)

const 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((err, res) => console.log(res.text));

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 'json'
require 'httparty'

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)

const 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((err, res) => console.log(res.text));

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 'json'
require 'httparty'

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)

const 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((err, res) => console.log(res.text));

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 'json'
require 'httparty'

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)

const 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((err, res) => console.log(res.text));

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 'json'
require 'httparty'

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)

const 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((err, res) => console.log(res.text));

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 'json'
require 'httparty'

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)

const 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((err, res) => console.log(res.text));

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 A coma-separated list of languages’ isocodes Optional, valid isocode

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 'json'
require 'httparty'

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)

const 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((err, res) => console.log(res.text));

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 'json'
require 'httparty'

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)

const 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((err, res) => console.log(res.text));

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" \
     -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 'json'
require 'httparty'

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)

const 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((err, res) => console.log(res.text));

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 empty array 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 'json'
require 'httparty'

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)

const 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((err, res) => console.log(res.text));

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 'json'
require 'httparty'

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)

const 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((err, res) => console.log(res.text));

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 'json'
require 'httparty'

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)

const request = require('superagent');

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

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 'json'
require 'httparty'

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)

const request = require('superagent');

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

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 'json'
require 'httparty'

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)

const request = require('superagent');

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

GET https://api.recast.ai/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 A coma-separated list of languages’ isocodes, log status, and intents’ slugs Optional, valid isocode, valid status (matched, mismatched, archived), valid intent slug

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 'json'
require 'httparty'

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)

const 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((err, res) => console.log(res.text));

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 'json'
require 'httparty'

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)

const 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((err, res) => console.log(res.text));

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 'json'
require 'httparty'

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)

const 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((err, res) => console.log(res.text));

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 'json'
require 'httparty'

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)

const request = require('superagent');

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

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 A coma-separated list of gazettes’ states Optional, valid openess (open or closed), valid states (activated or deactivated)

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 'json'
require 'httparty'

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)

const 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((err, res) => console.log(res.text));

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

require 'json'
require 'httparty'

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, 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',
  json={'entity_id': ENTITY_SLUG, 'is_activated': IS_ACTIVATED, 'is_open': IS_OPEN, 'strictness': STRICTNESS, 'synonyms': [{'value': VALUE, 'language': {'isocode': ISOCODE}}, {'value': VALUE, 'language': {'isocode': ISOCODE}}]},
  headers={'Authorization': 'Token DEVELOPER_TOKEN'}
)

print(response.text)

const request = require('superagent');

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

POST https://api.recast.ai/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
synonyms Array of Synonym The gazette synonyms you want to create Optional, valid synonyms models with value and language accessible

This call returns a gazette model in results variable.

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 'json'
require 'httparty'

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)

const 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((err, res) => console.log(res.text));

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 'json'
require 'httparty'

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)

const 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((err, res) => console.log(res.text));

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 'json'
require 'httparty'

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)

const 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((err, res) => console.log(res.text));

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 'json'
require 'httparty'

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)

const 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((err, res) => console.log(res.text));

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 'json'
require 'httparty'

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)

const 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((err, res) => console.log(res.text));

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 'json'
require 'httparty'

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)

const 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((err, res) => console.log(res.text));

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 'json'
require 'httparty'

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)

const 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((err, res) => console.log(res.text));

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 'json'
require 'httparty'

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)

const 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((err, res) => console.log(res.text));

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_supported Boolean Is the language fully handled by the platform (advanced level) or not (standard level)?

Bot Builder API

/conversation_states

This endpoint manages conversations.

Conversation model

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

Show a conversation

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

require 'recastai'

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

puts response

import recastai

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

print(response)

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

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

GET https://api.recast.ai/build/v1/users/$USER_SLUG/bots/$BOT_SLUG/builders/v1/conversation_states/$CONVERSATION_ID

This call returns a conversation model in the results field.

Update a conversation

curl -H "Authorization: Token DEVELOPER_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"language": "en"}' \
     -X PUT "https://api.recast.ai/build/v1/users/$USER_SLUG/bots/$BOT_SLUG/builders/v1/conversation_states/$CONVERSATION_ID"

require 'recastai'

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

puts conversation

import recastai

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

print(conversation)

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

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

PUT https://api.recast.ai/build/v1/users/$USER_SLUG/bots/$BOT_SLUG/builders/v1/conversation_states/$CONVERSATION_ID

This call returns a conversation model in the results field.

Delete a conversation

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

require 'recastai'

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

puts response

import recastai

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

print(response)

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

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

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

Bot Connector API

/connectors

This endpoint manages connectors.

Connector model

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

Showing a connector

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

require 'json'
require 'httparty'

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

puts JSON.parse(result.body)

import requests

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

print(response.text)

const request = require('superagent');

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

GET https://api.recast.ai/connect/v1/connectors/${BOT_ID}

This call returns a connector model in the results field.

Updating a connector

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

require 'json'
require 'httparty'

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

puts JSON.parse(result.body)

import requests

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

print(response.text)

const request = require('superagent');

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

PUT https://api.recast.ai/connect/v1/connectors/${BOT_ID}

This call returns a connector model in the results field.

Parameter Type  Description Constraints
url String The connector’s endpoint Required, a valid url

Deleting a connector

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

require 'json'
require 'httparty'

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

puts JSON.parse(result.body)

import requests

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

print(response.text)

const request = require('superagent');

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

DELETE https://api.recast.ai/connect/v1/connectors/${BOT_ID}

This call does not return any content.

/channels

This endpoint manages channels.

Channel model

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

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

Showing a channel

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

require 'json'
require 'httparty'

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

puts JSON.parse(result.body)

import requests

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

print(response.text)

const request = require('superagent');

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

GET https://api.recast.ai/connect/v1/channels/$CHANNEL_SLUG

This call returns a channel model in the results field.

Indexing channels

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

require 'json'
require 'httparty'

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

puts JSON.parse(result.body)

import requests

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

print(response.text)

const request = require('superagent');

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

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

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

Creating a channel

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

require 'json'
require 'httparty'

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

puts JSON.parse(result.body)

import requests

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

print(response.text)

const request = require('superagent');

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

POST https://api.recast.ai/connect/v1/channels

This call returns a channel model in results variable.

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

Updating a channel

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

require 'json'
require 'httparty'

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

puts JSON.parse(result.body)

import requests

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

print(response.text)

const request = require('superagent');

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

PUT https://api.recast.ai/connect/v1/channels/$CHANNEL_SLUG

This call returns a channel model in results variable.

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

Deleting a channel

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

require 'json'
require 'httparty'

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

puts JSON.parse(result.body)

import requests

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

print(response.text)

const request = require('superagent');

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

DELETE https://api.recast.ai/connect/v1/channels/${CHANNEL_SLUG}

This call does not return any content.

/conversations

This endpoint manages conversations.

Conversation model

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

Showing a conversation

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

require 'json'
require 'httparty'

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

puts JSON.parse(result.body)

import requests

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

print(response.text)

const request = require('superagent');

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

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

This call returns a conversation model in results variable.

Indexing conversations

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

require 'json'
require 'httparty'

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

puts JSON.parse(result.body)

import requests

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

print(response.text)

const request = require('superagent');

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

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

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

Deleting a conversation

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

require 'json'
require 'httparty'

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

puts JSON.parse(result.body)

import requests

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

print(response.text)

const request = require('superagent');

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

DELETE https://api.recast.ai/connect/v1/conversations/$CONVERSATION_ID

This call does not return any content.

/participants

This endpoint manages participants.

Participant model

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

Showing a participant

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

require 'json'
require 'httparty'

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

puts JSON.parse(result.body)

import requests

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

print(response.text)

const request = require('superagent');

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

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

This call returns a participant model in results variable.

Indexing participants

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

require 'json'
require 'httparty'

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

puts JSON.parse(result.body)

import requests

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

print(response.text)

const request = require('superagent');

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

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

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

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",
  "state": "relative",
  "raw": "next Thursday",
  "confidence": 0.92
}
Entity Examples
datetime the next friday, today, September 7 2016, 12/12/1992, this evening, mid-november, eoy
Key Comments
formatted String, the written format of the datetime
iso String, the ISO-8601 standard of the datetime in UTC
accuracy String, the accuracy of the explicitly given datetime
Can be composed of one or more of year, month, week, day, halfday, hour, min, sec, now separated by a coma (,)
chronology String, the point in time referenced by the datetime
Can be past, present, or future
state String, the type of the datetime
Can be relative, or absolute
raw The raw value extracted from the sentence
confidence The confidence score between 0 and 1 for the detection

Distance

{
  "scalar": 24.0,
  "unit": "mi",
  "meters": 38624.159999999996,
  "raw": "twenty-four miles",
  "confidence": 0.97
}
Entity Examples
distance 20 meters, seven miles, ten kms, 156 centimeters, .8 foot
Key Comments
scalar Float, the countable
unit String, the quantifier
Can be km (kilometers), m (meters), mi (miles), ft (feet), in (inches), etc.
meters Float, the distance in meters
raw The raw value extracted from the sentence
confidence The confidence score between 0 and 1 for the detection

Duration

{
  "chrono": "02:00:00:00",
  "years": 0.005478757133798352,
  "months": 0.06575342465753424,
  "days": 2.0,
  "hours": 48.0,
  "minutes": 2880.0,
  "seconds": 172800.0,
  "raw": "two days",
  "confidence": 0.99
}
Entity Examples
duration five days, one year, 27 seconds, two days and 3 hours, 72 weeks
Key Comments
chrono String, a formatted representation of the duration in the form of :xx:xx:
years Float, the number of years in this duration
months Float, the number of months in this duration
days Float, the number of days in this duration
hours Float, the number of hours in this duration
minutes Float, the number of minutes in this duration
seconds Float, the number of seconds in this duration
raw The raw value extracted from the sentence
confidence The confidence score between 0 and 1 for the detection

Email

{
  "local": "paul",
  "tag": null,
  "domain": "recast.ai",
  "raw": "paul@recast.ai",
  "confidence": 0.99
}
Entity Examples
email hello@recast.ai, hello+devs@recast.ai, hello.you+devs@recast.co.uk
Key Comments
local String, the local part of the email
tag String, the tag part of the email
domain String, the domain of the email
raw The raw value extracted from the sentence
confidence The confidence score between 0 and 1 for the detection

Emoji

{
    "formatted": "happy",
    "feeling": "happy",
    "tags": [
        "eye",
        "face",
        "mouth",
        "open",
        "smile"
    ],
    "unicode": "U+1F604",
    "description": "smiling face with open mouth & smiling eyes",
    "raw": ":)",
    "confidence": 0.99
}
Entity Examples
emoji :), :heart:, 🙂
Key Comments
formatted String, the localized feeling of the emoji
feeling String, the expressed sentiment of the emoji
tags Array of String, a list of word related to the emoji
unicode String, the unicode codepoint of the emoji
description String, a fully-written sentence describing the emoji
raw The raw value extracted from the sentence
confidence The confidence score between 0 and 1 for the detection

IP

{
  "formatted": "Fontenay-sous-Bois, Île-de-France, FR",
  "lat": 48.8544,
  "lng": 2.4827,
  "raw": "82.121.114.213",
  "confidence": 0.99
}
Entity Examples
ip 127.0.0.1, 192.157.0.54, 153.34.43.0
Key Comments
formatted String, the full denomination of the ip’s location
lat Float, the latitude of the ip’s location
lng Float, the longitude of the ip’s location
raw The raw value extracted from the sentence
confidence The confidence score between 0 and 1 for the detection

Interval

{
  "begin": "2016-10-31T09:00:00Z",
  "end": "2016-11-06T09:00:00Z",
  "begin_accuracy": "day",
  "end_accuracy": "day",
  "begin_chronology": "future",
  "end_chronology": "future",
  "timespan": 518400.0,
  "raw": "from monday to sunday",
  "confidence": 0.96
}
Entity Examples
interval between today and tomorrow, from now to next week, wednesday the 3rd between 2pm and 3pm, starting sunday ending monday
Key Comments
begin String, the ISO-8601 standard of the start point in UTC
end String, the ISO-8601 standard of the end point in UTC
begin_chronology String, comma separated points in time referenced by the begin field
Can be past, present, or future
end_chronology String, comma separated points in time referenced by the end field
Can be past, present, or future
begin_accuracy String, the accuracy of the explicitly given begin datetime
Can be composed of one or more of year, month, week, day, halfday, hour, min, sec, now separated by a 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.15.0

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

TRAIN

MISC

2.14.0

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

BUILD

TRAIN

MISC

2.13.0

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

BUILD

CONNECT

2.12.0

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

TRAIN

BUILD

CONNECT

SDKs

MISC

2.11.0

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

TRAIN

BUILD

CONNECT

MONITOR

REQUEST

MISC

2.10.1

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

TRAIN

RUN

REQUEST

2.10.0

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

TRAIN

BUILD

REQUEST

MISC

2.9.0

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

TRAIN

REQUEST

2.8.0

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

TRAIN

RUN

REQUEST

2.7.1

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

REQUEST

2.7.0

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

RUN

REQUEST

2.6.0

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

TRAIN

REQUEST

2.5.0

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

TRAIN

RUN

MONITOR

REQUEST

MISC

2.4.0

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

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

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

ENTITIES

2.3.0

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

PLATFORM

API

ENTITIES

2.2.0

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

BOT BUILDER

TRAIN

ENTITIES

2.1.4

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

ENTITIES

BOT BUILDER

API

2.1.3

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

PLATFORM

ENTITIES

2.1.2

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

BOT BUILDER

ENTITIES

2.1.1

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

ENTITIES

2.1.0

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

PLATFORM

API

2.0.0

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

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": "Request 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, 01/07/2016:

LANGUAGES

ENTITIES

MISC

1.2.1

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

API

1.2.0

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

PLATFORM

ENTITIES

1.1.1

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

MISC

1.1.0

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

PLATFORM

INTENTS

JSON

MISC

1.0.1

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

MISC

1.0.0

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

NLP

ENTITIES

MISC

shell ruby python javascript