Xayn
API docs by Redocly

Front Office API (2.7.0)

Download OpenAPI specification:Download

Front Office

The front office is typically used within front-end apps, for example a website or a mobile application. With this API, you can handle interactions with documents and search for personalized documents.

Format

All the request bodies in this API are JSON encoded and their content-type header should be set to application/json.

Auth

The API requires to set the authorizationToken header when used with the provided token.

User

Most methods require a user_id. From our perspective, a user_id is simply required to group interactions together. We don't need to know who that user is, so it is preferred to create this user_id in a privacy-preserving way. For example, create a hash method which transforms your user into an ID hash.

Documents & Snippets

The search and recommendation API, at a high level, returns a list of documents, with each entry having a score, the document id and potentially other data that is provided during ingestion.

In practice, our systems provide searches and recommendations based on an internal representation we call "snippet", as it's derived from a snippet of processed text. Since a document can have multiple snippets associated with it, each document in the result contains a snippet id, which consists of the document id and a sub_id which specifies which snippet exactly this result is based on. The getting started documentation provides more details about this.

Document Id & Snippet Id

The document id is a string which always refers to the document as a whole, no matter how many snippets it has.

The snippet id is a struct containing a document_id field and a sub_id field, it refers to a a specific snippet that belongs to the document document_id.

We recommend using the snippet id where possible. For example, if you want to register an interaction or do a similarity search based on the previous results you should use the full returned snippet id, not just the document id.

Recommendation

Provides recommendations for a given user

Finds a number of recommendations for the given user_id.

Recommendations are based on snippets and each recommendation contains the snippet id it is based on as well as a score. A higher score means that the document matches the preferences of the user better. Scores can be compared only with other scores that belong to the same request; comparing scores of documents that have been obtained through different requests can lead to unexpected results.

Depending on the request parameters the recommendation can also include additional fields.

The recommendations also contain the properties of the snippets parent document if this is requested and the properties are not empty.

Documents that have been interacted with by the user are filtered out from the result.

Note that you can request personalized documents for a specific user_id, only after that same user_id has made enough interactions via our system.

Authorizations:
ApiKeyAuth
path Parameters
user_id
required
string (Id) [ 1 .. 256 ] characters ^[a-zA-Z0-9\-:@.][a-zA-Z0-9\-:@._]*$
Example: id1

An id can be any non-empty string that consist of arabic digits, latin letters, hyphens, colons, @s, dots or underscores (except as the first character). The length constraints are in bytes, not characters.

Request Body schema: application/json
count
integer <int32> (Count) [ 1 .. 100 ]

Maximum number of documents to return.

published_after
string <date-time> (PublishedAfter) [ 10 .. 40 ] characters
Deprecated

Deprecated. Use a filter on the document property instead, for example on publication_date.

include_properties
boolean (IncludeProperties)
Default: {"$ref":"#/components/schemas/IncludeProperties/default"}

Include the properties of each document in the response.

include_snippet
boolean (IncludeSnippet)
Default: {"$ref":"#/components/schemas/IncludeSnippet/default"}

Includes the snippets text for each search result.

FilterCompare (object) or FilterCombine (object) or FilterIds (object)

Filter the documents wrt their properties.

Comparison: A key must be a valid DocumentPropertyId and the id must have been indexed before. The compared value must be of the IndexedPropertyType for which the id has been indexed.

Combination: Combinators may only be nested two times.

Ids: Works like the $in comparison operator but requires the returned documents id to be in the provided array of document ids.

Be aware that $ids will only work properly if document splitting isn't used.

One of
= 1 properties
additional property
object = 1 properties
boolean or DocumentPropertyString (string)
One of
boolean
$in
Array of strings [ 0 .. 500 ] items [ items [ 0 .. 2048 ] characters ^[^\x00]+$ ]

Arbitrary array of strings property that can be attached to a document. The item length constraints are in bytes, not characters.

number or Timestamp (string)
One of
number
number or Timestamp (string)
One of
number
number or Timestamp (string)
One of
number
number or Timestamp (string)
One of
number

Responses

Request samples

Content type
application/json
{
  • "count": 10,
  • "published_after": "2019-08-24T14:15:22Z",
  • "include_properties": true,
  • "include_snippet": true,
  • "filter": {
    }
}

Response samples

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

Personalize documents for the user Deprecated

Use /users/{user_id}/recommendations instead.

Get a list of snippets personalized for the given user_id.

Each snippet has an id and contains the id of the document it originates from as well as a score. A higher score means that the document matches the preferences of the user better. Scores can be compared only with other scores that belong to the same request; comparing scores of documents that have been obtained through different requests can lead to unexpected results.

