Hexis API (1.0.0)

Introduction

Hexis API is a RESTful API that lets you programmatically interact with language analysis tools built at our lab. At the moment this includes a high-performance text classification model for hate speech detection.

Using the API

Getting Started

Hexis API is designed to be straightforward to use. You can use the language and platform of your choice to make requests. To get a feel for the API, you can also use a tool like Postman or Insomnia.

To help you get started, this documentation provides code examples in Javascript, Python, PHP, and Unix shell. They illustrate how to post requests and receive responses in JSON format.

API Endpoint

This API uses a base path of https://api.hexis.ai. It is only available via a SSL-secured HTTP connection.

Client Libraries

To work with Hexis API, you can either use standard network libraries for the programming language of your choice, or use the Swagger Generator 3 tool to auto-generate Hexis API client libraries for a variety of languages. We do not provide any guarantees that these autogenerated libraries are compatible with our API (e.g. some libraries may not work with Bearer authentication). You can find our OpenAPI 3.0 specification here.

Exchange Format

The HTTP content type is application/json and the payloads exchanged between a client and the REST-endpoint are valid JSON objects. Other things to note in the text content: Double quotes (") need to be escaped (\") and line breaks should be replaced with |LBR|.

Classification Score

Hexis API's scores are an indication of probability, not severity. Higher numbers represent a higher likelihood that the patterns in the text resemble patterns in comments that people have tagged as offensive. These scores are intended to let developers pick a threshold and review or ignore scores below that point. Although the number is not a score of how offensive a particular comment is, the threshold should be set according to the use case at hand.

In a high-recall setting where it is favorable to deal with false positives instead of false negatives, one can choose a point around 0.5 or above. While it is possible to mistakenly flag a message that is only mildly toxic (ideally there is a manual review process in place), this setting will catch the less salient, implicit cases.

On the other hand, there is the high-precision setting where the priority is to automatically filter only definitive cases of offensive language. Here it's safe to choose a point around 0.9 or above.

As a simple heuristic: If you do moderation manually, a sensible threshold value would be 0.5. Alternatively, you could just use the raw classification scores to rank items for review. If you want to do moderation without human intervention, you could pick a threshold value of 0.9 (and be potentially overblocking in a few cases) or 0.99 (and be potentially underblocking in a few cases).

Rate Limiting

The REST-endpoint allows a maximum of 10 requests per second. Once this limit is reached, calls to the endpoint will start returning errors with an HTTP status code of 429. The maximum request body size is 10 kilobytes. Requests larger than this trigger a status code of 413. Keep in mind though that the maximum input size for the classification model is 120 words. Any request larger than this will be split into 120-word sized parts and counted seperately. If you are hitting the limit of the free tier, a status code of 401 will be issued.

In practice, you don't need to think about the timing in between requests, as small bursts of excessive requests are still being processed by the endpoint. The exception to this is bulk processing, where you should implement a 100ms pause in between requests.

Customizing the API

In case you want to build a custom model with us, this is the specification for the training data.

Annotation Scheme

We largely follow the annotation guidelines of the GermEval Shared Task on the Identification of Offensive Language as described e.g. in the Overview of the GermEval 2018 Shared Task on the Identification of Offensive Language. We implement Task 1: Coarse-grained Binary Classification, where postings are labeled as either OFFENSE or OTHER, and optionally Task 2: Fine-grained 4-way Classification, where postings are labeled as either PROFANITY, INSULT, ABUSE, or OTHER, and extend it by another class, namely THREAT.

File Format

The data should be placed in a UTF-8 encoded plain text file. One training example per line, in the following format:

<TEXT> tab <LABEL-TASK-I> tab <LABEL-TASK-II>

Line breaks in the text should be replaced with |LBR|.

Authentication

Bearer

Security Scheme Type HTTP
HTTP Authorization Scheme bearer
Bearer format "JWT"

Offensive Language Detection

Authorizations:
path Parameters
language
required
string

Language code. Possible values are en, de

model
required
string

Model identifier. Possible values are v1

Request Body schema: application/json
text
required
string

Input text

Responses

200

OK

Response Schema: application/json
scores
object

List of scores

400

Bad Request

401

Unauthorized

413

Request Entity Too Large

429

Too Many Requests

post/off/{language}/{model}
/off/{language}/{model}

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "text": "string"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "scores":
    [
    ]
}