NAV Navbar
Logo
shell python ruby php javascript java
Version: v2 v3

Introduction

Welcome to the MonkeyLearn API v3 documentation.

Here you’ll find everything you need to access the MonkeyLearn API. You can use it to classify, extract, or manage your custom models programmatically.

We provide a REST API that you can access directly or through a client library.

Currently, we officially support client libraries for the following programming languages:

Client Libraries

Python

The Python client can be installed via pip:

$ pip install monkeylearn

Ruby

The Ruby client can be installed as a gem:

$ gem install monkeylearn

Javascript

The Node.js client can be installed via npm:

$ npm install monkeylearn

PHP

The PHP client can be installed via Composer:

You can use autoloader from Composer by:

{
    "require": {
        "monkeylearn/monkeylearn-php": "~0.1"
    }
}

Alternatively, if you don’t want to use Composer, clone the code and include this line in your code:

require 'autoload.php';

Java

The Java client can be installed via Maven:

<dependency>
  <groupId>com.monkeylearn</groupId>
  <artifactId>monkeylearn-java</artifactId>
  <version>0.1.5</version>
  <scope>compile</scope>
</dependency>

Alternatively, if you want to compile it yourself:

$ git clone git@github.com:monkeylearn/monkeylearn-java
$ cd monkeylearn-java
$ mvn install

You can also download the compiled jar.

R

The R client library (documentation) is maintained by ropensci.

To install the stable CRAN version:

install.packages("monkeylearn")

To install the development version:

devtools::install_github("ropensci/monkeylearn")

API Version

Currently, the latest MonkeyLearn API version is v3.2.

MonkeyLearn uses a MAJOR.MINOR versioning schema:

The current version is added as a header in every API response:

X-Api-Version: v3.2

The Changelog is available below.

Client library versions

Client library versions always share the Major and Minor numbers of the API version they support, followed by a third number (usually called the Patch number) that represents the revision of the sdk internal code.

Authentication

Request example

curl -H "Authorization: Token [YOUR_TOKEN]" \
"[API_ENDPOINT]"
from monkeylearn import MonkeyLearn

ml = MonkeyLearn('[YOUR_TOKEN]')
require 'monkeylearn'

Monkeylearn.configure do |c|
  c.token = '[YOUR_TOKEN]'
end
<?php

require 'autoload.php';

$ml = new MonkeyLearn\Client('[YOUR_TOKEN]');
?>
var MonkeyLearn = require('monkeylearn');

var ml = new MonkeyLearn('[YOUR_TOKEN]');
import com.monkeylearn.MonkeyLearn;
import com.monkeylearn.MonkeyLearnException;

public class App {
    public static void main( String[] args ) throws MonkeyLearnException {
        MonkeyLearn ml = new MonkeyLearn("[YOUR_TOKEN]");
    }
}

Make sure to replace [YOUR_TOKEN] with your API Token.

MonkeyLearn requires that you authenticate by sending an API Token with each request to grant you access to the API.

Every MonkeyLearn account has its own API Token. If you don’t have an account yet, you can register at our website.

Once you have an account, you will find your API Token in your account settings page.

Note that teams also may have an API Token associated. If you are part of a team and want to use your team token, you can find it on the teams settings page.

MonkeyLearn expects for the API Token to be included in every API request in the Authorization header with a value of “Token ” and followed by the token itself. This is what it would look like:

Authorization: Token [YOUR_TOKEN]

If you don’t provide the header, a 401 - FORBIDDEN response with the following body will be returned:

{
    "status_code": 401,
    "error_code": "AUTH_HEADER",
    "detail": "Authentication credentials were not provided. Make sure you are sending the HTTP Authentication headers properly."
}

If you provide an invalid token, you will get a 401 - FORBIDDEN response with the following body:

{
    "status_code": 401,
    "error_code": "AUTH_HEADER_TOKEN",
    "detail": "Invalid token."
}

Error responses

Status codes

MonkeyLearn API uses HTTP status codes in responses to indicate the success or failure of a request.

The various HTTP status codes we might return are listed below.

Code Description
200
OK
The request was processed successfully.
400
BAD REQUEST
The server could not parse the request. If you’ve sent a JSON in the request body, check it’s well formed.
401
UNAUTHORIZED
Not authorized to access this resource. Usually, this is related to an error with the API Token (see Authentication for more details)
403
FORBIDDEN
You are not allowed to perform the requested action on the resource.
404
NOT FOUND
The resource does not exist or you don’t have access to it. Check the URL.
405
METHOD NOT ALLOWED
The specified URL does not allow the specified HTTP method. Check the URL and Method.
422
VALIDATION ERROR
You sent an invald parameter. Verify the data you have sent, especially the parameters query string or the structure of the JSON body (if any of those were given).
423
LOCKED
The resource requested is temporarilly offline. There’s nothing wrong with the request itself. Trying again later should fix this.
429
TOO MANY REQUESTS
Your request was throttled. You have reached your request limit (see Rate limiting for more details)
500
INTERNAL SERVER ERROR
We had a problem with our server. The developers have automatically been notified. Try again later or contact support if you need immediate assistance.
503
SERVICE UNAVAILABLE
The API is temporarily offline for maintenance. Please try again later.

Error response body

For client errors (4xx) and server errors (5xx), we will also include extra information about what went wrong encoded as a JSON in the response body.

As we saw in the Authentication section, if you provide an invalid API Token in the Authentication header, you’ll get the following response body:

{
    "status_code": 401,
    "error_code": "AUTH_HEADER_TOKEN",
    "detail": "Invalid token."
}

The fields below are the fields you’ll get in a JSON error response body:

Field Description
status_code The status code from the response. Check out Status codes for a list of possible values.
error_code A parseable reason of why the request failed. Check out Error codes for a list of possible values.
detail A human-readable detail about the cause of the error. Try to avoid parsing this value since it can change over time.

Error codes

The error_code field in an error response body is more specific than the status_code field and it is more suitable for parsing than the detail field.

Code Description
INTERNAL_SERVER An internal server error occurred. Usually, this means there’s nothing wrong with the request itself, but the intervention of a MonkeyLearn developer is required to debug it and fix it. Developers are automatically notified when these errors occur.
REQUEST_PARAM Generic parameter error. Usually, when there’s something wrong with the request params you’ll get one of the more specific parameter related error codes below. Check the detail field for more information.
REQUEST_PARAM_MISSING A required parameter is missing in the request body or URL (path or query string). Check the detail field for detailed information.
REQUEST_PARAM_PARSE The type or structure of a parameter is invalid. Check the detail field for detailed information.
REQUEST_PARAM_INVALID_VALUE The value of a parameter is invalid. Check the detail field for more information.
AUTH_HEADER The Authorization header is missing.
AUTH_HEADER_TOKEN The token provided in the Authorization header is invalid.
FORBIDDEN You are not allowed to perform the requested action on the resource. Check the detail field for more information.
MODEL_LIMIT You have reached the custom model limit for your current plan.
MODEL_FORBIDDEN_READ You do not have read access to the model.
MODEL_FORBIDDEN_WRITE You do not have write access to the model.
RESOURCE_NOT_FOUND The resource doesn’t exist or you don’t have read access. Check the URL.
MODEL_NOT_FOUND The classifier or extractor does not exist or you do not have read access. Check the URL.
TAG_NOT_FOUND The classifier tag doesn’t exist or you don’t have read access to the classifier. Check the URL.
PAGE_NOT_FOUND On endpoints that support pagination, the requested page doesn’t exist. Check the pagination query parameters.
PLAN_QUERY_LIMIT You have hit the maximum monthly requests for your current plan. Check the query limits section below.
CONCURRENCY_RATE_LIMIT You have sent more than five requests in less than a second, so the request has been throttled. Check the rate limiting section below.
PLAN_RATE_LIMIT You have sent too many request within a minute. The limit depends on your current plan, check the rate limiting section below.
RESOURCE_STATE_INVALID The resource is currently unavailable.
PRODUCTION_MODEL_MISSING The production model has not been deployed yet.

Rate Limiting

The MonkeyLearn API is rate limited by number of requests per time window. There are two limits with two time windows. The concurrency rate limit restricts the requests you can make within a second and the standard rate limit limits the requests you can make within a minute.