The snippet also contain the parent documents properties if this is requested and the properties are not empty. Documents that have been interacted with by the user are filtered out from the result. Note that you can request personalized documents for a specific user_id, only after that same user_id has made enough interactions via our system.

Authorizations:
ApiKeyAuth
path Parameters
user_id
required
string (Id) [ 1 .. 256 ] characters ^[a-zA-Z0-9\-:@.][a-zA-Z0-9\-:@._]*$
Example: id1

An id can be any non-empty string that consist of arabic digits, latin letters, hyphens, colons, @s, dots or underscores (except as the first character). The length constraints are in bytes, not characters.

Request Body schema: application/json
count
integer <int32> (Count) [ 1 .. 100 ]

Maximum number of documents to return.

published_after
string <date-time> (PublishedAfter) [ 10 .. 40 ] characters
Deprecated

Deprecated. Use a filter on the document property instead, for example on publication_date.

include_properties
boolean (IncludeProperties)
Default: {"$ref":"#/components/schemas/IncludeProperties/default"}

Include the properties of each document in the response.

include_snippet
boolean (IncludeSnippet)
Default: {"$ref":"#/components/schemas/IncludeSnippet/default"}

Includes the snippets text for each search result.

FilterCompare (object) or FilterCombine (object) or FilterIds (object)

Filter the documents wrt their properties.

Comparison: A key must be a valid DocumentPropertyId and the id must have been indexed before. The compared value must be of the IndexedPropertyType for which the id has been indexed.

Combination: Combinators may only be nested two times.

Ids: Works like the $in comparison operator but requires the returned documents id to be in the provided array of document ids.

Be aware that $ids will only work properly if document splitting isn't used.

One of
= 1 properties
additional property
object = 1 properties
boolean or DocumentPropertyString (string)
One of
boolean
$in
Array of strings [ 0 .. 500 ] items [ items [ 0 .. 2048 ] characters ^[^\x00]+$ ]

Arbitrary array of strings property that can be attached to a document. The item length constraints are in bytes, not characters.

number or Timestamp (string)
One of
number
number or Timestamp (string)
One of
number
number or Timestamp (string)
One of
number
number or Timestamp (string)
One of
number

Responses

Request samples

Content type
application/json
{
  • "count": 10,
  • "published_after": "2019-08-24T14:15:22Z",
  • "include_properties": true,
  • "include_snippet": true,
  • "filter": {
    }
}

Response samples

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

Get personalized snippets for the user Deprecated

Deprecated. Use POST /users/{user_id}/personalized_documents instead.

Authorizations:
ApiKeyAuth
path Parameters
user_id
required
string (Id) [ 1 .. 256 ] characters ^[a-zA-Z0-9\-:@.][a-zA-Z0-9\-:@._]*$
Example: id1

An id can be any non-empty string that consist of arabic digits, latin letters, hyphens, colons, @s, dots or underscores (except as the first character). The length constraints are in bytes, not characters.

query Parameters
count
integer <int32> (Count) [ 1 .. 100 ]
Default: 10

Maximum number of documents to return.

published_after
string <date-time> (PublishedAfter) [ 10 .. 40 ] characters
Deprecated

Deprecated. Use a filter on the document property instead, for example on publication_date.

include_properties
boolean (IncludeProperties)

Include the properties of each document in the response.

include_snippet
boolean (IncludeSnippet)

Includes the snippets text for each search result.

FilterCompare (object) or FilterCombine (object) or FilterIds (object) (Filter)

Filter the documents wrt their properties.

Comparison: A key must be a valid DocumentPropertyId and the id must have been indexed before. The compared value must be of the IndexedPropertyType for which the id has been indexed.

Combination: Combinators may only be nested two times.

Ids: Works like the $in comparison operator but requires the returned documents id to be in the provided array of document ids.

Be aware that $ids will only work properly if document splitting isn't used.

Responses

Response samples

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

Recommendations for a given user_id or a history

Finds a number of recommendations for the given user_id or a history.

Recommendations are based on snippets and each recommendation contains the snippet id it is based on as well as a score. A higher score means that the document matches the preferences of the user or the history better. Scores can be compared only with other scores that belong to the same request; comparing scores of documents that have been obtained through different requests can lead to unexpected results.

Depending on the request parameters the recommendation can also include additional fields.

The recommendations also contain the properties of the snippets parent document if this is requested and the properties are not empty.

By default documents that have been interacted with by the user or are listed in the history are filtered out from the result. This behavior can be changed with exclude_seen.

Note that you can request personalized documents for a specific user_id, only after that same user_id has made enough interactions via our system.

Histories are not stored in the system.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
count
integer <int32> (Count) [ 1 .. 100 ]

Maximum number of documents to return.

published_after
string <date-time> (PublishedAfter) [ 10 .. 40 ] characters
Deprecated

