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.5.

MonkeyLearn uses a MAJOR.MINOR versioning schema:

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

X-Api-Version: v3.5

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_API_KEY]" \
"[API_ENDPOINT]"
from monkeylearn import MonkeyLearn

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

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

require 'autoload.php';

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

const ml = new MonkeyLearn('[YOUR_API_KEY]')
import com.monkeylearn.MonkeyLearn;
import com.monkeylearn.MonkeyLearnException;

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

Make sure to replace [YOUR_API_KEY] with your API Key.

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

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

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

Note that teams also may have an API Key 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 Key to be included in every API request in the Authorization header with a value of “Token ” and followed by the key itself. This is what it would look like:

Authorization: Token [YOUR_API_KEY]

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 Key (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 Key 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 (API Key) 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.
STEP_NOT_FOUND The workflow step doesn’t exist or you don’t have read access to the workflow. 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 a 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.

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."
}

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 is important to define a query. A query is not a request. A request may count as none, one, or more queries. Currently, three endpoints consume queries, that is, classify extract, and upload workflow data endpoints. The number of queries will be the count of successful classifications or extractions for the texts given in the text_list parameter. For workflows, it depends on the steps; the queries consumed will be sum of all the queries consumed by all the models in the workflow.

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_API_KEY]" \
-H "Content-Type: application/json" \
-i \
"https://api.monkeylearn.com/v3/classifiers/?page=2&per_page=5&order_by=-is_public,name"
from monkeylearn import MonkeyLearn

ml = MonkeyLearn('[YOUR_API_KEY]')
response = ml.classifiers.list(page=2, per_page=5, order_by=['-is_public', 'name'])
print(response.body)
require 'monkeylearn'

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

response = Monkeylearn.classifiers.list(page: 2, per_page: 5, order_by: ['-is_public', 'name'])
puts response.body
<?php
require 'autoload.php';

$ml = new MonkeyLearn\Client('[YOUR_API_KEY]');
$res = $ml->classifiers->list();
var_dump($res->result);
?>
const MonkeyLearn = require('monkeylearn')

const ml = new MonkeyLearn('[YOUR_API_KEY]')
ml.classifiers.list({page:2, per_page:5, order_by: "-is_public,name"}).then(res => {
    console.log(res.body)
});
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_API_KEY]");
        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 endpoints 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_API_KEY]" \
-H "Content-Type: application/json" \
-i \
"https://api.monkeylearn.com/v3/classifiers/[MODEL_ID]/classify/"
from monkeylearn import MonkeyLearn

ml = MonkeyLearn('[YOUR_API_KEY]')
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_API_KEY]'
end

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

$ml = new MonkeyLearn\Client('[YOUR_API_KEY]');
$data = ['first text', array('text' => 'Second text', 'external_id' => 'ANY_ID'), ''];
$model_id = '[MODEL_ID]';
$res = $ml->classifiers->classify($model_id, $data);
var_dump($res->result);
?>
const MonkeyLearn = require('monkeylearn')

const ml = new MonkeyLearn('[YOUR_API_KEY]')
let model_id = '[MODEL_ID]'
let data = ['First text', {text: 'Second text', external_id: 'ANY_ID'}, '']
ml.classifiers.classify(model_id, data).then(res => {
    console.log(res.body)
})
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_API_KEY]");
        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_API_KEY]" \
-H "Content-Type: application/json" \
-i \
"https://api.monkeylearn.com/v3/classifiers/[MODEL_ID]/"
from monkeylearn import MonkeyLearn

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

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

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

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

const ml = new MonkeyLearn('[YOUR_API_KEY]')
let model_id = '[MODEL_ID]'
ml.classifiers.detail(model_id).then(res => {
    console.log(res.body)
})
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_API_KEY]");
        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_names": false,
            "preprocess_emails": true,
            "preprocess_urls": 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

This endpoint does not take any parameters

Response

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 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. 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. 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_namesboolean Indicates whether people names preprocessing is done when training the model. Added in v3.4.
preprocess_emailsboolean Indicates whether email addresses preprocessing is done when training the model. Added in v3.4.
preprocess_urlsboolean Indicates whether urls preprocessing is done when training the model. Added in v3.4.
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.
tagging_strategystring Indicates the tagging strategy that will be used to train the model. It can be one of “autodetect”, “single” or “multi”. Added in v3.4.
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_API_KEY]" \
-H "Content-Type: application/json" \
-i \
"https://api.monkeylearn.com/v3/classifiers/"
from monkeylearn import MonkeyLearn

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

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

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

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

const ml = new MonkeyLearn('[YOUR_API_KEY]')
ml.classifiers.create({
    name: 'New Classifier'
}).then(res => {
    console.log(res.body)
})
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_API_KEY]");
        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_names": false,
            "preprocess_emails": true,
            "preprocess_urls": 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_namesboolean false Indicates whether people names preprocessing is done when training the model. Added in v3.4.