Concurrency rate limit

The concurrency rate limit limits the requests you can make within a second. It’s a security hard limit and it’s the same for every user. It helps prevent abusive use of shared resources and it also helps users to plan the requests by scheduling in their codebase. This can only be disabled if you have an Enterprise Plan with dedicated servers.

Time window Maximum requests
1 second 5 requests

A throttled request will get a response with a 429 status code and a body like the following one:

{
    "status_code": 429,
    "error_code": "CONCURRENCY_RATE_LIMIT",
    "detail": "Request was throttled. Too many concurrent requests."
}

Plan rate limit

The plan rate limit restricts the requests you can make within a minute and depends on the user plan:

Plan Time window Maximum requests
Free 60 seconds 20 requests
Team 60 seconds 60 requests
Business 60 seconds 120 requests
Enterprise 60 seconds Unlimited on dedicated servers

A throttled request will get a response with a 429 status code and a body like the following one:

{
    "status_code": 429,
    "error_code": "PLAN_RATE_LIMIT",
    "seconds_to_wait": 23,
    "detail": "Request was throttled. Expected available in 23 seconds."
}

As you can see, the response specifies how many seconds you’ll have to wait for the API to become available.

Query Limits

Every MonkeyLearn Plan allows you to make a certain number of queries each month.

First, it’s important to define a query. A query is not a request. A request may count as none, one, or more queries. Currently, only two endpoints consume queries, that is, the classify and extract endpoints. The number of queries will be the count of successfull classifications or extractions for the texts given in the text_list parameter.

The following are the current query limits:

Plan Monthly queries
Free 300 queries
Team 30,000 queries
Business 300,000 queries
Enterprise Unlimited queries on dedicated servers

Every response sends some headers to help you track the queries you have consumed in the request and the queries you have left.

Header Description
X-Query-Limit-Limit Your current query limit
X-Query-Limit-Remaining The number of queries your account has left to use
X-Query-Limit-Request-Queries The number of queries consumed by this request

Pagination & Order

Endpoints that list resources support pagination and ordering. They accept the following query string parameters:

Request example

curl -H "Authorization:Token [YOUR_TOKEN]" \
-H "Content-Type: application/json" \
-i \
"https://api.monkeylearn.com/v3/classifiers/?page=2&per_page=5&order_by=-public,name"
from monkeylearn import MonkeyLearn

ml = MonkeyLearn('[YOUR_TOKEN]')
response = ml.classifiers.list()
print(response.body)
require 'monkeylearn'

Monkeylearn.configure do |c|
  c.token = '[YOUR_TOKEN]'
end

response = Monkeylearn.classifiers.list()
puts response.body
<?php
require 'autoload.php';

$ml = new MonkeyLearn\Client('[YOUR_TOKEN]');
$res = $ml->classifiers->list_classifiers();
var_dump($res->result);
?>
var MonkeyLearn = require('monkeylearn');

var ml = new MonkeyLearn('[YOUR_TOKEN]');
var p = ml.classifiers.list();
p.then(function (res) {
    console.log(res.result);
});
import com.monkeylearn.MonkeyLearn;
import com.monkeylearn.MonkeyLearnResponse;
import com.monkeylearn.MonkeyLearnException;

public class App {
    public static void main( String[] args ) throws MonkeyLearnException {
        MonkeyLearn ml = new MonkeyLearn("[YOUR_TOKEN]");
        MonkeyLearnResponse res = ml.classifiers.list();
        System.out.println( res.jsonResult );
    }
}

Response example

[
    {
        "id": "cl_nGAmTLFv",
        "name": "Hotel Reviews Classifier",
        "description": "",
        "is_public": true,
        "model_version": "v3.0",
        "industries": [
            "business_intelligence",
            "customer_support",
            "marketing",
            "other"
        ],
        "priority": 7,
        "last_trained": "2018-04-20T20:05:14.681116+00:00"
    },
    {
        "id": "cl_sk5zky4q",
        "name": "Plant Classifier",
        "description": "Classify the plants!",
        "is_public": false,
        "model_version": "v3.0",
        "industries": [],
        "priority": 0,
        "last_trained": "2018-04-23T18:26:49.221156+00:00",
        "last_deployed": "2018-05-15T22:26:49.345345+00:00"
    }
]
Parameter Description
page Specifies the page you want to retrieve.
per_page Specifies the maximum number of items each page should have.
order_by Specifies the order of the list. You can order using any of the field names, either in ascending or desceding order (adding ‘-’ before the name). Also, you can order by more than one criteria, separating them with commas. Added in v3.2.

For instance, if you want to get the second page of a list, with 2 elements per page and getting the custom models first ordered by name; then the string parameters would be like in the request example.

Each parameter has different defaults depending on the endpoint. Check the specific endpoint documentation.

Responses on enpoints with pagination will also include the following headers:

Header Description
Link Links to the next and last pages, as specified in RFC 5988.
X-Pagination-Total-Pages The total number of pages in this resource for the chosen value of per_page.

Classifier API

Classify

https://api.monkeylearn.com/v3/classifiers/[MODEL_ID]/classify/

Classifies texts with a given classifier.

Request example

curl \
--data '{"data": ["first text", {"text": "second text", "external_id": "ANY_ID"}, ""]}' \
-H "Authorization: Token [YOUR_TOKEN]" \
-H "Content-Type: application/json" \
-i \
"https://api.monkeylearn.com/v3/classifiers/[MODEL_ID]/classify/"
from monkeylearn import MonkeyLearn

ml = MonkeyLearn('[YOUR_TOKEN]')
data = ["first text", {"text": "second text", "external_id": "ANY_ID"}, ""]
model_id = '[MODEL_ID]'
response = ml.classifiers.classify(model_id, data)
print(response.body)
require 'monkeylearn'

Monkeylearn.configure do |c|
  c.token = '[YOUR_TOKEN]'
end

data = ['First text', {text: 'Second text', external_id: '2'}]
model_id = '[MODEL_ID]'
response = Monkeylearn.classifiers.classify(model_id, data)
puts response.body
<?php
require 'autoload.php';

$ml = new MonkeyLearn\Client('[YOUR_TOKEN]');
$data = ["first text", "second text"];
$model_id = '[MODEL_ID]';
$res = $ml->classifiers->classify($model_id, $data, true);
var_dump($res->result);
?>
var MonkeyLearn = require('monkeylearn');

var ml = new MonkeyLearn('[YOUR_TOKEN]');
var model_id = '[MODEL_ID]';
var data = ["first text", "second text"];
var p = ml.classifiers.classify(model_id, data, true);
p.then(function (res) {
    console.log(res.result);
});
import com.monkeylearn.MonkeyLearn;
import com.monkeylearn.MonkeyLearnResponse;
import com.monkeylearn.MonkeyLearnException;

public class App {
    public static void main( String[] args ) throws MonkeyLearnException {
        MonkeyLearn ml = new MonkeyLearn("[YOUR_TOKEN]");
        String modelId = "[MODEL_ID]";
        String[] textList = {"first text", "second text"};
        MonkeyLearnResponse res = ml.classifiers.classify(modelId, textList, true);
        System.out.println( res.arrayResult );
    }
}

Response example

[
    {
        "text": "first text",
        "external_id": null,
        "error": false,
        "classifications": [{
            "tag_name": "Misc",
            "tag_id": 340,
            "confidence": 0.76
        }]
    }, {
        "text": "second text",
        "external_id": "ANY_ID",
        "error": false,
        "classifications": [{
            "tag_name": "Misc",
            "tag_id": 340,
            "confidence": 0.71
        }]
    }, {
        "text": "",
        "external_id": null,
        "error": true,
        "error_detail": "Invalid text, empty strings are not allowed",
        "classifications": null
    }
]

Request parameters

Accepts parameters in the request body as a JSON with the following attributes:

Attribute Default Description
dataArray [string or object]
REQUIRED
A list of up to 500 data elements to classify. Each element must be either a string with the text or a data object.
production_modelboolean false Indicates if the classifications are performed by the production model. Only use this parameter on custom models. Note that you first need to deploy your model to production either from the UI model settings or by using the Classifier deploy API endpoint.