Deprecated. Use a filter on the document property instead, for example on publication_date.

include_properties
boolean (IncludeProperties)
Default: {"$ref":"#/components/schemas/IncludeProperties/default"}

Include the properties of each document in the response.

include_snippet
boolean (IncludeSnippet)
Default: {"$ref":"#/components/schemas/IncludeSnippet/default"}

Includes the snippets text for each search result.

required
object

Personalize the ranking of candidates based on a users preferences.

exclude_seen
boolean
Default: true

If true do not include documents the user has already seen as search candidate.

A trimmed version of the users history might be used for this filter.

This option is incompatible with not specifying a user.

required
object (InputUser)

Information about a user provided as input for an search

Currently this can either be the user's id or a user's history.

id
string (Id) [ 1 .. 256 ] characters ^[a-zA-Z0-9\-:@.][a-zA-Z0-9\-:@._]*$

An id can be any non-empty string that consist of arabic digits, latin letters, hyphens, colons, @s, dots or underscores (except as the first character). The length constraints are in bytes, not characters.

Array of objects (History) [ 1 .. 100 ] items

The history is an sequence of entries representing documents visited by the user.

It is ordered from the "oldest" interaction at index 0 to the "newest" interaction at the highest index.

History entries do not need to have a timestamp, if no timestamp is given it is approximated in some way based on timestamps of neighboring documents and if non have a timestamp they are all assumed to have happened "just now" for simplicity.

Array ([ 1 .. 100 ] items)
required
string or object (SnippetOrDocumentId)
timestamp
string <date-time> (Timestamp) [ 10 .. 40 ] characters

A RFC3339 compatible date-time

  • can be in the future
  • will be converted to and then stored as UTC
  • sub-second resolution is not guaranteed

The length constraints are in bytes, not characters.

FilterCompare (object) or FilterCombine (object) or FilterIds (object)

Filter the documents wrt their properties.

Comparison: A key must be a valid DocumentPropertyId and the id must have been indexed before. The compared value must be of the IndexedPropertyType for which the id has been indexed.

Combination: Combinators may only be nested two times.

Ids: Works like the $in comparison operator but requires the returned documents id to be in the provided array of document ids.

Be aware that $ids will only work properly if document splitting isn't used.

One of
= 1 properties
additional property
object = 1 properties
boolean or DocumentPropertyString (string)
One of
boolean
$in
Array of strings [ 0 .. 500 ] items [ items [ 0 .. 2048 ] characters ^[^\x00]+$ ]

Arbitrary array of strings property that can be attached to a document. The item length constraints are in bytes, not characters.

number or Timestamp (string)
One of
number
number or Timestamp (string)
One of
number
number or Timestamp (string)
One of
number
number or Timestamp (string)
One of
number

Responses

Request samples

Content type
application/json
{
  • "count": 10,
  • "published_after": "2019-08-24T14:15:22Z",
  • "include_properties": true,
  • "include_snippet": true,
  • "personalize": {
    },
  • "filter": {
    }
}

Response samples

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

Interaction

Add a interaction between a user and either a snippet or a whole document.

Register an interaction between a user and a snippet or a whole document.

For web sites, consider triggering this method whenever a certain document url loads, preferably after the user spent some time on the page, in order to prevent false positives. For apps, consider implementing a "like" button, where the on-click triggers this method.

Please remember that it is recommended to register a reaction with the specific snippet the user interacted with instead of the document as a whole. You can do so by providing snippet ids instead of document ids.

Authorizations:
ApiKeyAuth
path Parameters
user_id
required
string (Id) [ 1 .. 256 ] characters ^[a-zA-Z0-9\-:@.][a-zA-Z0-9\-:@._]*$
Example: id1

An id can be any non-empty string that consist of arabic digits, latin letters, hyphens, colons, @s, dots or underscores (except as the first character). The length constraints are in bytes, not characters.

Request Body schema: application/json
required
Array of objects (UserInteractionData) [ 1 .. 1000 ] items
Array ([ 1 .. 1000 ] items)
string or object (SnippetOrDocumentId)
One of
[ 1 .. 256 ] characters
string [ 1 .. 256 ] characters ^[a-zA-Z0-9\-:@.][a-zA-Z0-9\-:@._]*$

An id can be any non-empty string that consist of arabic digits, latin letters, hyphens, colons, @s, dots or underscores (except as the first character). The length constraints are in bytes, not characters.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "request_id": "string",
  • "kind": "InvalidUserId",
  • "details": { }
}

Search

Semantic search in documents

Semantically search through the documents in different ways.

When a snippet id is used, the system will return snippets across all documents, that are similar to the one referred to by the given id.