preprocess_emailsboolean true Indicates whether email addresses preprocessing is done when training the model. Added in v3.4.
preprocess_urlsboolean true Indicates whether urls preprocessing is done when training the model. Added in v3.4.
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.
tagging_strategystring autodetect Indicates the tagging strategy that will be used to train the model. It can be one of “autodetect”, “single” or “multi”. Added in v3.4.

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_API_KEY]" \
-H "Content-Type: application/json" \
-i \
"https://api.monkeylearn.com/v3/classifiers/[MODEL_ID]/"
from monkeylearn import MonkeyLearn

ml = MonkeyLearn('[YOUR_API_KEY]')
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_API_KEY]'
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
<?php
require 'autoload.php';

$ml = new MonkeyLearn\Client('[YOUR_API_KEY]');
$model_id = '[MODEL_ID]';
$res = $ml->classifiers->edit($model_id, 'New name for classifier');
var_dump($res->result);
?>
const MonkeyLearn = require('monkeylearn')

const ml = new MonkeyLearn('[YOUR_API_KEY]')
let model_id = '[MODEL_ID]'
ml.classifiers.edit(model_id, {
    description: 'The classifier will use preprocessing for social media now',
    preprocess_social_media: true
}).then(res => {
    console.log(res.body)
})
// 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_names": false,
            "preprocess_emails": true,
            "preprocess_urls": 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]/

This endpoint deletes a classifier. This action cannot be undone.

Request example

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

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

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

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

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

const ml = new MonkeyLearn('[YOUR_API_KEY]')
let model_id = '[MODEL_ID]'
ml.classifiers.delete(model_id).then(res => {
    console.log(res)
})
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_API_KEY]");
        String modelId = "[MODEL_ID]";
        MonkeyLearnResponse res = ml.classifiers.delete(modelId);
        System.out.println( res.jsonResult );
    }
}

Request parameters

This endpoint does not take any parameters

Response

This endpoint 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_API_KEY]" \
-H "Content-Type: application/json" \
-i \
"https://api.monkeylearn.com/v3/classifiers/"
from monkeylearn import MonkeyLearn

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

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

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

$ml = new MonkeyLearn\Client('[YOUR_API_KEY]');
$res = $ml->classifiers->list();
var_dump($res->result);
?>
const MonkeyLearn = require('monkeylearn')

const ml = new MonkeyLearn('[YOUR_API_KEY]')
ml.classifiers.list().then(res => {
    console.log(res.body)
})
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_API_KEY]");
        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 to be retrieved.
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. It can be ordered using any of the field names, either in ascending or descending order (adding ‘-’ before the name). Also, more than one criteria can be specified, separated 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 Classifier

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_API_KEY]" \
-H "Content-Type: application/json" \
-i \
"https://api.monkeylearn.com/v3/classifiers/[MODEL_ID]/deploy/"
from monkeylearn import MonkeyLearn

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

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

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

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

const ml = new MonkeyLearn('[YOUR_API_KEY]')
let model_id = '[MODEL_ID]';
ml.classifiers.deploy(model_id).then(res => {
    console.log(res)
})
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_API_KEY]");
        String modelId = "[MODEL_ID]";
        MonkeyLearnResponse res = ml.classifiers.deploy(modelId);
        System.out.println( res.jsonResult );
    }
}

Request parameters

This endpoint does not take any parameters

Response

This endpoint returns an empty response body

Train Classifier

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_API_KEY]" \
-H "Content-Type: application/json" \
-i \
"https://api.monkeylearn.com/v3/classifiers/[MODEL_ID]/train/"
from monkeylearn import MonkeyLearn

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

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

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

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

const ml = new MonkeyLearn('[YOUR_API_KEY]')
let model_id = '[MODEL_ID]'
ml.classifiers.train(model_id).then(res => {
    console.log(res)
})
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_API_KEY]");
        String modelId = "[MODEL_ID]";
        MonkeyLearnResponse res = ml.classifiers.train(modelId);
        System.out.println( res.jsonResult );
    }
}

Request parameters

This endpoint does not take any parameters

Response

This endpoint returns an empty response body

Tag Detail

Request example

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

ml = MonkeyLearn('[YOUR_API_KEY]')
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_API_KEY]'
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_API_KEY]');
$model_id = '[MODEL_ID]';
$tag_id = [TAG_ID];
$res = $ml->classifiers->tags->detail($model_id, $tag_id);
var_dump($res->result);
?>
const MonkeyLearn = require('monkeylearn')

const ml = new MonkeyLearn('[YOUR_API_KEY]')
let model_id = '[MODEL_ID]'
let tag_id = [TAG_ID]
ml.classifiers.tags.detail(model_id, tag_id).then(res => {
    console.log(res.body)
})
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_API_KEY]");
        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

This endpoint does not take any parameters

Response

Attribute 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 object 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_API_KEY]" \
-H "Content-Type: application/json" \
-i \
"https://api.monkeylearn.com/v3/classifiers/[MODEL_ID]/tags/"
from monkeylearn import MonkeyLearn

ml = MonkeyLearn('[YOUR_API_KEY]')
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_API_KEY]'
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_API_KEY]');
$model_id = '[MODEL_ID]';
$res = $ml->classifiers->tags->create($model_id, 'New Tag');
var_dump($res->result);
?>
const MonkeyLearn = require('monkeylearn')