A data object has the following attributes:

Attribute Default Description
textstring
REQUIRED
The text to classify. It cannot be an empty string.
external_idstring null An ID for the text that will be included in the response of its corresponding classification.

Response

The response body of this endpoint is a list where each item is the classification result object for its positional corresponding text. Each of these objects has the following attributes:

Attribute Description
textstring The original text from the request.
external_idinteger The value given in the request as the external_id for this text. If not given, the value is null.
errorboolean Indicates if the classification was performed (true) or an error was detected (false).
error_detailstring Details about the error. Only present if an error occurred.
classificationsArray [object] A list of classification objects that represent the result tags of the classification.

The classification object has the following attributes:

Attribute Description
tag_namestring The name of the tag.
tag_idinteger The ID of the tag.
confidencefloat A value from 0 to 1 that indicates the confidence of the classification where 1 represents the highest possible confidence.
parentsarray [object]
Deprecated
A list of the classification objects for each parent of the result tag, ordered from top to bottom. Only valid for v2 models.

Classifier detail

https://api.monkeylearn.com/v3/classifiers/[MODEL_ID]/

Returns information about a classifier including its settings, stats, and tags.

Request example

curl -H "Authorization:Token [YOUR_TOKEN]" \
-H "Content-Type: application/json" \
-i \
"https://api.monkeylearn.com/v3/classifiers/[MODEL_ID]/"
from monkeylearn import MonkeyLearn

ml = MonkeyLearn('[YOUR_TOKEN]')
model_id = '[MODEL_ID]'
response = ml.classifiers.detail(model_id)
print(response.body)
require 'monkeylearn'

Monkeylearn.configure do |c|
  c.token = '[YOUR_TOKEN]'
end

response = Monkeylearn.classifiers.detail('[MODEL_ID]')
puts response.body
<?php
require 'autoload.php';

$ml = new MonkeyLearn\Client('[YOUR_TOKEN]');
$model_id = '[MODEL_ID]';
$res = $ml->classifiers->detail($model_id);
var_dump($res->result);
?>
var MonkeyLearn = require('monkeylearn');

var ml = new MonkeyLearn('[YOUR_TOKEN]');
var model_id = '[MODEL_ID]';
var p = ml.classifiers.detail(model_id);
p.then(function (res) {
    console.log(res.result);
});
import com.monkeylearn.MonkeyLearn;
import com.monkeylearn.MonkeyLearnResponse;
import com.monkeylearn.MonkeyLearnException;

public class App {
    public static void main( String[] args ) throws MonkeyLearnException {
        MonkeyLearn ml = new MonkeyLearn("[YOUR_TOKEN]");
        String modelId = "[MODEL_ID]";
        MonkeyLearnResponse res = ml.classifiers.detail(modelId);
        System.out.println( res.jsonResult );
    }
}

Response example

{
    "id": "cl_nWnsvxrV",
    "name": "Example Classifier",
    "description": "This text should describe what the classifiers is about",
    "is_public": true,
    "model_version": "v3.0",
    "created": "2018-01-21T12:21:11+00:00",
    "industries": ["customer_support", "marketing"],
    "priority": 2,
    "last_trained": "2018-04-03T17:32:09+00:00",
    "last_deployed": "2018-05-15T22:26:49.345345+00:00",
    "model": {
        "settings": {
            "algorithm": "svm",
            "language": "en",
            "max_features": 10000,
            "ngram_range": [1, 3],
            "use_stemming": true,
            "preprocess_numbers": true,
            "preprocess_social_media": false,
            "normalize_weights": true,
            "stopwords": ["i", "me", "my", ...],
            "whitelist": []
        },
        "stats": {
            "accuracy": 0.750,
            "average_f1_score": 0.642
        },
        "tags": [{
                "id": 10,
                "name": "Animals"
            }, {
                "id": 11,
                "name": "Plants"
        }]
    },
    "production_model": {...}
}

Request parameters

Does not take any parameters

Response

Property Description
idstring The ID of the model. It always starts with cl_.
namestring The name of the model.
descriptionstring The description of the model.
is_publicboolean Indicates whether the classifier is public or custom. Added in v3.1.
model_versionstring The version of the model. The version of all new models is v3.0.
createdstring The date and time when this model was created, in ISO format. If the model has never been trained, the returned value will be null. Added in v3.2.
industriesArray [string] The list of industries where this module is suggested to be used. Read-only field, valid for public models. Added in v3.2.
priorityinteger Ordering criteria priority. The higher the value the higher the priority. Read-only field, valid for public models. The Added in v3.2.
last_trainedstring The date and time when this model was last trained, in ISO format. If the model has never been trained, the returned value will be null.
last_deployedstring The date and time when this model was last deployed, in ISO format. If the model has never been deployed, the returned value will be null. Only valid for custom models.
modelobject Information about the machine learning model of the classifier.
settingsobject The training settings of the model.
algorithmstring The algorithm used when training the model. It can either be “nb” or “svm”.
languagestring The language of the model. Here’s the list of supported languages.
max_featuresinteger The maximum number of features used when training the model. It’s a number between 10 and 100,000.
ngram_rangeArray [integer] The n-gram range used when training the model. It’s an array with two numbers between 1 and 3. They indicate the minimum and the maximum n for the n-grams used, respectively.
use_stemmingboolean Indicates whether stemming is used when training the model.
preprocess_numbersboolean Indicates whether number preprocessing is done when training the model.
preprocess_social_mediaboolean Indicates whether preprocessing of social media is done when training the model.
normalize_weightsboolean Indicates whether weights are normalized when training the model.
stopwordsArray [string] The list of stopwords used when training the model.
whitelistArray [string] The whitelist of words used when training the model.
statsobject Statistics of the model. If the model has never been trained, the value will be null.
accuracyfloat The accuracy of the model. If the model has never been trained, the returned value will be null.
average_f1_scorefloat The average of the F1 score of all the tags in the model. If the model has never been trained, the returned value will be null.
tagsarray [object] A list of tag objects with the information about each of the tags of the model.
production_modelobject Information about the production model of the classifier. The keys are the same as the ones in model. If there is no production model deployed, the returned value is null. Only valid for custom models.

The tag object has the following attributes:

Attribute Description
idinteger The ID of the tag.
namestring The name of the tag.
parent_idinteger
Deprecated
The ID of the parent tag. Only valid for v2 models.

The supported languages are:

Parameter Language
"en" English
"es" Spanish
"fr" French
"de" German
"it" Italian
"pt" Portuguese
"nl" Dutch
"ru" Russian
"fi" Chinese
"hu" Japanese
"ro" Korean
"sv" Arabic
"zh" Danish
"ja" Swedish
"ko" Romanian
"ar" Hungarian
"da" Finnish
"no" Norwegian
"multi_language" Other or multiple languages

Create Classifier

https://api.monkeylearn.com/v3/classifiers/

Creates a new classifier.

Request example

curl --data '{"name": "New Classifier"}' \
-H "Authorization:Token [YOUR_TOKEN]" \
-H "Content-Type: application/json" \
-i \
"https://api.monkeylearn.com/v3/classifiers/"
from monkeylearn import MonkeyLearn

ml = MonkeyLearn('[YOUR_TOKEN]')
response = ml.classifiers.create('New classifier')
print(response.body)
require 'monkeylearn'

Monkeylearn.configure do |c|
  c.token = '[YOUR_TOKEN]'
end

response = Monkeylearn.classifiers.create('New Classifier')
puts response.body
<?php
require 'autoload.php';

$ml = new MonkeyLearn\Client('[YOUR_TOKEN]');
$res = $ml->classifiers->create('New classifier');
var_dump($res->result);
?>
var MonkeyLearn = require('monkeylearn');

var ml = new MonkeyLearn('[YOUR_TOKEN]');
var p = ml.classifiers.create('New classifier');
p.then(function (res) {
    console.log(res.result);
});
import com.monkeylearn.MonkeyLearn;
import com.monkeylearn.MonkeyLearnResponse;
import com.monkeylearn.MonkeyLearnException;

public class App {
    public static void main( String[] args ) throws MonkeyLearnException {
        MonkeyLearn ml = new MonkeyLearn("[YOUR_TOKEN]");
        MonkeyLearnResponse res = ml.classifiers.create("New classifier");
        System.out.println( res.jsonResult );
    }
}

