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 request a list of personalized documents.
All the request bodies in this API are JSON encoded and their Content-Type headers should be set to application/json.
Each method requires 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.
\
Handles interactions between users and documents and allows to fetch personalized documents per user.
Returns a list of documents personalized for the given user_id.
Each document contains the id, the score and the properties that are attached to the document.
The score is a value between 0 and 1 where a higher value means that the document matches the preferences of the user better.
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 [ 1 .. 256 ] characters ^[a-zA-Z0-9_:@.\-]+$ Example: user_id Id of the user |
| count | integer <int32> (Count) [ 1 .. 100 ] Default: 10 Maximum number of personalized documents to return |
| published_after | string <date-time> [ 10 .. 40 ] characters Example: published_after=2000-05-14T20:22:50Z Only include documents which have been published after given datetime. If used documents without a |
{- "documents": [
- {
- "id": "document_id0",
- "score": 0.87,
- "properties": {
- "title": "News title"
}
}
]
}Use this method to register an interaction between a user and a 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 then triggers this method.
| user_id required | string [ 1 .. 256 ] characters ^[a-zA-Z0-9_:@.\-]+$ Example: user_id Id of the user |
required | Array of objects (UserInteractionData) [ 1 .. 1000 ] items |
{- "documents": [
- {
- "id": "document_id"
}
]
}{- "request_id": "string",
- "kind": "InvalidUserId",
- "details": { }
}Returns a list of documents that are semantically similar to the one given as input. Each document contains the id, the score and the properties. The score is a value between 0 and 1 where a higher value means that the document is more similar to the one in input
required | object Information about a document provided as input for an search. You can either include an existing Document's |
| count | integer <int32> (Count) [ 1 .. 100 ] Default: 10 |
| published_after | string <date-time> [ 10 .. 40 ] characters A RFC3339 compatible date-time
|
| min_similarity | number <float> [ 0 .. 1 ] Default: 0 Minimal similarity of a document to consider it as search candidate. |
object Personalize the ranking of candidates based on a users preferences. | |
| enable_hybrid_search | boolean Default: false Enable the hybrid search mode. |
{- "document": {
- "id": "document_id",
- "query": "inflation is causing world-wide price hikes, especially for energy and food consumption"
}, - "count": 10,
- "published_after": "2000-05-14T20:22:50Z",
- "min_similarity": 0,
- "personalize": {
- "exclude_seen": true,
- "user": {
- "id": "user_id",
- "history": [
- {
- "id": "document_id",
- "timestamp": "2000-05-14T20:22:50Z"
}
]
}
}, - "enable_hybrid_search": false
}{- "documents": [
- {
- "id": "document_id0",
- "score": 0.87,
- "properties": {
- "title": "News title"
}
}
]
}