API
Last updated
Was this helpful?
Last updated
Was this helpful?
Metarank's API provides an easy way to integrate Metarank with your applications.
receives the stream of events
trains the model on your data
provides personalized results generated by the trained model
- retrieval of recommendations.
- using LLMs for encoding and cross-encoding texts.
- to have a nice metrics dashboard about Metarank internals.
API Endpoint: /feedback
Method: POST
Feedback endpoint receives several types of events: item, user, interaction, ranking.
Integrating these events is crucial for personalization to operate properly and provide relevant results.
You can find events and their description on the .
A JSON message with the following fields:
accepted
: how many events from the submitted batch were processed
status
: "ok" when no errors found
tookMillis
: how many milliseconds batch processing took
updated
: how many underlying ranking features were recomputed.
Example:
API Endpoint: /train/<model name>
Method: POST
Payload: none
A JSON response with the following fields:
weights
: per-field model weights
sizeBytes
: model size in bytes
features
: test/train error loss while training.
Example:
API Endpoint: /rank/<model name>
Method: POST
Querystring Parameters:
explain: boolean
: used to provide extra information in the response containing calculated feature values.
Ranking endpoint does the real work of personalizing items that are passed to it. You need to explicitly define which model to invoke.
id
: a request identifier later used to join ranking and interaction events. This will be the same value that you will pass to feedback endpoint for impression and ranking events.
user
: an optional unique visitor identifier.
session
: an optional session identifier, a single visitor may have multiple sessions.
items
: which particular items were displayed to the visitor.
items.id
: id of the content item. Should match the item
property from item metadata event.
items.label
: an optional field for explicit relevance judgments.
took
: number of millis spend processing request
items.id
: id of the content item. Will match item
property from the item metadata event.
items.score
: a score calculated by personalization model
items.features
: an array of feature values calculated by pesonaliization model. This field will be returned if explain
field is set to true
in the request. The structure of this object will vary depending on the feature type.
API Endpoint: /recommend/<model-name>
Method: POST
Where:
count
- number of items to recommend.
user
- optional, current user id
items
- context of recommendation. For example, it can be single item for "similar-items" recommendation, and multiple items at once for "cart-style" recommendations.
took
: number of millis spend processing request
items.id
: id of the content item.
items.score
: a score calculated by recommender model.
Metarank has API for quick and dirty LLM inference and encoding of texts. It can be useful for implementing hybrid search applications, when you need an actual embedding vector for a query.
API Endpoint: /inference/encoder/<name>
Method: POST
Encode a batch of strings into vectors using configured model <name>
.
API Endpoint: /inference/cross/<name>
Method: POST
Encode a batch of query-document pairs into similarity scores using configured model <name>
.
API Endpoint: /metrics
Method: GET
Dumps app and JVM metrics in a prometheus format.
Train endpoint runs the training on persisted click-through data. You can run this method at any time to re-train the model. See the on how to set up the retraining.
timestamp
: when this event happened. (see on which formats are supported)
fields
: an optional array of extra fields that you can use in your model, for more information refer to .
items.fields
: an optional set of per-item fields, for example BM25 scores coming from ES. See in ranking.
Recommend endpoint returns recommended items that are produced by .