Response example

{
    "id": "cl_sk5zky4q",
    "name": "New Classifier",
    "description": "",
    "is_public": false,
    "model_version": "v3.0",
    "created": "2018-01-21T12:21:11+00:00",
    "industries": [],
    "priority": 0,
    "last_trained": null,
    "last_deployed": null,
    "model": {
        "settings": {
            "algorithm": "nb",
            "language": "en",
            "max_features": 10000,
            "ngram_range": [1, 1],
            "use_stemming": true,
            "preprocess_numbers": true,
            "preprocess_social_media": false,
            "normalize_weights": true,
            "stopwords": ["i", "me", "my", ...],
            "whitelist": []
        },
        "stats": null,
        "tags": []
    },
    "production_model": null
}

Request parameters

Accepts parameters in the request body as a JSON with the following attributes:

Parameter Default Description
namestring
Required
The name of the model.
descriptionstring "" The description of the model.
algorithmstring "nb" The algorithm used when training the model. It can either be “nb” or “svm”.
languagestring "en" The language of the model. It must be one of the supported languages.
max_featuresinteger 10000 The maximum number of features used when training the model. It’s a number between 10 and 100000.
ngram_rangearray [integer] [1, 1] Indicates the n-gram range used when training the model. It’s a list of two numbers between 1 and 3. They indicate the minimum and the maximum n for the n-grams used, respectively.
use_stemmingboolean true Indicates whether stemming is used when training the model.
preprocess_numbersboolean true Indicates whether number preprocessing is done when training the model.
preprocess_social_mediaboolean false Indicates whether preprocessing of social media is done when training the model.
normalize_weightsboolean true Indicates whether weights will be normalized when training the model.
stopwordsboolean orarray [string] true The list of stopwords used when training the model. Use false for no stopwords, true for the default stopwords, or an array of strings for custom stopwords.
whitelistarray [string] [] The whitelist of words used when training the model.

Response

The response contains the details about the classifier that has been created.

Edit Classifier

https://api.monkeylearn.com/v3/classifiers/[MODEL_ID]/

Updates a classifier name, description, and settings.

Request example

curl -X "PATCH" \
--data '{"preprocess_social_media":true, "description": "The classifier will use preprocessing for social media now"}' \
-H "Authorization:Token [YOUR_TOKEN]" \
-H "Content-Type: application/json" \
-i \
"https://api.monkeylearn.com/v3/classifiers/[MODEL_ID]/"
from monkeylearn import MonkeyLearn

ml = MonkeyLearn('[YOUR_TOKEN]')
model_id = '[MODEL_ID]'
response = ml.classifiers.edit(
    model_id,
    preprocess_social_media=True,
    description='The classifier will use preprocessing for social media now'
)
print(response.body)
require 'monkeylearn'

Monkeylearn.configure do |c|
  c.token = '[YOUR_TOKEN]'
end

model_id = '[MODEL_ID]'
response = Monkeylearn.classifiers.edit(
    model_id,
    description: 'The classifier will use preprocessing for social media now',
    preprocess_social_media: true
)
puts response.body
// This endpoint is not supported in the PHP SDK yet. Coming soon!
// This endpoint is not supported in the Javascript SDK yet. Coming soon!
// This endpoint is not supported in the Java SDK yet. Coming soon!

Response example

{
    "id": "cl_sk5zky4q",
    "name": "Classifier name",
    "description": "The classifier will use preprocessing for social media now",
    "is_public": false,
    "model_version": "v3.0",
    "created": "2018-01-21T12:21:11+00:00",
    "industries": [],
    "priority": 0,
    "last_trained": "2018-04-23T18:26:49.221156+00:00",
    "last_deployed": "2018-05-15T22:26:49.345345+00:00",
    "model": {
        "settings": {
            "algorithm": "nb",
            "language": "en",
            "max_features": 10000,
            "ngram_range": [1, 1],
            "use_stemming": true,
            "preprocess_numbers": true,
            "preprocess_social_media": true,
            "normalize_weights": true,
            "stopwords": ["i", "me", "my", ...],
            "whitelist": []
        },
        "stats": {
          "accuracy": 0.750,
          "average_f1_score": 0.642
        },
        "tags": [{
            "id": 10,
            "name": "Animals"
          }, {
            "id": 11,
            "name": "Plants"
        }]
    },
    "production_model": {...}
}

Request parameters

Accepts parameters in the request body as a JSON. They are the same request parameters as in Create classifier, except there are no required parameters.

Response

The response contains the details about the classifier that has been created.

Delete Classifier

https://api.monkeylearn.com/v3/classifiers/[MODEL_ID]/

Deletes a classifier. This action cannot be undone.

Request example

curl -X "DELETE" \
-H "Authorization:Token [YOUR_TOKEN]" \
-H "Content-Type: application/json" \
-i \
"https://api.monkeylearn.com/v3/classifiers/[MODEL_ID]/"
from monkeylearn import MonkeyLearn

ml = MonkeyLearn('[YOUR_TOKEN]')
model_id = '[MODEL_ID]'
response = ml.classifiers.delete(model_id)
print(response.body)
require 'monkeylearn'

Monkeylearn.configure do |c|
  c.token = '[YOUR_TOKEN]'
end

response = Monkeylearn.classifiers.delete('[MODEL_ID]')
puts response.body
<?php
require 'autoload.php';

$ml = new MonkeyLearn\Client('[YOUR_TOKEN]');
$model_id = '[MODEL_ID]';
$res = $ml->classifiers->delete($model_id);
var_dump($res->result);
?>
var MonkeyLearn = require('monkeylearn');

var ml = new MonkeyLearn('[YOUR_TOKEN]');
var model_id = '[MODEL_ID]';
var p = ml.classifiers.delete(model_id);
p.then(function (res) {
    console.log(res.result);
});
import com.monkeylearn.MonkeyLearn;
import com.monkeylearn.MonkeyLearnResponse;
import com.monkeylearn.MonkeyLearnException;

public class App {
    public static void main( String[] args ) throws MonkeyLearnException {
        MonkeyLearn ml = new MonkeyLearn("[YOUR_TOKEN]");
        String modelId = "[MODEL_ID]";
        MonkeyLearnResponse res = ml.classifiers.delete(modelId);
        System.out.println( res.jsonResult );
    }
}

Request parameters

Does not take any parameters

Response

Returns an empty response body

List Classifiers

https://api.monkeylearn.com/v3/classifiers/

Returns all the available classifiers for the user. This includes their custom models, public models, and models shared in the teams the user belongs to. This endpoint supports pagination.

Request example

curl -H "Authorization:Token [YOUR_TOKEN]" \
-H "Content-Type: application/json" \
-i \
"https://api.monkeylearn.com/v3/classifiers/"
from monkeylearn import MonkeyLearn

ml = MonkeyLearn('[YOUR_TOKEN]')
response = ml.classifiers.list()
print(response.body)
require 'monkeylearn'

Monkeylearn.configure do |c|
  c.token = '[YOUR_TOKEN]'
end

response = Monkeylearn.classifiers.list()
puts response.body
<?php
require 'autoload.php';

$ml = new MonkeyLearn\Client('[YOUR_TOKEN]');
$res = $ml->classifiers->list_classifiers();
var_dump($res->result);
?>
var MonkeyLearn = require('monkeylearn');

var ml = new MonkeyLearn('[YOUR_TOKEN]');
var p = ml.classifiers.list();
p.then(function (res) {
    console.log(res.result);
});
import com.monkeylearn.MonkeyLearn;
import com.monkeylearn.MonkeyLearnResponse;
import com.monkeylearn.MonkeyLearnException;

public class App {
    public static void main( String[] args ) throws MonkeyLearnException {
        MonkeyLearn ml = new MonkeyLearn("[YOUR_TOKEN]");
        MonkeyLearnResponse res = ml.classifiers.list();
        System.out.println( res.jsonResult );
    }
}

Response example

