Headers

Introduction

This page describes the headers and their associated values that Query APIs expects in the incoming requests over either REST API or WebSocket API.
The headers expected in Query API requests are summarized in the below table.

Name	REST API	Websocket API
Accept	required	required
Content-Type	required	required
X-Voysis-Audio-Profile-Id	required	required
Authorization	required	required
X-Voysis-Ignore-Vad	not supported	optional
X-Voysis-Entity	optional	not supported

Accept

❗️

Mandatory Header

API Versioning and Media Types

All requests to the Voysis REST API must specify a valid Accept HTTP header. The media type of the request will identify the version of the API that is in use. If a caller supplies a media type that does not specify an exact version then the latest version of the API is assumed. It is recommended that client applications always use version-specific media types to ensure stability.

The format for the Voysis custom type is application/vnd.voysisquery.v1+json. Where v1 is the version of the API you are using and +json specifies the type of content you expect to receive.

Example

HTTP

Accept: application/vnd.voysisquery.v1+json

Forward and Backward Compatibility

To ensure backward compatibility, Voysis will never modify a specific major version of the API in a way that would break clients that understand that version of the API. We may introduce minor revisions to API implementations without incrementing the version number but such changes will not cause interoperability problems with clients as long as the client conforms to these compatibility rules.

If breaking changes are made, then the major version of the API will change, resulting in a new media type (for example, "application/vnd.voysisquery.v2"). As long as client devices specify the major API version number in their Accept headers, they will not encounter interoperability problems as the API changes.

To ensure forward compatibility for client devices where minor API revisions are
made, clients must allow for the following scenarios:

• A new property may be introduced into an entity. Where a client device does not recognise a property in an object, it should simply ignore it.

Content-Type

❗️

Mandatory Header

The Content-Type header specifies the type of data you are sending. For requests which send json you must use application/json or the Voysis custom type (example: application/vnd.voysisquery.v1+json)

Example

HTTP

Content-Type: application/json

For requests which send audio data you must use the mime type of the audio you are sending.

HTTP

Content-Type: audio/pcm;bits=16;rate=16000

X-Voysis-Audio-Profile-Id

❗️

Mandatory Header

The X-Voysis-Audio-Profile-Id header is a required header value that is used as a way of uniquely identifying the device and user. See the section in general concepts for more information on what this value means.

Example

HTTP

X-Voysis-Audio-Profile-Id: f8338e44-9d48-11e7-abc4-cec278b6b50a

Authorization

❗️

Mandatory Header

The Authorization header must contain a valid session token.

Example

HTTP

Authorization: Bearer yyqEL28cPBL2Up1wUA3zYxEJghT5BdtsccNbmnqxI5c76IHnJOUpr5b7C0NT8enU

X-Voysis-Ignore-Vad

🚧

Optional Header

Only for WebSocket API

This header gives you control over the use of Voice Activity Detection feature.
When using the WebSocket API if this header is missing it is considered false.
This header is ignored in the REST API.

HTTP

X-Voysis-Ignore-Vad: false

X-Voysis-Entity

🚧

Optional Header

Only for REST API

Allows streaming with implicit query creation. It must be a base64-encoded representation of the JSON entity that is POSTed to create a query.(see create a query )
##Example

Shell

X-Voysis-Entity: $(echo -n '{"locale":"en-US"}' |base64)