Guides
Guides

APIs

Suggest Edits

See Headers for details on required headers and their meaning.

📘

Application Token

All of the curl examples on this page include an authorization header that depends on your shell having set a valid appToken variable. Refer to the Authorization chapter for information on obtaining a valid application token.

Query

A query is executed by first creating the query and then streaming audio data to that query. The audio is streamed via HTTP's chunked transfer encoding mechanism. Once all audio is uploaded, the query is processed and the results returned to the client.

The query response may contain the transcribed text representation of the user's query as well as any integration-specific results.

Create a Query

To create a new audio query, the API client must POST a query entity to the /queries endpoint. For example:

curl -H "Content-Type: application/json" \
     -H "Accept: application/vnd.voysisquery.v1+json" \
     -H "Authorization: Bearer $appToken" \
     -H "X-Voysis-Audio-Profile-Id: f8338e44-9d48-11e7-abc4-cec278b6b50a" \
     -d '{"locale": "en-US", "queryType": "audio","audioQuery": {"mimeType": "audio/pcm;bits=16;rate=16000"}}' \
     https://mycompany.voysis.io/queries

An example response:

{
  "id": "e56c0a7a-d402-4218-a56f-68f75bd788ff",
  "locale": "en-US",
  "queryType": "audio",
  "audioQuery": {
    "mimeType": "audio/pcm;bits=16;rate=16000"
  },
  "_links": {
    "self": {
      "href": "http://mycompany.voysis.io/queries/e56c0a7a-d402-4218-a56f-68f75bd788ff"
    },
    "audio": {
      "href": "http://mycompany.voysis.io/queries/e56c0a7a-d402-4218-a56f-68f75bd788ff/audio"
    }
  },
  "_embedded": {}
}

Add Audio Data

Once the query entity is created, the client may then POST the audio data to the query.

API clients transport the audio data to Voysis in chunks. A client must use chunked HTTP/1.1 transfer encoding.

API clients add the audio data should POST the binary data to the /queries/{query_id}/audio endpoint. The server will block until the query response is available, and return the full query response. For example:

curl -H "Content-Type: audio/pcm;bits=16;rate=16000" \
     -H "Accept: application/vnd.voysisquery.v1+json" \
     -H "Authorization: Bearer $appToken" \
     -H "Transfer-Encoding: chunked" \
     -H "X-Voysis-Audio-Profile-Id: f8338e44-9d48-11e7-abc4-cec278b6b50a" \
     --data-binary @my_audio.wav
     https://mycompany.voysis.io/queries/e56c0a7a-d402-4218-a56f-68f75bd788ff/audio

An example response:

{
  "id": "2b01d611-ed67-40cf-b383-67516005818e",
  "locale": "en-US",
  "queryType": "audio",
  "audioQuery": {
    "mimeType": "audio/pcm;bits=16;rate=16000"
  },
  "textQuery": {
    "text": "add this to my cart"
  },
  "intent": "add_to_cart",
  "context": {
  },
  "entities": {
  },
  "_links": {
    "query": {
      "href": "https://mycompany.voysis.io/queries/e56c0a7a-d402-4218-a56f-68f75bd788ff"
    },
    "self": {
      "href": "https://mycompany.voysis.io/queries/e56c0a7a-d402-4218-a56f-68f75bd788ff/audio/"
    }
  }
}

Stream with Implicit Query Creation

It is possible to initiate an audio stream directly without first creating a query. When using this approach, the query will be automatically created by Voysis. An extra header is required in the HTTP request to provide the details required to create the query. This header is X-Voysis-Entity and must be a base64-encoded representation of the JSON entity that is POSTed to create a query (see "Create a Query" above). As a convenience, it is not necessary to specify that the query type is audio, as that is implicit, and it is not necessary to duplicate the MIME type for the audio in the entity body, as this is determined from the Content-Type header.

For example:

curl -H "Content-Type: audio/pcm;bits=16;rate=16000" \
     -H "Accept: application/vnd.voysisquery.v1+json" \
     -H "Authorization: Bearer $appToken" \
     -H "Transfer-Encoding: chunked" \
     -H "X-Voysis-Audio-Profile-Id: f8338e44-9d48-11e7-abc4-cec278b6b50a" \
     -H "X-Voysis-Entity: $(echo -n '{"locale":"en-US"}' |base64)" \
     --data-binary @my_audio.wav
     https://mycompany.voysis.io/queries

An example response:

{
  "id": "2b01d611-ed67-40cf-b383-67516005818e",
  "locale": "en-US",
  "queryType": "audio",
  "audioQuery": {
    "mimeType": "audio/pcm;bits=16;rate=16000"
  },
  "textQuery": {
    "text": "add this to my cart"
  },
  "intent": "add_to_cart",
  "context": {
  },
  "entities": {
  },
  "_links": {
    "query": {
      "href": "https://mycompany.voysis.io/queries/e56c0a7a-d402-4218-a56f-68f75bd788ff"
    },
    "self": {
      "href": "https://mycompany.voysis.io/queries/e56c0a7a-d402-4218-a56f-68f75bd788ff/audio/"
    }
  }
}

Retrieve the Query Result

A query's result remains available via the API for a fixed time after its completion. Its state can be fetched via a GET request.

API clients should GET the query from the /queries/{query_id} endpoint. For example:

curl -H "Content-Type: application/json" \
     -H "Accept: application/vnd.voysisquery.v1+json" \
     -H "Authorization: Bearer $appToken" \
     -H "X-Voysis-Audio-Profile-Id: f8338e44-9d48-11e7-abc4-cec278b6b50a" \
     https://mycompany.voysis.io/queries/e56c0a7a-d402-4218-a56f-68f75bd788ff

See Query Responses for details on the structure and meaning of the fields in the query response.

An example response:

{
  "id": "e56c0a7a-d402-4218-a56f-68f75bd788ff",
  "queryType": "audio",
  "textQuery": {
    "text": "show me freshly squeezed orange juice"
  },
  "audioQuery": {
    "mimeType": "audio/pcm;bits=16;rate=16000"
  },
  "intent": "newSearch",
  "reply": {
    "text": "Here's what I found"
  },
  "entities": {
    "keywords": ["freshly", "squeezed", "orange", "juice"],
    "products": [],
    "queryString": "freshly squeezed orange juice",
    "sortBy": ""
  },
  "_links": {
    "self": {
      "href": "/queries/e56c0a7a-d402-4218-a56f-68f75bd788ff"
    },
    "audio": {
      "href": "/queries/e56c0a7a-d402-4218-a56f-68f75bd788ff/audio"
    }
  },
  "_embedded": {}
}

Updated over 5 years ago