[
    {
        "id": "cl_sk5zky4q",
        "name": "Plant Classifier",
        "description": "Classify the plants!",
        "is_public": false,
        "model_version": "v3.0",
        "created": "2018-01-21T12:21:11+00:00",
        "industries": [],
        "priority": 0,
        "last_trained": "2018-04-23T18:26:49.221156+00:00",
        "last_deployed": "2018-05-15T22:26:49.345345+00:00"
    },
    {
        "id": "cl_nGAmTLFv",
        "name": "Hotel Reviews Classifier",
        "description": "",
        "is_public": true,
        "model_version": "v3.0",
        "created": "2018-01-21T12:21:11+00:00",
        "industries": [
            "business_intelligence",
            "customer_support",
            "marketing",
            "other"
        ],
        "priority": 7,
        "last_trained": "2018-04-20T20:05:14.681116+00:00"
    },
    // ...
]

Request parameters

Accepts the following parameters as query string parameters:

Parameter Default Description
pageinteger 1 The page number you want to retrieve
per_pageinteger 20 The maximum number of items the page should have. The maximum allowed value is 50.
order_bystring -created Specifies the order of the list. You can order using any of the field names, either in ascending or desceding order (adding ‘-’ before the name). Also, you can order by more than one criteria, separating them with commas. Added in v3.2.

Response

An array of objects, each one representing one classifier. Each of these has the following attributes:

Attribute Description
idstring The ID of the model. It always starts with cl_.
namestring The name of the model.
descriptionstring The description of the model.
is_publicboolean Indicates whether the model is public or not. Added in v3.1.
model_versionstring The version of the model. The version of all the new models is v3.0.
createdstring The date and time when this model was created, in ISO format. If the model has never been trained, the returned value will be null. Added in v3.2.
industriesArray [string] The list of industries where this module is suggested to be used. Read-only field, valid for public models. Added in v3.2.
priorityinteger Ordering criteria priority. The higher the value the higher the priority. Read-only field, valid for public models. The Added in v3.2.
last_trainedstring The date and time when the model was last trained, in ISO format. If the model has never been trained, the returned value will be null.
last_deployedstring The date and time when this model was last deployed, in ISO format. If the model has never been deployed, the returned value will be null. Only valid for custom models.

Deploy

https://api.monkeylearn.com/v3/classifiers/[MODEL_ID]/deploy/

Deploys the current model to production. Note that the old production model will be overwritten and lost. The model must be trained in order to be deployed. This action cannot be undone.

Request example

curl -X POST \
-H "Authorization:Token [YOUR_TOKEN]" \
-H "Content-Type: application/json" \
-i \
"https://api.monkeylearn.com/v3/classifiers/[MODEL_ID]/deploy/"
from monkeylearn import MonkeyLearn

ml = MonkeyLearn('[YOUR_TOKEN]')
model_id = '[MODEL_ID]'
response = ml.classifiers.deploy(model_id)
print(response.body)
require 'monkeylearn'

Monkeylearn.configure do |c|
  c.token = '[YOUR_TOKEN]'
end

response = Monkeylearn.classifiers.deploy('[MODEL_ID]')
puts response.body
<?php
require 'autoload.php';

$ml = new MonkeyLearn\Client('[YOUR_TOKEN]');
$model_id = '[MODEL_ID]';
$res = $ml->classifiers->deploy($model_id);
var_dump($res->result);
?>
var MonkeyLearn = require('monkeylearn');

var ml = new MonkeyLearn('[YOUR_TOKEN]');
var model_id = '[MODEL_ID]';
var p = ml.classifiers.deploy(model_id);
p.then(function (res) {
    console.log(res.result);
});
import com.monkeylearn.MonkeyLearn;
import com.monkeylearn.MonkeyLearnResponse;
import com.monkeylearn.MonkeyLearnException;

public class App {
    public static void main( String[] args ) throws MonkeyLearnException {
        MonkeyLearn ml = new MonkeyLearn("[YOUR_TOKEN]");
        String modelId = "[MODEL_ID]";
        MonkeyLearnResponse res = ml.classifiers.deploy(modelId);
        System.out.println( res.jsonResult );
    }
}

Request parameters

Does not take any parameters

Response

Returns an empty response body

Train

https://api.monkeylearn.com/v3/classifiers/[MODEL_ID]/train/

Starts training the model. Please note that v3 models train automatically and it is not required to manually train them.

Request example

curl -X POST \
-H "Authorization:Token [YOUR_TOKEN]" \
-H "Content-Type: application/json" \
-i \
"https://api.monkeylearn.com/v3/classifiers/[MODEL_ID]/train/"
from monkeylearn import MonkeyLearn

ml = MonkeyLearn('[YOUR_TOKEN]')
model_id = '[MODEL_ID]'
response = ml.classifiers.train(model_id)
print(response.body)
require 'monkeylearn'

Monkeylearn.configure do |c|
  c.token = '[YOUR_TOKEN]'
end

response = Monkeylearn.classifiers.train('[MODEL_ID]')
puts response.body
<?php
require 'autoload.php';

$ml = new MonkeyLearn\Client('[YOUR_TOKEN]');
$model_id = '[MODEL_ID]';
$res = $ml->classifiers->train($model_id);
var_dump($res->result);
?>
var MonkeyLearn = require('monkeylearn');

var ml = new MonkeyLearn('[YOUR_TOKEN]');
var model_id = '[MODEL_ID]';
var p = ml.classifiers.train(model_id);
p.then(function (res) {
    console.log(res.result);
});
import com.monkeylearn.MonkeyLearn;
import com.monkeylearn.MonkeyLearnResponse;
import com.monkeylearn.MonkeyLearnException;

public class App {
    public static void main( String[] args ) throws MonkeyLearnException {
        MonkeyLearn ml = new MonkeyLearn("[YOUR_TOKEN]");
        String modelId = "[MODEL_ID]";
        MonkeyLearnResponse res = ml.classifiers.train(modelId);
        System.out.println( res.jsonResult );
    }
}

Request parameters

Does not take any parameters

Response

Returns an empty response body

Tag Detail

Request example

curl -H "Authorization:Token [YOUR_TOKEN]" \
-H "Content-Type: application/json" \
-i \
"https://api.monkeylearn.com/v3/classifiers/[MODEL_ID]/tags/[TAG_ID]/"
from monkeylearn import MonkeyLearn

ml = MonkeyLearn('[YOUR_TOKEN]')
model_id = '[MODEL_ID]'
tag_id = [TAG_ID]
response = ml.classifiers.tags.detail(model_id, tag_id)
print(response.body)
require 'monkeylearn'

Monkeylearn.configure do |c|
  c.token = '[YOUR_TOKEN]'
end

model_id = '[MODEL_ID]'
tag_id = [TAG_ID]
response = Monkeylearn.classifiers.tags.detail(model_id, tag_id)
puts response.body
<?php
require 'autoload.php';

$ml = new MonkeyLearn\Client('[YOUR_TOKEN]');
$model_id = '[MODEL_ID]';
$tag_id = [TAG_ID];
$res = $ml->classifiers->categories->detail($model_id, $tag_id);
var_dump($res->result);
?>
var MonkeyLearn = require('monkeylearn');

var ml = new MonkeyLearn('[YOUR_TOKEN]');
var model_id = '[MODEL_ID]';
var tag_id = [TAG_ID];
var p = ml.classifiers.categories.detail(model_id, tag_id);
p.then(function (res) {
    console.log(res.result);
});
import com.monkeylearn.MonkeyLearn;
import com.monkeylearn.MonkeyLearnResponse;
import com.monkeylearn.MonkeyLearnException;

public class App {
    public static void main( String[] args ) throws MonkeyLearnException {
        MonkeyLearn ml = new MonkeyLearn("[YOUR_TOKEN]");
        String modelId = "[MODEL_ID]";
        int tagId = [TAG_ID];
        MonkeyLearnResponse res = ml.classifiers.categories.detail(modelId, tagId);
        System.out.println( res.jsonResult );
    }
}

Response example

{
    "id": 9432,
    "name": "New Tag",
    "classifier_id": "cl_kVgQtHnW",
    "stats": {
        "precision": 0.6,
        "recall": 0.8,
        "f1_score": 0.7,
        "false_negatives": 4,
        "false_positives": 8,
        "true_negatives": 32,
        "true_positives": 45,
        "keywords": [{
            "term": "to be",
            "relevance": 1.956
        }, {
            "term": "better",
            "relevance": 1.26
        },
            //...
        ]
    }
}

