Minerva Open Text API
API Integration
Version 2.3
Last update: 6/06/2023
Getting Started
Minerva Open Text accepts input text in any language (alphanumeric characters excluding punctuation marks and symbols), either natively or through translation, and does not require any pre-processing.
info
How we handle punctuation marks, symbols, special characters and emojis:
- If sent mixed with alphanumeric text: they will be stripped from the string and remaining text will be processed normally
- If sent in isolation (with no other alphanumeric characters mixed in): the API will not process the string and simply return an error
Your Technical Integration contact will provide you with the access details needed to contact the Minerva Open API. These consist of a custom UUID token sent as a header with each API request (see below).
Blacklisted terms detection feature
If you have a specific list of blacklisted terms that you would like to be detected and reported explicitly,
you can provide them to us, and we will set it up for you. The list should be a file with blacklisted words
or/and sentences separated by a new line.
After all set, the blacklist_enabled parameter in the text settings can be set to true and the API will return
the list of found blacklisted terms in the blacklisted_terms strings array field.
Keep in mind that setting blacklist_enabled to true can not be done without a terms list uploaded.
Open Text Settings Configuration API
The Text Settings Configuration endpoints allow you to read and customise a group of parameters for the Minerva Open Text API. These parameters will act as constants and do not need to be sent at each API call.
Get Text Settings Configuration Request
GET https://open.faceit.com/minerva/v1/config/text-settings
Example request cURL:
curl --location --request GET 'https://open.faceit.com/minerva/v1/config/text-settings' \
--header 'faceit-gametoken: ${token}' \
--header 'Content-Type: application/json'
Headers
| Header | Type | Description |
|---|---|---|
faceit-gametoken | string | A unique UUID token issued by FACEIT used to authenticate requests to the API. |
Get Text Settings Configuration Response
Example success response
{
"logging_enabled": true,
"translation_enabled": true,
"blacklist_enabled": false,
"threshold": 0.5
}
Patch Text Settings Configuration Request
PATCH https://open.faceit.com/minerva/v1/config/text-settings
Example request cURL:
curl --location --request PATCH 'https://open.faceit.com/minerva/v1/config/text-settings' \
--header 'faceit-gametoken: ${token}' \
--header 'Content-Type: application/json' \
--data-raw '{
"translation_enabled": true,
"logging_enabled": true,
"threshold": "0.5",
"blacklist_enabled": false
}'
Headers
| Header | Type | Description |
|---|---|---|
faceit-gametoken | string | A unique UUID token issued by FACEIT used to authenticate requests to the API. |
Payload parameters
All parameters are optional, you may patch just one or any number of them at your convenience.
| Field | Type | Description |
|---|---|---|
translation_enabled | boolean | Whether you would like to use translation whenever a language is not natively supported. |
logging_enabled | boolean | Whether you would like us to retain the data for additional training for our models. |
threshold | double | The value you can make automated actions in your game, e.g. muting players, banning, etc. |
blacklist_enabled | boolean | Whether you would like to use the blacklisted terms detection feature. |
Patch Text Settings Configuration Response
A successuful PATCH request will simply return a 200 OK and an empty object in the response body.
Open Text Analyze API
The Analyze Text API allows you to send us text communications from your game to be analyzed by our internal minerva models, based on your game's settings configuration.
Post Analyze Text Request
POST https://open.faceit.com/minerva/v1/analyze-text
Example request cURL:
curl --location --request POST 'https://open.faceit.com/minerva/v1/analyze-text' \
--header 'faceit-gametoken: ${token}' \
--header 'Content-Type: application/json' \
--data-raw '{
"text": "Hello world, how are things today?",
"text_id": "47da7fc1-67af-4c30-a3f4-60863b515d19",
"game_player_id": "b0c2d6dc-de78-487e-ab3f-b319bc0d85c0",
"language": "en"
}'
Headers
| Header | Type | Description |
|---|---|---|
faceit-gametoken | string | A unique UUID token issued by FACEIT used to authenticate requests to the API. |
Payload parameters
| Parameter | Type | Description |
|---|---|---|
text | string | The chat message or comment the player has sent. This field has a max length of 30,000 characters. |
game_player_id | string | The account_id of the player in the game. |
text_id | string, optional | The id of the text message. This is an optional field, generally useful for cross-referencing with the system where text messages reside. |
language | string, optional | The language of the text message, in ISO codes 2 letters. This is an optional field, it can be filled if the game developer is aware of the language. |
Post Analyze Text Response
Each response will score one request, and will be linked to that request via the text_id.
Response parameters
| Parameter | Type | Description |
|---|---|---|
toxicity_score | double | The summary toxicity score attribute, which is compared with the threshold value. |
toxicity_subscores | object | The toxicity feature scores and names. |
is_toxic | boolean | true if toxicity_score is greater than threshold value. |
detected_language | string | The language that has been detected when scoring the toxicity. This is sent as ISO code 2 letters. |
translated_text | string | The translated chat message the player has sent, if translation is enabled for the game. |
text_id | string | The text id of the text message (as it was received in the request). |
contains_blacklisted_term | boolean | DEPRECATED.true if the text contains a blacklisted term. |
blacklisted_terms | []string | The list of found blacklisted terms. |
Example success response
{
"toxicity_score": 0.0892567,
"toxicity_subscores": {
"IDENTITY_ATTACK": 0.02153178,
"INSULT": 0.01347425,
"PROFANITY": 0.024675326,
"SEVERE_TOXICITY": 0.015071031,
"THREAT": 0.065432265,
"TOXICITY": 0.03639824
},
"is_toxic": false,
"detected_language": "en",
"text_id": "47da7fc1-67af-4c30-a3f4-60863b515d19",
"blacklisted_terms": ["bad", "words"]
}
API Errors
The API may return any of the following errors. Each response body will include a snake case error code and a message field with a description of the error.
Generic errors (all routes)
| Error | Description |
|---|---|
403 Forbidden | Missing or invalid API token. Error codes: invalid_token, missing_token. |
500 Internal Server Error | Something went wrong on FACEIT's side. Error code: internal. |
GET /config/text-settings
| Error | Description |
|---|---|
404 Not Found | Text settings missing for this game's config. Error code: text_settings_not_found. |
PATCH /config/text-settings
| Error | Description |
|---|---|
400 Bad Request | The API request is malformed; usually due to an incorrect threshold value (should be a float value between 0 and 1). Error code: wrong_threshold. |
POST /analyze-text
| Error | Description |
|---|---|
400 Bad Request | The API request is malformed; examples include text field empty, malformed language fields and text sent containing only emojis or special characters. Error codes: empty_text, malformed_language, unprocessable_text, text_too_long. |
412 Precondition Failed | Missing configuration for the provided API token; examples include translation disabled in config but required for a request or text settings missing. Error codes: translation_disabled, no_text_settings, blacklist_not_found. |
Other errors
If you get any other error that hinders your integration with the Minerva API, please reach out to your technical integration contact.