const ml = new MonkeyLearn('[YOUR_API_KEY]')
let model_id = '[MODEL_ID]'
ml.classifiers.tags.create(model_id, {
    name: 'New Tag'
}).then(res => {
    console.log(res.body)
})
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_API_KEY]");
        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_API_KEY]" \
-H "Content-Type: application/json" \
-i \
"https://api.monkeylearn.com/v3/classifiers/[MODEL_ID]/tags/[TAG_ID]/"
from monkeylearn import MonkeyLearn

ml = MonkeyLearn('[YOUR_API_KEY]')
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_API_KEY]'
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_API_KEY]');
$model_id = '[MODEL_ID]';
$tag_id = [TAG_ID];
$res = $ml->classifiers->tags->edit($model_id, $tag_id, 'Edited tag name');
var_dump($res->result);
?>
const MonkeyLearn = require('monkeylearn')

const ml = new MonkeyLearn('[YOUR_API_KEY]')
let model_id = '[MODEL_ID]'
let tag_id = [TAG_ID]
ml.classifiers.tags.edit(model_id, tag_id, {
    name: 'Edited tag name'
}).then(res => {
    console.log(res.body)
})
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_API_KEY]");
        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]/

This endpoint 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_API_KEY]" \
-H "Content-Type: application/json" \
-i \
"https://api.monkeylearn.com/v3/classifiers/[MODEL_ID]/tags/[TAG_ID]/"
from monkeylearn import MonkeyLearn

ml = MonkeyLearn('[YOUR_API_KEY]')
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_API_KEY]'
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_API_KEY]');
$model_id = '[MODEL_ID]';
$tag_id = [TAG_ID];
$res = $ml->classifiers->tags->delete($model_id, $tag_id);
var_dump($res->result);
?>
const MonkeyLearn = require('monkeylearn')

const ml = new MonkeyLearn('[YOUR_API_KEY]')
let model_id = '[MODEL_ID]'
let tag_id = [TAG_ID]
ml.classifiers.tags.delete(model_id, tag_id).then(res => {
    console.log(res)
})
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_API_KEY]");
        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 It’s a tag ID. The data that was tagged with the deleted tag will be tagged with this new tag. This parameter is optional.

Response

This endpoint returns an empty response body

Upload Classifier 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"], "markers": ["any_marker", "other_marker"]}, {"text": "second text", "tags": [9541, 8968]}]}' \
-H "Authorization:Token [YOUR_API_KEY]" \
-H "Content-Type: application/json" \
-i \
"https://api.monkeylearn.com/v3/classifiers/[MODEL_ID]/data/"
from monkeylearn import MonkeyLearn

ml = MonkeyLearn('[YOUR_API_KEY]')
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],
    'markers': ['any_marker', 'other_marker']
}, {
    '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_API_KEY]'
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],
    markers: ['any_marker', 'other_marker']
}, {
    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_API_KEY]');
$model_id = '[MODEL_ID]';
$tag_id_1 = [TAG_ID];
$tag_id_2 = [OTHER_TAG_ID];
$tag_name = '[TAG_NAME]';
$data = array(
    array('text' => 'first text', 'tags' => [$tag_id_1, $tag_name]),
    array('text' => 'second text', 'tags' => [$tag_id_1, $tag_id_2])
);
$res = $ml->classifiers->upload_data($model_id, $data);
var_dump($res->result);
?>
const MonkeyLearn = require('monkeylearn')

const ml = new MonkeyLearn('[YOUR_API_KEY]')
let model_id = '[MODEL_ID]'
let tag_id_1 = [TAG_ID]
let tag_id_2 = [OTHER_TAG_ID]
let tag_name = '[TAG_NAME]'
let data = [{
    text: 'first text',
    tags: [tag_id_1, tag_name],
    markers: ['any_marker', 'other_marker']
},{
    text: 'second text',
    tags: [tag_id_1, tag_id_2]
}]
ml.classifiers.upload_data(model_id, data).then(res => {
    console.log(res.body)
})
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_API_KEY]");
        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,
    "shortened_tags": []
}

Request parameters

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

Parameter Default Description
dataarray [object]
Required
A list of data objects.
input_duplicates_strategystring "merge" Indicates what to do with duplicate texts in this request. Must be one of “merge”, “keep_first” or “keep_last”. The exact workings are explained below. Added in v3.5.
existing_duplicates_strategystring "overwrite" Indicates what to do with texts of this request that already exist in the model. Must be one of “overwrite” or “ignore”. The exact workings are explained below. Added in v3.5.

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 referred 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.
markersarray [string] [] A list of markers that will be associated with the text. New markers will be created if they don’t already exist. Added in v3.3.

The possible values of input_duplicates_strategy are:

Value Description
"merge" For a collection of several duplicate texts, a single text is uploaded to the model. It contains all the tags and markers of all the tagged texts of the input dataset. If some of the duplicate texts have tags and some don’t, the markers of the ones that don’t have tags are ignored.
"keep_first" For a collection of several duplicate texts, a single text is uploaded to the model. It contains all the tags and markers of the first tagged text of the input dataset. Duplicate untagged texts that appear before this text are ignored.
"keep_last" For a collection of several duplicate texts, a single text is uploaded to the model. It contains all the tags and markers of the last tagged text of the input dataset. Duplicate untagged texts that appear after this text are ignored.