https://api.monkeylearn.com/v3/classifiers/[MODEL_ID]/tags/[TAG_ID]/

Returns information about a tag.

Request parameters

Does not take any parameters

Response

Property Description
idinteger The ID of the tag.
namestring The name of the tag.
classifier_idstring The ID of the classifier this tag belongs to. It always starts with cl_.
statsobject Statistics about the tag. If the tag has never been trained, the value will be null.
precisionfloat The precision for this tag.
recallfloat The recall for this tag.
f1_scorefloat The F1 score for this tag.
false_negativesinteger The number of false negatives in the training data for this tag.
false_positivesinteger The number of false positives in the training data for this tag.
true_negativesinteger The number of true negatives in the training data for this tag.
true_positivesinteger The number of true positives in the training data for this tag.
keywordsarray [object] The list of keyword objects with the most relevant keywords for this tag.
accuracyarray [object]
Deprecated
The accuracy for the children of this tag. Only valid for v2 models.
parent_idinteger
Deprecated
The ID of the parent tag. Only valid for v2 models.

The keyword objects has the following attributes:

Attribute Description
termstring The keyword term.
relevancefloat A relevance score.

Create Tag

https://api.monkeylearn.com/v3/classifiers/[MODEL_ID]/tags/

Creates a new tag in a classifier.

Request example

curl --data '{"name": "New Tag"}'  \
-H "Authorization:Token [YOUR_TOKEN]" \
-H "Content-Type: application/json" \
-i \
"https://api.monkeylearn.com/v3/classifiers/[MODEL_ID]/tags/"
from monkeylearn import MonkeyLearn

ml = MonkeyLearn('[YOUR_TOKEN]')
model_id = '[MODEL_ID]'
response = ml.classifiers.tags.create(model_id, 'New Tag')
print(response.body)
require 'monkeylearn'

Monkeylearn.configure do |c|
  c.token = '[YOUR_TOKEN]'
end

model_id = '[MODEL_ID]'
response = Monkeylearn.classifiers.tags.create(model_id, 'New Tag')
puts response.body
<?php
require 'autoload.php';

$ml = new MonkeyLearn\Client('[YOUR_TOKEN]');
$model_id = '[MODEL_ID]';
$parent_tag_id = [TAG_ID];
$res = $ml->classifiers->categories->create($model_id, 'New Tag', $parent_tag_id);
var_dump($res->result);
?>
var MonkeyLearn = require('monkeylearn');

var ml = new MonkeyLearn('[YOUR_TOKEN]');
var model_id = '[MODEL_ID]';
var parent_tag_id = [TAG_ID];
var p = ml.classifiers.categories.create(model_id, 'New Tag', parent_tag_id);
p.then(function (res) {
    console.log(res.result);
});
import com.monkeylearn.MonkeyLearn;
import com.monkeylearn.MonkeyLearnResponse;
import com.monkeylearn.MonkeyLearnException;

public class App {
    public static void main( String[] args ) throws MonkeyLearnException {
        MonkeyLearn ml = new MonkeyLearn("[YOUR_TOKEN]");
        String modelId = "[MODEL_ID]";
        int parentTagId = [TAG_ID];
        MonkeyLearnResponse res = ml.classifiers.categories.create(modelId, "New Tag",
                                                                    parentTagId);
        System.out.println( res.jsonResult );
    }
}

Response example

{
    "id": 9312,
    "name": "New Tag",
    "classifier_id": "cl_kVgQtHnW",
    "stats": null
}

Request parameters

Accepts parameters in the request body as a JSON with the following attributes:

Parameter Description
namestring
Required
The name of the tag.
parent_idinteger
Deprecated
The ID of the parent tag. Only valid for v2 models.

Response

The response contains details about the tag that has been created.

Edit Tag

https://api.monkeylearn.com/v3/classifiers/[MODEL_ID]/tags/[TAG_ID]/

Updates a tag in a classifier.

Request example

curl -X "PATCH" \
--data '{"name": "Edited tag name"}'  \
-H "Authorization:Token [YOUR_TOKEN]" \
-H "Content-Type: application/json" \
-i \
"https://api.monkeylearn.com/v3/classifiers/[MODEL_ID]/tags/[TAG_ID]/"
from monkeylearn import MonkeyLearn

ml = MonkeyLearn('[YOUR_TOKEN]')
model_id = '[MODEL_ID]'
tag_id = [TAG_ID]
response = ml.classifiers.tags.edit(model_id, tag_id, 'Edited tag name')
print(response.body)
require 'monkeylearn'

Monkeylearn.configure do |c|
  c.token = '[YOUR_TOKEN]'
end

model_id = '[MODEL_ID]'
tag_id = [TAG_ID]
response = Monkeylearn.classifiers.tags.edit(model_id, tag_id, name:'Edited tag name')
puts response.body
<?php
require 'autoload.php';

$ml = new MonkeyLearn\Client('[YOUR_TOKEN]');
$model_id = '[MODEL_ID]';
$tag_id = [TAG_ID];
$new_name = 'Edited tag name';
$new_parent_id = [OTHER_TAG_ID];
$res = $ml->classifiers->categories->edit($model_id, $tag_id, $new_name, $new_parent_id);
var_dump($res->result);
?>
var MonkeyLearn = require('monkeylearn');

var ml = new MonkeyLearn('[YOUR_TOKEN]');
var model_id = '[MODEL_ID]';
var tag_id = [TAG_ID];
var new_name = 'Edited tag name';
var new_parent_id = [OTHER_TAG_ID];
var p = ml.classifiers.categories.edit(model_id, tag_id, new_name, new_parent_id);
p.then(function (res) {
    console.log(res.result);
});
import com.monkeylearn.MonkeyLearn;
import com.monkeylearn.MonkeyLearnResponse;
import com.monkeylearn.MonkeyLearnException;

public class App {
    public static void main( String[] args ) throws MonkeyLearnException {
        MonkeyLearn ml = new MonkeyLearn("[YOUR_TOKEN]");
        String modelId = "[MODEL_ID]";
        int tagId = [TAG_ID];
        String newName = "Edited tag name";
        int newParentId = [OTHER_TAG_ID];
        MonkeyLearnResponse res = ml.classifiers.categories.edit(modelId, tagId, newName, newParentId);
        System.out.println( res.jsonResult );
    }
}

Response example

{
    "id": 9312,
    "name": "Edited tag name",
    "classifier_id": "cl_kVgQtHnW",
    "stats": null
}

Request parameters

Accepts parameters in the request body as a JSON with the following attributes:

Parameter Description
namestring The new name of the tag.
parent_idinteger
Deprecated
The ID of the new parent tag. Only valid for v2 models.

Response

The response contains details about the tag that has been edited.

Delete Tag

https://api.monkeylearn.com/v3/classifiers/[MODEL_ID]/tags/[TAG_ID]/

Deletes a tag from a classifier. This action cannot be undone.

Request example

curl -X "DELETE" \
--data '{"move_data_to": [OTHER_TAG_ID]}'  \
-H "Authorization:Token [YOUR_TOKEN]" \
-H "Content-Type: application/json" \
-i \
"https://api.monkeylearn.com/v3/classifiers/[MODEL_ID]/tags/[TAG_ID]/"
from monkeylearn import MonkeyLearn

ml = MonkeyLearn('[YOUR_TOKEN]')
model_id = '[MODEL_ID]'
tag_id = [TAG_ID]
response = ml.classifiers.tags.delete(model_id, tag_id)
print(response.body)
require 'monkeylearn'

Monkeylearn.configure do |c|
  c.token = '[YOUR_TOKEN]'
end

model_id = '[MODEL_ID]'
tag_id = [TAG_ID]
response = Monkeylearn.classifiers.tags.delete(model_id, tag_id)
puts response.body
<?php
require 'autoload.php';

$ml = new MonkeyLearn\Client('[YOUR_TOKEN]');
$model_id = '[MODEL_ID]';
$tag_id = [TAG_ID];
$res = $ml->classifiers->categories->delete($model_id, $tag_id);
var_dump($res->result);
?>
var MonkeyLearn = require('monkeylearn');

