Raffle Search API (1.3.0)

Download OpenAPI specification:Download

This document describes the Raffle Search API. It provides the features needed to build a custom user interface for the Raffle Search Engine, and provide signals that can be used to increase the accuracy of search results and provide insights through the Raffle Web App.

Tools

Some endpoints rely on an API Tool being created in advance in the Raffle Web App. An API Tool allow you to configure what sources to search in and specify how many results to return. It is possible to have muttiple API Tools for use in different contexts.

API Tools are identified by a unique id that can be obtained by clicking the "Install" button on the API Tool configuration page.

Errors

Errors are returned in a standardized format.

{
  "code: <http status code>,
  "message": "detailed error message"
}

Suggest searches

The autocomplete endpoint is used to fetch suggestions based on the input provided by the user so far. The response will be a list of search queries that can be suggested to the user. If no suggestions are found, "null" is returned rather than an empty list.

Insufficient Data

The suggestions returned by the API are based on actual user queries (i.e. what other users have asked previously). A certain amount of existing queries are required before any suggestions can be generated. Calling this endpoint before a sufficient amount of data is available will result in an error.

Authorizations:
None
query Parameters
uid
required
string

the id of the search instance (aka the tool UID)

query
required
string

the search query provided by the user so far

limit
integer

The number of suggestions to return.

Responses

Response samples

Content type
application/json
{
  • "suggestions": [
    ]
}

Chat with the API

The chat endpoint replies to a chat message, based on the results of a search and previous conversation. If there are no relevant search results, it will be indicated by the status property.

References

A chat reply can reference the search results. These references are provided as indexes enclosed by square brackets (e.g. [1]). The references contain information about the source of the information, including a title, relevant text snippet, and a url (if available).

Follow up questions

If relevant, we will provide a list of related follow up questions that can be suggested to the user. These can be used in subsequent chat requests.

Latency

Note that it may take some time to generate the reply. It is highly recommended to display a placeholder to the user while the reply is being fetched. Once the reply is available, the placeholder can then be replaced by the actual reply.

Authorizations:
None
query Parameters
uid
required
string
Example: uid=D2FF7152-8089-41A9-A65D-E82111A11E49

The id of the search instance. This is also known as the tool UID.

query
required
string

the search query provided by the user

conversation-id
string

a unique identifier for a conversation. When provided, the conversation will continue from the latest reply generated with that identifier. If the identifier has not been used before, a new conversation is started. If no identifier is provided, a new conversation is started, and an identifier is returned in the response.

session-id
required
string

A unique id identifying the current user session across pages

preview
boolean

If set to true the request will not be used for training or show up in insights

device
string
Enum: "desktop" "mobile" "unknown"

The kind of device on which the user performed the chat

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "reply": "string",
  • "conversation_id": "string",
  • "follow_up_questions": [
    ],
  • "references": [
    ]
}

Get urls related to the topics of the conversations

Extract a list of conversation ids and urls that can be used for external statistics. The conversation ids are extracted from the DOM of the chat application used in the extension. If multiple relevant topics are discussed in a conversation we choose to return the url from the latest topic discussed.

Authorizations:
None
query Parameters
uid
required
string
Example: uid=D2FF7152-8089-41A9-A65D-E82111A11E49

The id of the search instance. This is also known as the tool UID.

from
required
string <date>
Example: from=1992-01-25

Retrieve data starting from and including this date.

to
required
string <date>
Example: to=1992-01-25

Retrieve data before this date.

Responses

Response samples

Content type
application/json
{}

Post feedback from the request

In order to improve search results and provide useful insignts, we track what results turned out most useful. An important signal used for determining this is what results a user is following (i.e. clicking or tapping on).

To allow correlating a result with the user action, whenever the user is following a url from a result, the client must call the feedback endpoint with the feedback data provided together with the result. This feedback data is a base64 encoded string that contains relevant information used internally at Raffle, so it must be sent back in its full original form (i.e. no lower casing or truncation).

Authorizations:
None
Request Body schema: application/json
required
type
required
string
Value: "click"

The kind of event.

feedback_data
required
string

The data obtained from the feedback_data property in a search response.

Responses

Request samples

Content type
application/json
{
  • "type": "click",
  • "feedback_data": "U29tZSBpbnRlcm5hbCBkYXRh"
}

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string"
}

Summarize a search results

The summary endpoint summarizes the results of a given search query. If there is no relevant search results to summarize, this will be indicated by the status property.

References

A summary can reference the original search results. These references are provided as indexes enclosed by square brackets (e.g. [1]). The references contain information about the source of the information, including a title, relevant text snippet, and a url (if available).

Latency

Note that it may take some time to generate the summary. It is highly recommended to display a placeholder to the user while the summary is being fetched. Once the summary is available, the placeholder can then be replaced by the actual summary.

Authorizations:
None
query Parameters
uid
required
string
Example: uid=D2FF7152-8089-41A9-A65D-E82111A11E49

The id of the search instance. This is also known as the tool UID.

query
required
string

the search query provided by the user

Responses

Response samples

Content type
application/json
{
  • "status": "success",
  • "summary": "string",
  • "references": [
    ]
}

Post external support feedback from the request

When a user is forwarded to support outside the raffle widget, it will not be reflected in our analytics. You can use this endpoint to notify us that a user was send to support.

Authorizations:
None
Request Body schema: application/json
required
uid
required
string

The uid of the tool that the event should be registered for.

url
required
string

The url the user was at when forwarded to support.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "code": 0,
  • "message": "string"
}

Retrieving top questions

Top questions can be used to give the end-user the option to choose from a list of popular search queries. The top questions provided by this endpoints are managed in the Raffle Web App.

Note that an API based search solution doesn't have to provide top questions, and the questions can come from different sources not managed by Raffle.

Authorizations:
None
query Parameters
uid
required
string
Example: uid=D2FF7152-8089-41A9-A65D-E82111A11E49

The id of the search instance. This is also known as the tool UID.

Responses

Response samples

Content type
application/json
{
  • "questions": [
    ]
}