In all cases, if a collection of duplicate texts doesn’t include a single text with tags, a single text is uploaded to the model, and it will only have the markers of the text that came first. The rest of the duplicates are ignored.

The possible values of existing_duplicates_strategy are:

Value Description
"overwrite" When a text is uploaded and it is identical to another one already present in the model, the one present in the model will be deleted and the new one will take its place. The old tags and markers will be deleted, and the ones of the new text will take their place.
"ignore" When a text is uploaded and it is identical to another one already present in the model, the new one will be ignored. No changes will be made to the existing text, its tags, or its markers.

Response

Returns an object with the following attributes:

Attribute Description
updated_countinteger Count of texts that already existed in the model.
created_countinteger Count of new texts created in the model.
duplicated_countinteger Count of texts that were duplicated in the request data.
shortened_tagsarray [string] A list of the tags that were longer than the 100 character limit and were therefore trimmed. Added in v3.4.

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_API_KEY]" \
-H "Content-Type: application/json" \
-i \
"https://api.monkeylearn.com/v3/extractors/[MODEL_ID]/extract/"
from monkeylearn import MonkeyLearn

ml = MonkeyLearn('[YOUR_API_KEY]')
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_API_KEY]'
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_API_KEY]');
$data = ['first text', array('text' => 'the meeting is at 10 AM', 'external_id' => 'ANY_ID'), ''];
$model_id = '[MODEL_ID]';
$res = $ml->extractors->extract($model_id, $data);
var_dump($res->result);
?>
const MonkeyLearn = require('monkeylearn')

const ml = new MonkeyLearn('[YOUR_API_KEY]')
let model_id = '[MODEL_ID]'
let data = ['First text', {text: 'the meeting is at 10 AM', external_id: 'ANY_ID'}, '']
ml.extractors.extract(model_id, data).then(res => {
    console.log(res.body)
})
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_API_KEY]");
        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_API_KEY]" \
-H "Content-Type: application/json" \
-i \
"https://api.monkeylearn.com/v3/extractors/[MODEL_ID]/"
from monkeylearn import MonkeyLearn

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

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

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

<?php
require 'autoload.php';

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

const ml = new MonkeyLearn('[YOUR_API_KEY]')
let model_id = '[MODEL_ID]'
ml.extractors.detail(model_id).then(res => {
    console.log(res.body)
})
// This endpoint is not supported by 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_API_KEY]" \
-H "Content-Type: application/json" \
-i \
"https://api.monkeylearn.com/v3/extractors/"
from monkeylearn import MonkeyLearn

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

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

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

<?php
require 'autoload.php';

$ml = new MonkeyLearn\Client('[YOUR_API_KEY]');
$model_id = '[MODEL_ID]';
$res = $ml->extractors->list();
var_dump($res->result);
?>
const MonkeyLearn = require('monkeylearn')

const ml = new MonkeyLearn('[YOUR_API_KEY]')
ml.classifiers.list().then(res => {
    console.log(res.body)
})
// 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.

Train Extractor

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

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

Request example

curl -X POST \
-H "Authorization:Token [YOUR_API_KEY]" \
-H "Content-Type: application/json" \
-i \
"https://api.monkeylearn.com/v3/extractors/[MODEL_ID]/train/"
# This endpoint is not yet supported by the Python SDK.
# This endpoint is not yet supported by the Ruby SDK.
// This endpoint is not yet supported by the PHP SDK.
// This endpoint is not yet supported by the JavaScript SDK.
// This endpoint is not yet supported by the Java SDK.

Request parameters

This endpoint does not take any parameters

Response

This endpoint returns an empty response body

Workflow API

Workflow detail

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

Returns information about a workflow including its steps and custom fields.

Request example

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

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

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

response = Monkeylearn.workflows.detail('[MODEL_ID]')
puts response.body
// This endpoint is not yet supported by the PHP SDK.
const MonkeyLearn = require('monkeylearn')

const ml = new MonkeyLearn('[YOUR_API_KEY]')
let model_id = '[MODEL_ID]'
ml.workflows.detail(model_id).then(res => {
    console.log(res.body)
})
// This endpoint is not yet supported by the Java SDK.

Response example

{
    "id": "wf_vbx2Yuuq",
    "name": "Example Workflow",
    "description": "This text should describe what the workflow is about",
    "is_public": false,
    "model_version": "v3.0",
    "created": "2019-01-25T20:05:46.909639+00:00",
    "db_name": "example_db_workflow",
    "steps": [{
        "name": "keywords",
        "input": "input_data",
        "model_id": "ex_YCya9nrn",
        "conditions": []
    }, {
        "name": "language",
        "input": "input_data",
        "model_id": "cl_Vay9jh28",
        "conditions": []
    }, {
        "name": "sentiment",
        "model_id": "cl_mhtFGCr4",
        "conditions": [{
            "target_step_name": "language",
            "input_name": "tag_name",
            "operator": "includes",
            "input_value": "English-en"
        }]
    }],
    "custom_fields": [{
            "name": "ticket_id",
            "type": "integer"
        }, {
            "name": "title",
            "type": "text"
    }],
    "sources": {
        "zendesk": [{
            "data_destination": "text",
            "data_origin": "ticker.subject"
        },{
            "data_destination": "ticket_id",
            "data_origin": "ticket.id"
        },{
            "data_destination": "title",
            "data_origin": "ticket.title"
        }
    ]}
}