var ml = new MonkeyLearn('[YOUR_TOKEN]');
var model_id = '[MODEL_ID]';
var tag_id = [TAG_ID];
var p = ml.classifiers.categories.delete(model_id, tag_id);
p.then(function (res) {
    console.log(res.result);
});
import com.monkeylearn.MonkeyLearn;
import com.monkeylearn.MonkeyLearnResponse;
import com.monkeylearn.MonkeyLearnException;

public class App {
    public static void main( String[] args ) throws MonkeyLearnException {
        MonkeyLearn ml = new MonkeyLearn("[YOUR_TOKEN]");
        String modelId = "[MODEL_ID]";
        int tagId = [TAG_ID];
        MonkeyLearnResponse res = ml.classifiers.categories.delete(modelId, tagId);
        System.out.println( res.jsonResult );
    }
}

Request parameters

Accepts parameters in the request body as a JSON with the following attributes:

Parameter Description
move_data_tointeger The ID of the tag data will be moved to before deleting the tag. If this parameter is omitted, the data will be irrevocably deleted.

Response

Returns an empty response body

Upload data

https://api.monkeylearn.com/v3/classifiers/[MODEL_ID]/data/

Uploads data to a classifier. This endpoint can be used to upload new data to a classifier, to update the tags of texts that have already been uploaded, or both.

Request example

curl --data '{"data": [{"text": "first text", "tags": [9541, "Misc"], "marks": ["any_mark", "other_mark"]}, {"text": "second text", "tags": [9541, 8968]}]}' \
-H "Authorization:Token [YOUR_TOKEN]" \
-H "Content-Type: application/json" \
-i \
"https://api.monkeylearn.com/v3/classifiers/[MODEL_ID]/data/"
from monkeylearn import MonkeyLearn

ml = MonkeyLearn('[YOUR_TOKEN]')
model_id = '[MODEL_ID]'
tag_id_1 = [TAG_ID]
tag_id_2 = [OTHER_TAG_ID]
tag_name = '[TAG_NAME]'
data = [
    {'text': 'first text', 'tags': [tag_id_1, tag_name], 'marks': ['any_mark', 'other_mark']},
    {'text': 'second text', 'tags': [tag_id_1, tag_id_2]}
]
response = ml.classifiers.upload_data(model_id, data)
print(response.body)
require 'monkeylearn'

Monkeylearn.configure do |c|
  c.token = '[YOUR_TOKEN]'
end

model_id = '[MODEL_ID]'
tag_id_1 = [TAG_ID]
tag_id_2 = [OTHER_TAG_ID]
tag_name = '[TAG_NAME]'
data = [
    {text: "first text", tags: [tag_id_1, tag_name], marks: ['any_mark', 'other_mark']},
    {text: "second text", tags: [tag_id_1, tag_id_2]}
]
response = Monkeylearn.classifiers.upload_data(model_id, data)
puts response.body
<?php
require 'autoload.php';

$ml = new MonkeyLearn\Client('[YOUR_TOKEN]');
$model_id = '[MODEL_ID]';
$tag_id_1 = [TAG_ID];
$data = array(
    array('first text', $tag_id_1),
    array('second text', '/A/B'),
);
$res = $ml->classifiers->upload_samples($model_id, $data);
var_dump($res->result);
?>
var MonkeyLearn = require('monkeylearn');

var ml = new MonkeyLearn('[YOUR_TOKEN]');
var model_id = '[MODEL_ID]';
var tag_id_1 = [TAG_ID];
var data = [
    ['first text', tag_id_1],
    ['second text', '/A/B']
];
var p = ml.classifiers.uploadSamples(model_id, data);
p.then(function (res) {
    console.log(res.result);
});
import com.monkeylearn.MonkeyLearn;
import com.monkeylearn.MonkeyLearnResponse;
import com.monkeylearn.MonkeyLearnException;
import com.monkeylearn.Tuple;

import java.util.ArrayList;

public class App {
    public static void main( String[] args ) throws MonkeyLearnException {
        MonkeyLearn ml = new MonkeyLearn("[YOUR_TOKEN]");
        String modelId = "[MODEL_ID]";
        ArrayList data = new ArrayList();
        int tag_id_1 = [TAG_ID];

        data.add(new Tuple<String, Integer>("first text", tag_id_1));
        data.add(new Tuple<String, String>("second text", "/A/B"));
        MonkeyLearnResponse res = ml.classifiers.uploadSamples(modelId, data);
        System.out.println( res.jsonResult );
    }
}

Response example

{
    "updated_count": 0,
    "created_count": 2,
    "duplicated_count": 0
}

Request parameters

Accepts parameters in the request body as a JSON with the following attributes:

Parameter Description
dataarray [object]
Required
A list of data objects.

A data object has the following attributes:

Attribute Default Description
textstring
Required
The text to create (in case it’s new) or to update (in case it already exists in the model).
tagsarray [integer or string] [] A list of tags that can be refered to by their numeric ID or their name. The text will be tagged with each tag in the list when created (in case it doesn’t already exist on the model). Otherwise, its tags will be updated to the new ones. New tags will be created if they don’t already exist.
marksarray [string] [] A list of marks that will be associated with the text. New marks will be created if they don’t already exist.

Response

Returns an object with the following attributes:

Attribute Description
updated_countinteger Count of texts that already existed in the model for which their tags were updated.
created_countinteger Count of new texts created in the model.
duplicated_countinteger Count of discarded texts because they were duplicated in the request data.

Extractor API

Extract

https://api.monkeylearn.com/v3/extractors/[MODEL_ID]/extract/

Extracts information from texts with a given extractor.

Request example

curl \
--data '{"data": ["first text", {"text": "the meeting is at 10 AM", "external_id": "ANY_ID"}, ""]}' \
-H "Authorization: Token [YOUR_TOKEN]" \
-H "Content-Type: application/json" \
-i \
"https://api.monkeylearn.com/v3/extractors/[MODEL_ID]/extract/"
from monkeylearn import MonkeyLearn

ml = MonkeyLearn('[YOUR_TOKEN]')
model_id = '[MODEL_ID]'
data = ['first text', {'text': 'the meeting is at 10 AM', 'external_id': 'ANY_ID'}, '']
response = ml.extractors.extract(model_id, data=data)
print(response.body)
require 'monkeylearn'

Monkeylearn.configure do |c|
  c.token = '[YOUR_TOKEN]'
end

data = ['First text', {text: 'the meeting is at 10 AM', external_id: 'ANY_ID'}, '']
model_id = '[MODEL_ID]'
response = Monkeylearn.extractors.extract(model_id, data)
puts response.body
<?php
require 'autoload.php';

$ml = new MonkeyLearn\Client('[YOUR_TOKEN]');
$data = ["first text", "the meeting is at 10 AM"];
$model_id = '[MODEL_ID]';
$res = $ml->extractors->extract($model_id, $data);
var_dump($res->result);
?>
var MonkeyLearn = require('monkeylearn');

var ml = new MonkeyLearn('[YOUR_TOKEN]');
var model_id = '[MODEL_ID]';
var data = ["first text", "the meeting is at 10 AM"];
var p = ml.extractors.extract(model_id, data);
p.then(function (res) {
    console.log(res.result);
});
import com.monkeylearn.MonkeyLearn;
import com.monkeylearn.MonkeyLearnResponse;
import com.monkeylearn.MonkeyLearnException;

public class App {
    public static void main( String[] args ) throws MonkeyLearnException {
        MonkeyLearn ml = new MonkeyLearn("[YOUR_TOKEN]");
        String modelId = "[MODEL_ID]";
        String[] textList = {"first text", "the meeting is at 10 AM"};
        MonkeyLearnResponse res = ml.extractors.extract(modelId, textList);
        System.out.println( res.arrayResult );
    }
}

Response example

[
    {
        "text": "first text",
        "external_id": null,
        "error": false,
        "extractions": []
    }, {
        "text": "the meeting is at 10 AM",
        "external_id": "ANY_ID",
        "error": false,
        "extractions": [{
            "extracted_text": "10 AM",
            "tag_name": "TIME",
            "parsed_value": "10:00:00",
            "offset_span": [18, 22]
        }]
    }, {
        "text": "",
        "external_id": null,
        "error": true,
        "error_detail": "Invalid text, empty strings are not allowed",
        "extractions": null
    }
]

