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.

NOTE

Like the GET /message endpoint, POST /speech is meant for short inputs. We enforce a max audio length of 20 seconds.

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/ogg for ogg 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'

At this time, 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
tag optional string A specific version tag you want to use for the query. See GET /apps/:app/tags.
n optional integer The maximum number of n-best intents and traits you want to get back. The default is 1, and the maximum is 8.

Body

Send your binary data (file or stream) in the request 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 or audio is too long (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=20200513' \
   -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 intent

Creates a new intent with the given attributes.

Arguments

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

name required type doc
name required string Name for the intent.

Definition

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

Example request

  $ curl -XPOST 'https://api.wit.ai/intents?v=20200513' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "buy_flowers"}'

Example response

  {
    "id": "13989798788",
    "name": "buy_flowers"
  }

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
name required string Name for the entity. For built-in entities, use the wit$ prefix.
roles required array List of roles you want to create for the entity. A default role will always be created.
lookups optional array For custom entities, list of lookup strategies (free-text, keywords). Both lookup strategies will be created if empty.
keywords optional array For keywords entities, list of keywords and synonyms. See POST /entities/:entity/keywords.

NOTE

Definition

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

Example request

  $ curl -XPOST 'https://api.wit.ai/entities?v=20200513' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"favorite_city",
       "roles":[]}'

Example response

  {
    "id": "5418abc7-cc68-4073-ae9e-3a5c3c81d965",
    "name": "favorite_city",
    "roles": ["favorite_city"],
    "lookups": ["free-text", "keywords"],
    "keywords": []
  }

Add new values to a keywords entity

Add a possible value into the list of keywords for the keywords entity.

Arguments

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

name required type doc
keyword required string Canonical value of the entity.
synonyms required array Ways of expressing, or aliases for this canonical value.

NOTE

  • This only applies to keywords entities.

Definition

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

Example request

  $ curl -XPOST 'https://api.wit.ai/entities/favorite_city/keywords?v=20200513' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"keyword": "Brussels",
       "synonyms": ["Brussels", "Capital of Europe"]}'

Example response

{
  "id": "57475251-ba5a-412b-85ec-3ab6f778d6fa",
  "name": "favorite_city",
  "roles": ["favorite_city"],
  "lookups": ["free-text", "keywords"],
  "keywords": [
    {"keyword": "Brussels",
     "synonyms": ["Brussels",
                  "Capital of Europe"]},
    {"keyword": "Paris",
     "synonyms": ["Paris",
                  "City of Light",
                  "Capital of France"]},
    {"keyword": "Seoul",
     "synonyms": ["Seoul",
                  "서울",
                  "Kimchi paradise"]}
  ]
}

Create a new synonym for a keywords entity

Create a new synonym of the canonical value of the keywords entity. This API is limited to synonyms shorter than 280 characters.

Arguments

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

name required type doc
synonym required string New synonym for the keyword of the entity. Must be shorter than 280 characters.

Definition

  POST https://api.wit.ai/entities/:entity/keywords/:keyword/synonyms

Example request

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

Example response

{
  "id": "57475251-ba5a-412b-85ec-3ab6f778d6fa",
  "name": "favorite_city"
  "roles": ["favorite_city"],
  "lookups": ["free-text", "keywords"],
  "keywords": [
    {"keyword": "Brussels",
     "synonyms": ["Brussels",
                  "Capital of Europe"]},
    {"keyword": "Paris",
     "synonyms": ["Camembert city",
                  "Capital of France",
                  "City of Light",
                  "Paris"]},
    {"keyword": "Seoul",
     "synonyms": ["Seoul",
                  "서울",
                  "Kimchi paradise"]}
  ]
}

Create a new trait

Creates a new trait with the given attributes.

Arguments

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

name required type doc
name required string Name for the trait.
values required array List of values for the trait.

Definition

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

Example request

  $ curl -XPOST 'https://api.wit.ai/traits?v=20200513' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "politeness",
       "values": ["polite", "rude"]}'

Example response

  {
    "id": "13989798788",
    "name": "politeness",
    "values": [ {
      "id": "97873388",
      "value": "polite"
    }, {
      "id": "54493392772",
      "value": "rude"
    } ]
  }

Create a new value for the trait

Creates a new value for the trait.

Arguments

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

name required type doc
value required string Canonical value of the trait.

Definition

  POST https://api.wit.ai/traits/:trait/values

Example request

  $ curl -XPOST 'https://api.wit.ai/traits/politeness/values?v=20200513' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"value": "neutral"}'

Example response

  {
    "id": "13989798788",
    "name": "politeness",
    "values": [ {
      "id": "97873388",
      "value": "polite"
    }, {
      "id": "54493392772",
      "value": "rude"
    }, {
      "id": "828283932",
      "value": "neutral"
    } ]
  }

Train your app

Annotate and validate utterances using intents, entities and traits to train your app programmatically.


Arguments

The request body contains a JSON array of utterance objects.

Utterance Format

name required type doc
text required string The text (sentence) you want your app to understand.
intent optional string The user intent for the utterance. Out-of-scope utterances would leave off this field.
entities required array The list of entities appearing in this sentence, that you want your app to extract once it is trained.
traits required array The list of traits that are relevant for the utterance.

Entity Format

name required type doc
entity required string The entity name, including the role. This can be an entity you created, or a built-in entity. i.e food:food or wit$datetime:from.
start required integer The starting index within the text.
end required integer The ending index within the text.
body required string The span of the text for the entity.
entities required array List of entities found within the composite entity.

Trait Format

name required type doc
trait required string The trait name. This can be a trait you created, or a built-in one. i.e faq or wit$sentiment.
value required string The value for the trait, e.g. positive.

NOTE

  • All intents, entities and traits need to exist prior to use them in this API.
  • The processing is done asynchronously. Depending on the size of the training queue, it might take a few minutes before your utterances are added to your app.
  • We currently impose a rate limit on this endpoint of 200 utterances posted to your app per minute. Please contact us if your use case requires exceeding this limit.

Definition

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

Example request

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

Example response

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

Example request with composite entity

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

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, in the ISO 639-1 format.
private required bool Private if true.
timezone optional string Default timezone of your app. Defaults to America/Los_Angeles.

Definition

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

Example request

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

Example response

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

Create a new version

Take a snapshot of the current app state, save it as a tag (version) of the app. The name of the tag created will be returned in the response.


Arguments

The request body must contain a JSON object as such:

name required type doc
tag required string Name of the new version.

Response Format

name type doc
tag string Name of the tag created.

NOTE

  • We currently impose a limit of maximum 5 tags per app.

Definition

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

Example request

  $ curl -XPOST 'https://api.wit.ai/apps/57f57a8a-a7ac-4e59-ac07-67d46422bb12/tags?v=20200513' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"tag": "v$1"}'

Example response

{
  "tag": "v_1"
}

Import your app from a backup

Create a new app with all the app data from the exported app.


Arguments

name required type doc
name required string Name of the new app.
private required bool Private if true.

NOTE

We currently impose a rate limit on this endpoint of 10 apps imported per minute.

Definition

POST 'https://api.wit.ai/import'

Example request

  $ curl -XPOST 'https://api.wit.ai/import?v=20200513&name=newapp&private=false' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/zip" \
  --data-binary "@$HOME/exported.zip"

Example response

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