Request parameters

This endpoint does not take any parameters

Response

Attribute Description
idstring The ID of the model. It always starts with wf_.
namestring The name of the model.
descriptionstring The description of the model.
is_publicboolean Indicates whether the model is public or custom.
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.
db_namestring The name of the database that this workflow uses.
stepsArray [object] A list of step objects that represent the steps of the workflow.
custom_fieldsArray [object] A list of custom field objects that represent user defined fields that come with the input data and that will be saved. It does not include the mandatory text field.
sourcesArray [object] A list of source objects that represent the data sources of the workflow.

The step object has the following attributes:

Attribute Description
idinteger The ID of the step.
namestring The name of the step.
inputstring Where the input text to use in this step comes from. It can be either the name of a step or input_data, which means that the input will be the original text.
model_idstring The ID of the model to be used in this step.
conditionsarray [object] A list of condition objects that evaluate whether this step should execute or not. All the conditions in the list must be true for the step to execute.

A condition object has the following attributes:

Attribute Description
target_step_namestring The name of the step that this condition uses.
input_namestring The name of the field of the target step that will be used in the condition.
operatorstring The operation that will be performed to evaluate the condition. Will be one of includes, not_includes.
input_valuestring The literal value against which the condition will be evaluated.

The custom field object has the following attributes:

Attribute Description
idinteger The ID of the field.
namestring The name of the field.
typestring The type of the data of the field. The possible values are string, date, text, integer, float and bool.

The source object has the following attributes:

Attribute Description
data_originstring The name of the field from where data will be gathered.
data_destinationstring The name of the field where data will be stored. It can be either text or the name of a custom field.

Create Workflow

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

Creates a new workflow.

Request example

curl --data '{"name":"New Workflow","db_name":"new_workflow","steps":[{"name":"language","model_id":"cl_Vay9jh28"},{"name":"sentiment","model_id":"cl_mhtFGCr4","conditions":[{"target_step_name":"language","input_name":"tag_name","operator":"includes","input_value":"English-en"}]}]}' \
-H "Authorization:Token [YOUR_API_KEY]" \
-H "Content-Type: application/json" \
-i \
"https://api.monkeylearn.com/v3/workflows/"
from monkeylearn import MonkeyLearn

ml = MonkeyLearn('[YOUR_API_KEY]')
name = 'New Workflow'
db_name = 'new_workflow'
steps = [{
    'name': 'language',
    'model_id': 'cl_Vay9jh28'
}, {
    'name': 'sentiment',
    'model_id': 'cl_mhtFGCr4',
    'conditions': [{
        'target_step_name': 'language',
        'input_name': 'tag_name',
        'operator': 'includes',
        'input_value': 'English-en'
    }]
}]
response = ml.workflows.create(name, db_name, steps)
print(response.body)
require 'monkeylearn'

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

name = 'New Workflow'
db_name = 'new_workflow'
steps = [{
    'name': 'language',
    'model_id': 'cl_Vay9jh28'
}, {
    'name': 'sentiment',
    'model_id': 'cl_mhtFGCr4',
    'conditions': [{
        'target_step_name': 'language',
        'input_name': 'tag_name',
        'operator': 'includes',
        'input_value': 'English-en'
    }]
}]
response = Monkeylearn.workflows.create(name, db_name, steps)
puts response.body
// This endpoint is not yet supported by the PHP SDK.
const MonkeyLearn = require('monkeylearn')

const ml = new MonkeyLearn('[YOUR_API_KEY]')
ml.workflows.create({
    name: 'New Workflow',
    db_name: 'new_workflow',
    steps = [{
        name: 'language',
        model_id: 'cl_Vay9jh28'
    }, {
        name: 'sentiment',
        model_id: 'cl_mhtFGCr4',
        conditions: [{
            target_step_name: 'language',
            input_name: 'tag_name',
            operator: 'includes',
            input_value: 'English-en'
        }]
    }]
}).then(res => {
    console.log(res.body)
})
// This endpoint is not yet supported by the Java SDK.