When a document id is used it will currently search as if you had provided the snippet id of an arbitrary snippet in the document. This means it's for now only meaningful usable with documents which only have one snippet. That will likely change in the future.

When a query is provided, the system will return documents that are similar to the query. If enable_hybrid_search is passed, then the system will also perform keyword matching between the query and the documents. It is possible to personalize the result by passing a user id or history. In this case, the system will consider the user's interests to rank the documents. Each document contains the id and the score, where a higher value means that the document is more similar to the input. Scores can be compared only with other scores that belong to the same request; comparing scores of documents that have been obtained through different requests can lead to unexpected results. The documents also contain their properties if this is requested and the properties are not empty.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required
object (InputDocument) = 1 properties

Information about a document provided as input for an search.

You can either include an existing document id, or use query which can hold arbitrary free text.

string or object (SnippetOrDocumentId)
One of
[ 1 .. 256 ] characters
string [ 1 .. 256 ] characters ^[a-zA-Z0-9\-:@.][a-zA-Z0-9\-:@._]*$

An id can be any non-empty string that consist of arabic digits, latin letters, hyphens, colons, @s, dots or underscores (except as the first character). The length constraints are in bytes, not characters.

query
string (DocumentSearchQuery) [ 1 .. 512 ] characters ^[^\x00]+$

A search query can be any non-empty, UTF-8-encoded string which doesn't contain a zero byte. The length constraints are in bytes, not characters.

count
integer <int32> (Count) [ 1 .. 100 ]

Maximum number of documents to return.

published_after
string <date-time> (PublishedAfter) [ 10 .. 40 ] characters
Deprecated

Deprecated. Use a filter on the document property instead, for example on publication_date.

include_properties
boolean (IncludeProperties)
Default: {"$ref":"#/components/schemas/IncludeProperties/default"}

Include the properties of each document in the response.

include_snippet
boolean (IncludeSnippet)
Default: {"$ref":"#/components/schemas/IncludeSnippet/default"}

Includes the snippets text for each search result.

object

Personalize the ranking of candidates based on a users preferences.

exclude_seen
boolean
Default: true

If true do not include documents the user has already seen as search candidate.

A trimmed version of the users history might be used for this filter.

This option is incompatible with not specifying a user.

required
object (InputUser)

Information about a user provided as input for an search

Currently this can either be the user's id or a user's history.

id
string (Id) [ 1 .. 256 ] characters ^[a-zA-Z0-9\-:@.][a-zA-Z0-9\-:@._]*$

An id can be any non-empty string that consist of arabic digits, latin letters, hyphens, colons, @s, dots or underscores (except as the first character). The length constraints are in bytes, not characters.

Array of objects (History) [ 1 .. 100 ] items

The history is an sequence of entries representing documents visited by the user.

It is ordered from the "oldest" interaction at index 0 to the "newest" interaction at the highest index.

History entries do not need to have a timestamp, if no timestamp is given it is approximated in some way based on timestamps of neighboring documents and if non have a timestamp they are all assumed to have happened "just now" for simplicity.

Array ([ 1 .. 100 ] items)
required
string or object (SnippetOrDocumentId)
timestamp
string <date-time> (Timestamp) [ 10 .. 40 ] characters

A RFC3339 compatible date-time

  • can be in the future
  • will be converted to and then stored as UTC
  • sub-second resolution is not guaranteed

The length constraints are in bytes, not characters.

enable_hybrid_search
boolean
Default: false

Enable the hybrid search mode.

FilterCompare (object) or FilterCombine (object) or FilterIds (object)

Filter the documents wrt their properties.

Comparison: A key must be a valid DocumentPropertyId and the id must have been indexed before. The compared value must be of the IndexedPropertyType for which the id has been indexed.

Combination: Combinators may only be nested two times.

Ids: Works like the $in comparison operator but requires the returned documents id to be in the provided array of document ids.

Be aware that $ids will only work properly if document splitting isn't used.

One of
= 1 properties
additional property
object = 1 properties
boolean or DocumentPropertyString (string)
One of
boolean
$in
Array of strings [ 0 .. 500 ] items [ items [ 0 .. 2048 ] characters ^[^\x00]+$ ]

Arbitrary array of strings property that can be attached to a document. The item length constraints are in bytes, not characters.

number or Timestamp (string)
One of
number
number or Timestamp (string)
One of
number
number or Timestamp (string)
One of
number
number or Timestamp (string)
One of
number

Responses

Request samples

Content type
application/json
{
  • "document": {
    },
  • "count": 10,
  • "published_after": "2019-08-24T14:15:22Z",
  • "include_properties": true,
  • "include_snippet": true,
  • "personalize": {
    },
  • "enable_hybrid_search": false,
  • "filter": {
    }
}

Response samples

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