HTTP API Reference

Retrieve the meaning of an audio wave

Returns the meaning extracted from an audio file or stream. We do recommend you to stream the audio input as it will reduce the latency, hence improve the user experience.

Headers

In addition to the authorization header, you must set a Content-type header to:

  • audio/wav if you are sending a WAV file. We support RIFF WAVE (linear, little-endian).
  • audio/mpeg3 for mp3 file or stream
  • audio/ulaw for G.711 u-law file or stream. Sampling rate must be 8khz
  • audio/raw. For this content-type, the following parameters are mandatory
parameter possible values
encoding signed-integer, unsigned-integer, floating-point, mu-law, a-law, ima-adpcm, ms-adpcm or gsm-full-rate
bits 8, 16, or 32
rate an integer value like 8000 or 8k
endian big or little (usually little, cf. this Wikipedia article)

Example:
'content-type': 'audio/raw;encoding=unsigned-integer;bits=16;rate=8000;endian=big'

For now Wit.ai is only able to process mono so you must make sure to send mono and not stereo to the API.

Arguments

The request’s URL can contain the following optional fields:

name required type doc
context optional context object (JSON) Context
msg_id optional string A specific Id you want to assign to the message that will be processed. If not set, Wit.ai will auto generate one for you
thread_id optional string A specific Id that will let you group requests per conversation
n optional integer The number of n-best outcomes you want to get back. default is 1

Body

Put your binary data (file or stream) in the body.

Streaming audio

We accept chunked data, which is a good way to reduce latency. In addition to the Content-type header, you must set a Transfer-encoding header to chunked

Audio stream shouldn’t exceed 10s of audio time.

Response Format

Please refer to GET /message for information about the response format.

Error codes

http code reason
200 success, business as usual
400 missing body (code: body) or missing content-type (code: content-type) or unknown content-type (code: unknown-content-type) or speech recognition failed (code: speech-rec) or invalid parameters (code: invalid-params)
401 missing or wrong auth token (code: auth)
408 request timed out, client was to slow to send data (code: timeout)
500 something went wrong on our side, our experts are probably fixing it. (code: wit)
503 something is very wrong on our side, our experts are probably being yelled at

NOTE

You can use SoX to record WAV files from the command line. The following options will create a Wit-ready WAV file (press Ctrl+C to stop recording):

  sox -d -b 16 -c 1 -r 16k sample.wav

Use the file command to check your file types.

  $ file sample.wav
  sample.wav: RIFF (little-endian) data, WAVE audio, Microsoft PCM, 16 bit, mono 16000 Hz

Definition

  POST https://api.wit.ai/speech

Example request

  $ curl -XPOST 'https://api.wit.ai/speech?v=20170307' \
   -i -L \
   -H "Authorization: Bearer $TOKEN" \
   -H "Content-Type: audio/wav" \
   --data-binary "@sample.wav"

The response format is the same as in GET /message

Create a new entity

Creates a new entity with the given attributes.

Arguments

The request body must contain a JSON object with the given fields:

name required type doc
id required string ID or name of the requested entity
doc optional string Short sentence describing this entity

NOTE

Definition

  POST https://api.wit.ai/entities

Example request

  $ curl -XPOST 'https://api.wit.ai/entities?v=20170307' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"doc":"A city that I like",
       "id":"favorite_city"}'

Example response

  {
    "name" : "favorite_city",
    "lang" : "en",
    "lookups" : [ ],
    "builtin" : false,
    "doc" : "A city that I like",
    "id" : "5418abc7-cc68-4073-ae9e-3a5c3c81d965"
  }

We don’t return the values anymore in the response. See GET /entities/:entity-id below.

Add new values to a keyword entity

Add a possible value into the list of values for the keyword entity.

Arguments

The request body must contain a JSON object with the given fields:

name required type doc
value required string Canonical value of the entity
expressions optional array of string Ways of expressing this canonical value
metadata optional string Metadata you want to attach to this value, will be sent back in runtime.

NOTE

  • This only applies to keyword entities. For trait or free-text entities, use POST /samples

Definition

  POST https://api.wit.ai/entities/$ENTITY_ID/values

Example request

  $ curl -XPOST 'https://api.wit.ai/entities/favorite_city/values?v=20170307' \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"value":"London",
       "expressions":["London"],
       "metadata":"CITY_1234"}'

Example response

{
  "builtin" : false,
  "doc" : "These are cities worth going to",
  "exotic" : false,
  "id" : "57475251-ba5a-412b-85ec-3ab6f778d6fa",
  "lang" : "en",
  "lookups" : [ "keywords" ],
  "name" : "favorite_city"
}

Create a new expression for a keyword entity

Create a new expression of the canonical value of the keyword entity. This API is limited to expressions shorter than 256 characters.

Arguments

The request body must be a JSON object with the given fields:

name required type doc
expression required string new expression for the canonical value of the entity. Must be shorter than 256 characters.

NOTE

  • This only applies to keyword entities. For trait or free-text entities, use POST /samples

Definition

  POST https://api.wit.ai/entities/$ENTITY_ID/values/$ENTITY_VALUE/expressions

Example request

  $ curl -XPOST 'https://api.wit.ai/entities/favorite_city/values/Paris/expressions?v=20170307' \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"expression":"Camembert city"}'

Example response

{
  "builtin" : false,
  "doc" : "These are cities worth going to",
  "exotic" : false,
  "id" : "57475251-ba5a-412b-85ec-3ab6f778d6fa",
  "lang" : "en",
  "lookups" : [ "keywords" ],
  "name" : "favorite_city"
}

Train your app

Validate samples (sentence + entities annotations) to train your app programmatically.