Response example


    "id": "wf_vbx2Yuuq",
    "name": "New Workflow",
    "created": "2019-01-25T20:05:46.909639+00:00",
    "db_name": "new_workflow",
    "steps": [{
        "name": "language",
        "input": "input_data",
        "model_id": "cl_Vay9jh28",
        "conditions": []
    }, {
        "name": "sentiment",
        "model_id": "cl_mhtFGCr4",
        "conditions": [{
            "target_step_name": "language",
            "input_name": "tag_name",
            "operator": "includes",
            "input_value": "English-en"
        }]
    }],
    "custom_fields": [],
    "sources": {}

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.
db_namestring
Required
The name of the database where the data will be stored. The name must not already be in use by another database.
webhook_urlstring "" An URL that will be called when an action is triggered.
stepsarray [object]
Required
A list of step objects.
custom_fieldsarray [object] [] A list of custom field objects that represent user defined fields that come with the input data and that will be saved. It does not include the mandatory text field.
sourcesobject {} An object that represents the data sources of the workflow.
zendeskarray [object] [] A list of source objects.
frontarray [object] [] A list of source objects.
promoterarray [object] [] A list of source objects.
freshdeskarray [object] [] A list of source objects.

A step object has the following attributes:

Attribute Default Description
namestring
Required
The name of the step. It must be unique on this workflow.
model_idstring
Required
The ID of the model that will be called.
inputstring "input_data" Where the input text to use in this step comes from. It can be either the name of a step or input_data, which means that the input will be the original text.
conditionsarray [object] [] A list of condition objects that evaluate whether this step should execute or not. All the conditions in the list must be true for the step to execute.

A condition object has the following attributes:

Attribute Description
target_step_namestring
Required
The name of the step that this condition uses.
input_namestring
Required
The name of the field of the target step that will be used in the condition. It should be one of tag_name, parsed_value.
operatorstring
Required
The operation that will be performed to evaluate the condition. Must be one of includes, not_includes.
input_valuestring
Required
The literal value against which the condition will be evaluated.

A custom field object has the following attributes:

Attribute Description
namestring
Required
The name of the field. It must be unique on this workflow.
typestring
Required
The type of the data of the field. It must be one of string, date, text, integer, float, bool.

A source object has the following attributes:

Attribute Default Description
data_originstring
Required
The name of the field from where data will be gathered.
data_destinationstring "text" The name of the field where data will be stored. It can be either text or the name of a custom field.

Response

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

Delete Workflow

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

This endpoint deletes a workflow. This action cannot be undone.

Request example

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

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

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

response = Monkeylearn.workflows.delete('[MODEL_ID]')
puts response.body
// This endpoint is not yet supported by the PHP SDK.
const MonkeyLearn = require('monkeylearn')

const ml = new MonkeyLearn('[YOUR_API_KEY]')
let model_id = '[MODEL_ID]'
ml.workflows.delete(model_id).then(res => {
    console.log(res)
})
// This endpoint is not yet supported by the Java SDK.

Request parameters

This endpoint does not take any parameters

Response

This endpoint returns an empty response body

Step Detail

https://api.monkeylearn.com/v3/workflows/[MODEL_ID]/steps/[STEP_ID]/

Returns information about a step.

Request example

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

ml = MonkeyLearn('[YOUR_API_KEY]')
model_id = '[MODEL_ID]'
step_id = [STEP_ID]
response = ml.workflows.steps.detail(model_id, step_id)
print(response.body)
# This endpoint is not yet supported by the Ruby SDK.
// This endpoint is not yet supported by the PHP SDK.
// This endpoint is not yet supported by the JavaScript SDK.
// This endpoint is not yet supported by the Java SDK.

Response example

{
    "id": 1632,
    "name": "first_step",
    "input": "input_data",
    "model_id": "ex_BvdUu2GC",
    "conditions": []
}

Request parameters

This endpoint does not take any parameters

Response

Attribute Description
idinteger The ID of the step.
namestring The name of the step.
inputstring Where the input text to use in this step comes from. It can be either the name of a step or input_data, which means that the input will be the original text.
model_idstring The ID of the model to be used in this step.

Create Step

https://api.monkeylearn.com/v3/workflows/[MODEL_ID]/steps/

Creates a new step in a workflow.

Request example

curl --data '{"name": "new_step", "model_id": "cl_yUgHXZTF"}'  \
-H "Authorization:Token [YOUR_API_KEY]" \
-H "Content-Type: application/json" \
-i \
"https://api.monkeylearn.com/v3/workflows/[MODEL_ID]/steps/"
from monkeylearn import MonkeyLearn

ml = MonkeyLearn('[YOUR_API_KEY]')
model_id = '[MODEL_ID]'
step_model_id = 'cl_yUgHXZTF'
name = 'new_step'
response = ml.workflows.steps.create(model_id, name, step_model_id)
print(response.body)
require 'monkeylearn'

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

model_id = '[MODEL_ID]'
step_model_id = 'cl_yUgHXZTF'
name = 'new_step'
response = Monkeylearn.workflows.steps.create(model_id, step_model_id: step_model_id, name: name)
puts response.body
// This endpoint is not yet supported by the PHP SDK.
const MonkeyLearn = require('monkeylearn')

const ml = new MonkeyLearn('[YOUR_API_KEY]')
let model_id = '[MODEL_ID]'
step_model_id = 'cl_yUgHXZTF'
name = 'new_step'
ml.workflows.steps.create(model_id, {
    name: name,
    model_id: step_model_id
}).then(res => {
    console.log(res.body)
})
// This endpoint is not yet supported by the Java SDK.

Response example

