Introduction

The Tier2AI API is a simple JSON API which provides access to our text classification machine learning model. To make a request, simply send an HTTP POST with a raw JSON body to https://ai-api.tier2.tech:2053

Overview

There are three elements in the root JSON object which are required.

"markers" is a list of categories for which you would like to to the input_text. Any text input is accepted here, we provide examples, but the model will understand any category names that an average English speaker would.

"input_text" is the text for which you would like to match to one or more categories.

"multinomial" can be true or false. For text classification tasks where there may be more than one correct category, or no correct categories, this should be set to true. For tasks where there is exactly one correct category, this should be set to false.

Interpreting The Results

The results will return a percentage for each category. You can try some test data to get a feel for where the thresholds should be for the scores, but this is the numbers we have come up with.

For "multinomial"==true: Greater than 94 is a match. If nothing is greater than 94, but some things are greater than 80, then the highest score is a match. If nothing is greater than 80, there is no match.

For "multinomial"==False: Whichever score is the highest is the match

Authentication

There is no authentication for the free tier of the API, commercial users paying for a license will be issued an API key which is passed with the URL as a GET Attribute "api_key".

Error Codes

The API will return JSON with the root element "success" set to false in the case of an error. The HTTP status code will also be of value 400 or greater. When "success"==false, the "result" element will be a string explaining the cause of the error.

Rate limit

The free tier allows 100 programmatic requests in a 24-hour period. The free tier does not permit the use of the API for commercial purposes.

There can be a maximum of 20 markers per request, but you can have unlimited markers simply by sending multiple requests to the API, using 20 markers at a time.

input_text is currently limited to 320 characters per request for the free tier.