/
📓
API Overview
Search
Try Notion
📓
API Overview
MeetKai provides two types of APIs, our conversational API “Oscar” and our search API “Grouch”
💡
The following product overview is covered by a number of patents pending in both the US and globally
Oscar
Oscar is the backend to support conversational experiences. It is stateful, allowing for our multi turn functionality. Every session with Oscar begins with initializing a dialogue, each “user” can have only a single ongoing dialogue at a time. The first Message sent to Oscar is what triggers the creation of a new stateful dialogue
Messages
A Message should be sent as a result of the user submitting either text or speech. Messages take in a set of speech recognition results, each with a possible transcription and the associated confidence. If the input is based on a keyword input, it should be marked as a single recognition result with confidence of 1.0.
💡
It is important to note to Oscar if the user entered the text or spoke it, otherwise it is not possible for Oscar to know the difference between a transcription with confidence 1 and a single text input with confidence 1.
Responses
Oscar responds with a stream of messages, please refer to the OpenAPI documentation for the specifics of each response type, however there are a few key concepts to keep in mind.
Responses from Oscar are intended to be displayed to the user as they are received in a streaming fashion.
Audio messages are meant to be buffered and played one after the other, this allows for two separate audio responses to be sent and played without requiring loading all at once
The connection will be closed when Oscar is finished with sending responses
Request methods
There are 3 different ways that one can send messages to Oscar.
Websocket
A web socket connection can be opened for each “turn”, the user should start by sending a single Message. Oscar will emit Responses and close the web socket when no more responses are expected (the turn is complete).
Key points:
Not all client libraries support headers with web sockets, for this reason it is not recommended to be used unless there are special considerations for why a websocket is preferable for the application runtime.
Compression is manually carried out, please see Postman for the headers that should be specified to select between gzip and zlib.
Streaming HTTP
This is the preferred method of interaction with Oscar. You begin by sending a POST message to the endpoint as prescribed in the API. In response you will get new line delimited messages. The connection will close when there are no more messages to send back
Batched HTTP
For clients that cannot support Websocket or Streaming HTTP, we also provide a batched endpoint. A single message is sent as a POST request and the response will come back as a JSON body with as an array of responses. Please refer to the batch API for details.
💡
You should always prefer the Streaming HTTP api since it is the most tested and utilized by MK internally. The batched HTTP API is intended only for testing and development as it is a much worse experience for an end user due to the responses requiring buffering. The WebSocket API does not support browsers due to limitations in sending headers, and in general is not intended for production usage.
Grouch
Grouch is the backend service that supports conversational search, instead of providing a conversational experience it is much more akin to a conventional search engine. Grouch itself is used to power all of the MeetKai Quick Apps and card abilities. There are comprehensive examples and documentation on how to use grouch, but for now this section will provide a few key points to consider.
Domains
Grouch itself can handle searching across a single or multiple domains. In the single domain scenario, the client must specify the domain to search for and results will be guaranteed to come from that domain.
💡
If a query is sent restricted to a domain where it would not make sense, the results are undefined. For this reason if you are not positive that the query matches that domain it is better to not specify any domains
In the multi domain scenario, all of the grouch supported domains are queried to surface results. Results are grouped together by domain and an associated ranking is supplied on a domain-by-domain level. External API usage currently does not support mixed ranking, it is up to the client to either co-mingle or display separately results for each domain.
NLU
Grouch supports the full conversational NLU that can be handled by Oscar in a conversational context, some example queries that grouch can handle:
Tom cruise movies no action
Shirt without stripes
Black shirt not for men
....
💡
Grouch provides limited multi turn support, unlike in Oscar where the turns are executed in sequence allowing for true multi turn coreference, the turns in grouch are processed as a single unit.
Pagination
Pagination in grouch is possible but does not use a conventional offset method. Instead you perform a new query but pass in as part of the request body the IDs to exclude from the previous result. Due to potential race conditions, clients are still advised to filter out duplicate item ids before displaying the next page of results.
💡
There is no way to tell how many results might be possible or are remaining. Instead it is suggested to just make a new request to see if a new page of results exists.
Personalization
Personalization for all experiences happens through Grouch. Currently external API users may provide 4 types of interactions. The API documentation contains full information on this.
Like: A like interaction is an explicit positive interaction, example frontend usages of this would be a thumbs up button or a positive rating
Dislike: A dislike interaction is an explicit negative interaction, it is the opposite of a Like
💡
A dislike on an item will “undo” a like for purposes of personalization and then move to the negative direction, not making it a 0.
Seen: A seen interaction is intended to provide an implicit interaction that a user has viewed a result. It is primarily used to enhance novelty and subtle personalization.
Click: A click interaction is a catch all for a positive interaction that implies a conversion, this might be clicking the watch now button in streaming or the order delivery button in restaurants. It is the most positive interaction a user can have with an item
💡
For best results, you are suggested to always send a SEEN when an Oscar result is rendered to the user and is displayed on the screen for some minimum number of seconds
Headers and Authorization
All requests to the MK API are expected to contain certain headers. There are two types of headers. Required headers, when missing, will cause the request to fail. Optional headers, when missing, will still allow a result to be returned but may be substantially degraded. In general the more headers provided the better the result quality. Please refer to the API documentation for full information.