{
    "id": 9816,
    "name": "new_step",
    "input": null,
    "model_id": "cl_yUgHXZTF"
}

Request parameters

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

Attribute Default Description
namestring
Required
The name of the step. It must be unique on this workflow.
model_idstring
Required
The ID of the model that will be called.
inputstring "input_data" Where the input text to use in this step comes from. It can be either the name of a step or input_data, which means that the input will be the original text.
conditionsarray [object] [] A list of condition objects that indicate whether this step should execute or not. All the conditions in the list must be true for the step to execute.

A condition object has the following attributes:

Attribute Description
target_step_namestring
Required
The name of the step that this condition uses.
input_namestring
Required
The name of the field of the target step that will be used in the condition. It should be one of tag_name, parsed_value.
operatorstring
Required
The operation that will be performed to evaluate the condition. Must be one of includes, not_includes.
input_valuestring
Required
The literal value against which the condition will be evaluated.

Response

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

Delete Step

https://api.monkeylearn.com/v3/workflows/[MODEL_ID]/steps/[STEP_ID]/

This endpoint deletes a step from a workflow. This action cannot be undone.

Request example

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

ml = MonkeyLearn('[YOUR_API_KEY]')
model_id = '[MODEL_ID]'
tag_id = [STEP_ID]
response = ml.workflows.steps.delete(model_id, step_id)
print(response.body)
# This endpoint is not yet supported by the Ruby SDK.
// This endpoint is not yet supported by the PHP SDK.
// This endpoint is not yet supported by the JavaScript SDK.
// This endpoint is not yet supported by the Java SDK.

Request parameters

This endpoint does not take any parameters

Response

This endpoint returns an empty response body

Upload Workflow Data

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

Uploads data to be processed to a workflow. This will create a new batch and will return its batch_id. MonkeyLearn will then asynchronously run all the steps of the workflow and record the output. This output can be accessed using the List Data endpoint.

Request example

curl --data '{"data": [{"text": "We got clean towels"}, {"text": "I would have said it was more like a queen size.", "rating": 2}]}' \
-H "Authorization:Token [YOUR_API_KEY]" \
-H "Content-Type: application/json" \
-i \
"https://api.monkeylearn.com/v3/workflows/[MODEL_ID]/data/"
from monkeylearn import MonkeyLearn

ml = MonkeyLearn('[YOUR_API_KEY]')
model_id = '[MODEL_ID]'
data = [{
    'text': 'We got clean towels'
}, {
    'text': 'I would have said it was more like a queen size.',
    'rating': 2     # this is optional, a value for a custom field
}]
response = ml.workflows.data.create(model_id, data)
print(response.body)
require 'monkeylearn'

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

model_id = '[MODEL_ID]'
data = [{
    text: 'We got clean towels'
}, {
    text: 'I would have said it was more like a queen size.',
    rating: 2     # this is optional, a value for a custom field
}]
response = Monkeylearn.workflows.data.create(model_id, data: data)
puts response.body
// This endpoint is not yet supported by the PHP SDK.
const MonkeyLearn = require('monkeylearn')

const ml = new MonkeyLearn('[YOUR_API_KEY]')
let model_id = '[MODEL_ID]'
let data = [{
    text: 'We got clean towels'
}, {
    text: 'I would have said it was more like a queen size.',
    rating: 2     // this is optional, a value for a custom field
}]
ml.workflows.upload_data(model_id, data).then(res => {
    console.log(res.body)
})
// This endpoint is not yet supported by the Java SDK.

Response example

{
    "batch_id": 39132
}

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.
[custom field name] null The value for a custom field for this text. The type of the value must be the one specified when the field was created.

Response

Returns an object with the following attributes:

Attribute Description
batch_idinteger The ID of the batch that has been created.

List Workflow Data

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

Lists data in a workflow with its corresponding processed output.

Request example

curl -H "Authorization:Token [YOUR_API_KEY]" \
-i \
"https://api.monkeylearn.com/v3/workflows/[MODEL_ID]/data/"
from monkeylearn import MonkeyLearn

ml = MonkeyLearn('[YOUR_API_KEY]')
model_id = '[MODEL_ID]'
response = ml.workflows.data.list(model_id)
print(response.body)
require 'monkeylearn'

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

model_id = '[MODEL_ID]'
response = Monkeylearn.workflows.data.list(model_id)
puts response.body
// This endpoint is not yet supported by the PHP SDK.
const MonkeyLearn = require('monkeylearn')

const ml = new MonkeyLearn('[YOUR_API_KEY]')
let model_id = '[MODEL_ID]'
ml.workflows.list(model_id, {}).then(res => {
    console.log(res.body)
})
// This endpoint is not yet supported by the Java SDK.

Response example