Request parameters

Accepts parameters in the request body as a JSON with the following attributes:

Attribute Default Description
dataArray [string or object]
REQUIRED
A list of up to 500 data elements to extract from. Each element must be either a string with the text or a data object .
production_modelboolean false Indicates if the extractions are performed by the production model. Only use this parameter on custom models. Note that you first need to deploy your model to production either from the UI model settings.

A data object has the following attributes:

Attribute Default Description
textstring
REQUIRED
The text to extract. It cannot be an empty string.
external_idstring null An ID for the text that will be included in the response of its corresponding classification.

Response

The response body of this endpoint is a list where each item is the extraction result object for its positional corresponding text. Each of these objects has the following attributes:

Attribute Description
textstring The original text from the request.
external_idinteger The value given in the request as the external_id for this text. If not given, the value is null.
errorboolean Indicates if the extraction was performed (true) or an error was detected (false).
error_detailstring Detail about the cause of the error. Only present if an error occurred.
extractionsArray [object] A list of result tag objects that represent the extracted tags.

The result tag object has the following attributes:

Attribute Description
tag_namestring The name of the tag.
extracted_textinteger The substring of the text where the tag was found.
offset_spanarray [integer] The [start, end] indexes of the text that indicate where the extracted_text was extracted from.
parsed_valuestring or integer or float A processed or normalized value for this extraction. A human who reads extracted_text should be able to obtain parsed_value. If this key is not present, then extractions will be present.
extractionsarray [object] A list of result tag objects that represent the sub-extractions of this tag. If not present, parsed_value will be present. In some cases, both parsed_value and extractions will be present.

Extractor detail

https://api.monkeylearn.com/v3/extractors/[MODEL_ID]/

Returns information about an extractor.

Request example

curl -H "Authorization:Token [YOUR_TOKEN]" \
-H "Content-Type: application/json" \
-i \
"https://api.monkeylearn.com/v3/extractors/[MODEL_ID]/"
from monkeylearn import MonkeyLearn

ml = MonkeyLearn('[YOUR_TOKEN]')
model_id = '[MODEL_ID]'
response = ml.extractors.detail(model_id)
print(response.body)
require 'monkeylearn'

Monkeylearn.configure do |c|
  c.token = '[YOUR_TOKEN]'
end

model_id = '[MODEL_ID]'
response = Monkeylearn.extractors.detail(model_id)
puts response.body

// This endpoint is not supported in the PHP SDK yet. Coming soon!
// This endpoint is not supported in the Javascript SDK yet. Coming soon!
// This endpoint is not supported in the Java SDK yet. Coming soon!

Response example

{
    "id": "ex_AjZtnq7Y",
    "name": "Example Extractor",
    "description": "This text should describe what the extractor is about",
    "is_public": true,
    "model_version": "v3.0",
    "created": "2018-01-21T12:21:11+00:00",
    "industries": [
      "business_intelligence",
      "customer_support",
      "social_media"
    ],
    "priority": 0,
    "last_trained": "2018-04-23T18:26:49.221156+00:00",
    "last_deployed": "2018-05-15T22:26:49.3453455+00:00",
    "model": {
        "tags": [
            {
                "tag_name": "DATE",
                "parsed_value": true,
                "tags": null
            }
        ]
    },
    "production_model": {...}
}

Response

The response body of this endpoint is an object with the following attributes:

Attribute Description
idstring The ID of the model. It always starts with ex_.
namestring The name of the model.
descriptionstring The description of the model.
is_publicboolean Indicates whether the model is public or not. Added in v3.1.
model_versionstring The version of the model. The version of all new models is v3.0.
createdstring The date and time when this model was created, in ISO format. If the model has never been trained, the returned value will be null. Added in v3.2.
industriesArray [string] The list of industries where this module is suggested to be used. Read-only field, valid for public models. Added in v3.2.
priorityinteger Ordering criteria priority. The higher the value the higher the priority. Read-only field, valid for public models. The Added in v3.2.
last_trainedstring The date and time when this model was last trained, in ISO format. If the model has never been trained, the returned value will be null.
last_deployedstring The date and time when this model was last deployed, in ISO format. If the model has never been deployed, the returned value will be null. Only valid for custom models.
modelobject Information about the machine learning model of the extractor.
tagsarray [object] A list of tag objects that represents the tags this extractor can return in an extraction.
production_modelobject Information about the production model of the extractor. The keys are the same as the ones in model. If there is no production model deployed, the returned value is null. Only valid for custom models.

The tag object has the following attributes:

Attribute Description
tag_namestring The name of the tag.
parsed_valueboolean Indicates whether or not this tag will have a parsed_value.
tagsarray A list of tag objects that represents the tags that can be children of this tag. If this tag cannot have children, the value will be null.

List Extractors

https://api.monkeylearn.com/v3/extractors/

Returns all the available extractors for the user. This includes their custom models, public models, and models shared in the teams the user belongs to. This endpoint supports pagination.

Request example

curl -H "Authorization:Token [YOUR_TOKEN]" \
-H "Content-Type: application/json" \
-i \
"https://api.monkeylearn.com/v3/extractors/"
from monkeylearn import MonkeyLearn

ml = MonkeyLearn('[YOUR_TOKEN]')
response = ml.extractors.list()
print(response.body)
require 'monkeylearn'

Monkeylearn.configure do |c|
  c.token = '[YOUR_TOKEN]'
end

response = Monkeylearn.extractors.list()
puts response.body

// This endpoint is not supported in the PHP SDK yet. Coming soon!
// This endpoint is not supported in the Javascript SDK yet. Coming soon!
// This endpoint is not supported in the Java SDK yet. Coming soon!

Response example

[
    {
        "id": "ex_sk5zky4q",
        "name": "Laptop Model Extractor",
        "description": "Extract laptop models!",
        "is_public": false,
        "model_version": "v3.0",
        "created": "2018-01-21T12:21:11+00:00",
        "industries": [],
        "priority": 0,
        "last_trained": "2018-04-23T18:26:49.221156+00:00",
        "last_deployed": "2018-05-15T22:26:49.3453455+00:00"
    },
    {
        "id": "ex_nGAmTLFv",
        "name": "Date and Time Extractor",
        "description": "",
        "is_public": true,
        "model_version": "v3.0",
        "created": "2018-01-21T12:21:11+00:00",
        "industries": [
            "business_intelligence",
            "customer_support",
            "marketing",
            "social_media"
        ],
        "priority": 7,
        "last_trained": "2018-04-20T20:05:14.681116+00:00"
    },
    // ...
]

Request parameters

Accepts the following parameters as query string parameters:

Parameter Default Description
pageinteger 1 The page number you want to retrieve
per_pageinteger 20 The maximum number of items the page should have. The maximum allowed value is 50.
order_bystring -created Specifies the order of the list. You can order using any of the field names, either in ascending or desceding order (adding ‘-’ before the name). Also, you can order by more than one criteria, separating them with commas. Added in v3.2.

Response

An array of objects. Each object represents an extractor and has the following attributes:

Attribute Description
idstring The ID of the model. It always starts with ex_.
namestring The name of the model.
descriptionstring The description of the model.
is_publicboolean Indicates whether the model is public or not. Added in v3.1.
model_versionstring The version of the model. The version of all new models is v3.0.
createdstring The date and time when this model was created, in ISO format. If the model has never been trained, the returned value will be null. Added in v3.2.
industriesArray [string] The list of industries where this module is suggested to be used. Read-only field, valid for public models. Added in v3.2.
priorityinteger Ordering criteria priority. The higher the value the higher the priority. Read-only field, valid for public models. The Added in v3.2.
last_trainedstring The date and time when this model was last trained, in ISO format. If the model has never been trained, the returned value will be null.
last_deployedstring The date and time when this model was last deployed, in ISO format. If the model has never been deployed, the returned value will be null. Only valid for custom models.

Changelog

v3.0

Release date: 2018-06-01

v3.1

Release date: 2018-06-16

v3.2

Release date: 2018-07-16