Arguments

The request body contains a JSON array of Samples

Sample

name required type doc
text required string The text (sentence) you want your app to understand
entities required array The list of entities appearing in this sentence, that you want your app to extract once it is trained.

SampleEntity

name required type doc
entity required string The entity name. This can be the name of an entity you created, or a builtin entity. i.e food or wit$on_off.

Note
his entity must have been created previously. You can use POST /entities
value required string Canonical value of the entity or the text span
start optional integer If your entity appears in the text, the starting index within the text
end optional integer If your entity appears in the text, the ending index within the text
subentities optional array List of entities found within the composite entity

Definition

  POST https://api.wit.ai/samples

Example request

  $ curl -XPOST 'https://api.wit.ai/samples?v=20170307' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '[{
        "text": "I want to fly to sfo",
        "entities": [
          {
            "entity": "intent",
            "value": "flight_request"
          },
          {
            "entity": "wit$location",
            "start": 17,
            "end": 20,
            "value": "sfo"
          }
        ]
      }]'

Example response

{
  "sent" : true,
  "n" : 1
}

Example request with composite entity

  $ curl -XPOST 'https://api.wit.ai/samples?v=20170307' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '[{
        "text": "I want a blue toyota",
        "entities": [
          {
            "entity": "car",
            "value": "blue toyota",
            "start": 9,
            "end": 20,
            "subentities": [
              {
                "entity":"color",
                "value": "blue",
                "start": 0,
                "end": 4
              },
              {
                "entity":"model",
                "value": "toyota",
                "start": 5,
                "end": 11
              }
            ]
          }
        ]
      }]'

Example response

{
  "sent" : true,
  "n" : 1
}

Create a new app

Creates a new app for an existing user.


Arguments

The request body contains a JSON object with the fields below

name required type doc
name required string Name of the new app
lang required string Language code (ISO alpha-2 code). Supported languages
private required string Private if “true”
desc optional string Short sentence describing your app

Definition

  POST https://api.wit.ai/apps

Example request

  $ curl -XPOST 'https://api.wit.ai/apps?v=20170307' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"My_New_App",
       "lang":"en",
       "private":"false"}'

Example response

{
  "access_token" : "NEW_ACCESS_TOKEN",
  "app_id" : "NEW_APP_ID"
}

Create a new intent

DEPRECATED As of April 13th 2016, intents have changed, please refer to Categorize user intent to learn more.


Currently the API only accepts expressions without entities.

Arguments

The request body can contain
- a JSON object with the fields below
- an array of JSON objects with the fields below

name required type doc
name required string Name of the new intent
doc optional string Short sentence describing this intent
metadata optional string String containing additional info for this intent
expressions optional array Possible expressions for this intent. Currently the API only accepts expressions without entities.
meta optional json Need a “states” field that contains an array of states associated with this intent (see notes below)

NOTE

To add states to your intent, use the field meta. If any, the intent won’t be activated for stateless queries. See more.
For example:

{
  "name" : "email_answer",
  "doc" : "to detect the preference between email or sms",
  "metadata" : "answer_id=1122",
  "meta" : {
    "states" : ["email_or_text","another_state"]
  },
  "expressions" : [{"body" : "email"}, {"body" : "text"},{"body" : "sms"}]
}

Definition

  GET https://api.wit.ai/intents

Example request

  $ curl -XPOST 'https://api.wit.ai/intents?v=20170307' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"flight_request",
       "doc":"detect flight request",
       "expressions":[{
          "body" : "fly from incheon to sfo"
        }, {
          "body" : "I want to fly from london to sfo"
        },{
          "body" : "need a flight from paris to tokyo"
        }]}'

Example response

{
  "intents" : [ {
    "id" : "8bbd17dc-b383-4f19-802e-dfc86d57cb23",
    "name" : "flight_request"
  }]
}

Example request with an array of intents

  $ curl -XPOST 'https://api.wit.ai/intents?v=20170307' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '[{"name":"car_request",
       "doc":"detect car request",
       "expressions":[{
          "body" : "book a rental car in London"
        }, {
          "body" : "need to get a car in paris"
        }]},
        {"name":"uber_request",
       "doc":"detect uber request",
       "expressions":[{
          "body" : "find a uber in London"
        }]}]'

Example response with an array of intents

{
  "intents" : [ {
    "id" : "fbe55d5b-a98b-4b56-a39b-00040679511a",
    "name" : "car_request"
  }, {
    "id" : "a0b8621b-01a7-4ba1-b7d6-cc5032bf8e5b",
    "name" : "uber_request"
  } ]
}

Add new expressions to an intent

DEPRECATED As of April 13th 2016, intents have changed, please refer to Categorize user intent to learn more.


Add validated expressions to a given intent. Currently the API only accepts expressions without entities.

Arguments

The request body must be an array with the given object:

name required type doc
body required string Expression for this intent. Currently the API only accepts expressions without entities.

Definition

  POST https://api.wit.ai/intents/$INTENT_ID/expressions

Example request

  $ curl -XPOST 'https://api.wit.ai/intents/flight_request/expressions?v=20170307' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '[{
          "body" : "I\u0027d like to fly from NY to Chicago"
        },{
          "body" : "fly to LA from Miami"
        }]'

Example response

  [ {
    "intent_id" : "8bbd17dc-b383-4f19-802e-dfc86d57cb23",
    "body" : "I'd like to fly from NY to Chicago"
  }, {
    "intent_id" : "8bbd17dc-b383-4f19-802e-dfc86d57cb23",
    "body" : "fly to LA from Miami"
  } ]

The $INTENT_ID parameter can be either the intent id or the intent name.