[{
    "id": 400,
    "text": "really dirty, location was good",
    "batch": {
        "id": 290,
        "processed_date": "2019-03-15T21:00:20.305742",
        "sent_to_process_date": "2019-03-15T21:00:18.061743"
    },
    "custom_fields": {
        "rating": 4
    },
    "steps": [{
        "step_name": "opinion_units",
        "output": [{
            "id": 380,
            "tag_name": "OPINION_UNIT",
            "parsed_value": "really dirty",
            "steps": [{
                "step_name": "sentiment",
                "output": [{
                    "id": 1280,
                    "tag_name": "Negative",
                    "tag_id": 89734368,
                    "confidence": 0.960114278651035,
                    "steps": []
                }],
            }]
        }, {
            "id": 381,
            "tag_name": "OPINION_UNIT",
            "parsed_value": "location was good",
            "steps": [{
                "step_name": "sentiment",
                "output": [{
                    "id": 1281,
                    "tag_name": "Positive",
                    "tag_id": 89734367,
                    "confidence": 0.920114278651091,
                    "steps": []
                }],
            }]
        }]
    }]
},
//...
]

Request parameters

Accepts the following parameters as query string parameters:

Parameter Default Description
pageinteger 1 The page number to be retrieved.
per_pageinteger 20 The maximum number of items the page should have. The maximum allowed value is 50.
batch_idinteger The ID of the batch to retrieve. If unspecified, data from all batches is shown.
is_processedboolean Whether to return data that has been processed or data that has not been processed yet. If unspecified, both are shown indistinctly.
sent_to_process_date_fromstring An ISO formatted date which specifies the oldest sent_date of the data to be retrieved.
sent_to_process_date_tostring An ISO formatted date which specifies the most recent sent_date of the data to be retrieved.

Response

Returns An array of objects, each one representing one data point. Each of these have the following attributes:

Attribute Description
idinteger The ID of the data point.
textstring The text of this data point.
batchobject Information about the batch that this data point belongs to.
idinteger The ID of this batch.
sent_to_process_datestring The date and time when this batch was first sent to the workflow, in ISO format. This is, when the batch was created.
processed_datestring The date and time when this batch last finished processing, in ISO format. If this batch has not been processed yet, the returned value will be null.
custom_fieldsobject The values of this data point for the custom fields of this workflow (if any are defined).
[custom field name] The value of this data point for this custom field. Will be null if it is unassigned.
stepsarray [object] A list of step objects with information about the results of the processing of each of the steps of this workflow. This list contains on the first level the steps that draw their input from input_data. The steps that draw their input from other steps are contained recursively inside the step object of their parent.

An step object has the following attributes:

Attribute Description
step_namestring The name of this step.
outputarray [object] A list of output objects with information about the results of the processing of this step. There is one object for every tag output by the model of this step (a single model may produce zero, one, or more tags). If this step wasn’t executed (either due to a condition or due to other reasons) the value will be null.

An output object has the following attributes:

Attribute Description
idinteger The ID of this output.
tag_namearray [object] The name of the tag output by the model.
parsed_valuearray [object] The parsed value of the tag output by the model. Only present in extractors.
tag_idarray [object] The ID of the tag output by the model. Only present in classifiers
confidencearray [object] The confidence of the tag output by the model. Only present in classifiers
stepsarray [object] A list of step objects with information about the results of the processing of each of the child steps of this step.

Create Custom Field

https://api.monkeylearn.com/v3/workflows/[MODEL_ID]/custom-fields/

Creates a new custom field in a workflow.

Request example

curl --data '{"name": "creation_date", "type": "date"}'  \
-H "Authorization:Token [YOUR_API_KEY]" \
-H "Content-Type: application/json" \
-i \
"https://api.monkeylearn.com/v3/workflows/[MODEL_ID]/steps/"
from monkeylearn import MonkeyLearn

ml = MonkeyLearn('[YOUR_API_KEY]')
model_id = '[MODEL_ID]'
name = 'creation_date'
data_type = 'date'
response = ml.workflows.steps.create(model_id, name, data_type)
print(response.body)
require 'monkeylearn'

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

model_id = '[MODEL_ID]'
name = 'creation_date'
data_type = 'date'
response = Monkeylearn.workflows.steps.create(model_id, name: name, data_type: data_type)
puts response.body
// This endpoint is not yet supported by the PHP SDK.
const MonkeyLearn = require('monkeylearn')

const ml = new MonkeyLearn('[YOUR_API_KEY]')
model_id = '[MODEL_ID]'
name = 'creation_date'
data_type = 'date'
ml.workflows.tags.create(model_id, {
    name: name,
    type: data_type
}).then(res => {
    console.log(res.body)
})
// This endpoint is not yet supported by the Java SDK.

Response example

{
    "id": 69181,
    "name": "creation_date",
    "type": "date"
}

Request parameters

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

Attribute Description
namestring
Required
The name of the field. It must be unique on this workflow.
typestring
Required
The type of the data of the field. It must be one of string, date, text, integer, float, bool.

Response

The response contains details about the custom field that has been created:

Attribute Description
idinteger The ID of the field.
namestring The name of the field.
typestring The type of the data of the field. The possible values are string, date, text, integer, float and bool.

Changelog

v3.5

Release date: 2019-06-10

v3.4

Release date: 2019-05-22

v3.3

Release date: 2018-09-18

v3.2

Release date: 2018-07-16

v3.1

Release date: 2018-06-16

v3.0

Release date: 2018-06-01