Xayn
API docs by Redocly

Front Office API (2.6.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.

Document

A document here is represented by its id and optional properties. In order to display a document in an interface, it's preferred to use properties, which is an arbitrary collection of values. For example, it could contain an image url, a full article url, the publication date, the author or much more. The properties that were added when the document was submitted to us, are just mirrored here.

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.

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
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

Personalize documents for the user

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)

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)

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.

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": false,
  • "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)
Default: true

Include the properties of each document in the response.

include_snippet
boolean (IncludeSnippet)
Default: false

Includes the snippets text for each search result.

FilterCompare (object) or FilterCombine (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.

Responses

Response samples

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

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
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)

Include the properties of each document in the response.

include_snippet
boolean (IncludeSnippet)

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)

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.

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": false,
  • "personalize": {
    },
  • "enable_hybrid_search": false,
  • "filter": {
    }
}

Response samples

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