Download OpenAPI specification:Download
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.
All the request bodies in this API are JSON encoded and their content-type
header should be set to application/json
.
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.
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.
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.
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. |
required | Array of objects (UserInteractionData) [ 1 .. 1000 ] items | ||||
Array ([ 1 .. 1000 ] items)
|
{- "documents": [
- {
- "id": "id1"
}
]
}
{- "request_id": "string",
- "kind": "InvalidUserId",
- "details": { }
}
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.
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. |
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 | ||||||||||||||||||||||||||
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 Combination: Combinators may only be nested two times. | |||||||||||||||||||||||||||
One of = 1 properties
|
{- "count": 10,
- "published_after": "2019-08-24T14:15:22Z",
- "include_properties": true,
- "include_snippet": false,
- "filter": {
- "document property id1": {
- "$eq": true,
- "$in": [ ],
- "$gt": 0,
- "$gte": 0,
- "$lt": 0,
- "$lte": 0
}, - "document property id2": {
- "$eq": true,
- "$in": [ ],
- "$gt": 0,
- "$gte": 0,
- "$lt": 0,
- "$lte": 0
}
}
}
{- "documents": [
- {
- "id": "document_id0",
- "snippet_id": {
- "document_id": "document_id0",
- "sub_id": 2
}, - "score": 0.87,
- "properties": {
- "title": "News title"
}
}
]
}
Deprecated. Use POST /users/{user_id}/personalized_documents
instead.
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. |
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 |
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 Combination: Combinators may only be nested two times. |
{- "documents": [
- {
- "id": "document_id0",
- "snippet_id": {
- "document_id": "document_id0",
- "sub_id": 2
}, - "score": 0.87,
- "properties": {
- "title": "News title"
}
}
]
}
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.
required | object (InputDocument) = 1 properties Information about a document provided as input for an search. You can either include an existing document | ||||||||||||||||||||||||||
| |||||||||||||||||||||||||||
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 | ||||||||||||||||||||||||||
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. | |||||||||||||||||||||||||||
| |||||||||||||||||||||||||||
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 Combination: Combinators may only be nested two times. | |||||||||||||||||||||||||||
One of = 1 properties
|
{- "document": {
- "id": "id1",
- "query": "string"
}, - "count": 10,
- "published_after": "2019-08-24T14:15:22Z",
- "include_properties": true,
- "include_snippet": false,
- "personalize": {
- "exclude_seen": true,
- "user": {
- "id": "id1",
- "history": [
- {
- "id": "id1",
- "timestamp": "2000-05-14T20:22:50Z"
}
]
}
}, - "enable_hybrid_search": false,
- "filter": {
- "document property id1": {
- "$eq": true,
- "$in": [ ],
- "$gt": 0,
- "$gte": 0,
- "$lt": 0,
- "$lte": 0
}, - "document property id2": {
- "$eq": true,
- "$in": [ ],
- "$gt": 0,
- "$gte": 0,
- "$lt": 0,
- "$lte": 0
}
}
}
{- "documents": [
- {
- "id": "document_id0",
- "snippet_id": {
- "document_id": "document_id0",
- "sub_id": 2
}, - "score": 0.87,
- "properties": {
- "title": "News title"
}
}
]
}