MonkeyLearn Api Documentation
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
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.6.
MonkeyLearn uses a MAJOR.MINOR versioning schema:
- The MAJOR number of the version (3) is part of every endpoint URL. A new MAJOR version increment would mean a huge redesgin of the API for which backwards-incompatible changes have occured. These changes are very rare. API v3 is here to stay.
- The MINOR number is incremented when new backwards-compatible changes are introduced. New endpoints or new attributes in the output are among the most common reasons for MINOR version releases. Note that since changes are backwards-compatible and the minor version is not part of the URL, if you have some working code for v3.2, when v3.3 is released, you won’t need to change anything in your code. Nonetheless, you’ll know new functionality is available if you want to support it in the future.
The current version is added as a header in every API response:
X-Api-Version: v3.6
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
const MonkeyLearn = require('monkeylearn')
const 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 team 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. |
FEATURE_TEMPORARILY_DISABLED |
The endpoint is temporarily disabled. Usually the reponse detail specifies when it will be available again. |
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
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)
});
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
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)
})
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 (false ) or an error was detected (true ). |
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
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)
})
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,
"classifier_type": "custom",
"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. |
classifier_typestring | Indicates the configured classifier type. Here’s the list of supported types. |
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. |
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 |
The supported classifier types are:
Parameter | Type |
---|---|
"custom" |
Custom type |
"topic" |
Topic classifier |
"sentiment" |
Sentiment classifier |
"intent" |
Intent classifier |
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
const MonkeyLearn = require('monkeylearn')
const ml = new MonkeyLearn('[YOUR_API_KEY]')
ml.classifiers.create({
name: 'New Classifier'
}).then(res => {
console.log(res.body)
})
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,
"classifier_type": "custom",
"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. |
classifier_typestring | custom |
Indicates the desired classifier type. It must be one of the supported classifier types. |
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
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)
})
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
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)
})
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
const MonkeyLearn = require('monkeylearn')
const ml = new MonkeyLearn('[YOUR_API_KEY]')
ml.classifiers.list().then(res => {
console.log(res.body)
})
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
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)
})
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
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)
})
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. |
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
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)
})
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. |
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
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)
})
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. |
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
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)
})
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
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)
})
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. |
"merge" |
When a text is uploaded and it is identical to another one already present in the model, new tags and markers will be merged with the exising ones. |
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
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)
})
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 (false ) or an error was detected (true ). |
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
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)
})
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
const MonkeyLearn = require('monkeylearn')
const ml = new MonkeyLearn('[YOUR_API_KEY]')
ml.classifiers.list().then(res => {
console.log(res.body)
})
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 JavaScript SDK.
Request parameters
This endpoint does not take any parameters
Response
This endpoint returns an empty response body
Workflow API
The Workflow API is in beta. Please let us know if you notice any errors.
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
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)
})
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": "wf_vbx2yuuq",
"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 or null to reference input_data . |
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","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'
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, None, steps)
print(response.body)
require 'monkeylearn'
Monkeylearn.configure do |c|
c.token = '[YOUR_API_KEY]'
end
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, :steps => steps)
puts response.body
const MonkeyLearn = require('monkeylearn')
const ml = new MonkeyLearn('[YOUR_API_KEY]')
ml.workflows.create({
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)
})
Response example
"id": "wf_vbx2Yuuq",
"name": "New Workflow",
"created": "2019-01-25T20:05:46.909639+00:00",
"db_name": "wf_vbx2yuuq",
"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. |
webhook_urlstring | "" |
An URL that will be called by MonkeyLearn after new a batch has been processed. The body will include the first page of the processed data in the same format as the List Workflow Data endpoint. |
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. |
actionsarray [object] | [] |
A list of action objects that represent an action that the workflow will execute after processing data. For the moment, the only possible actions are tag actions, where the results are tagged in an external platform, usually the same as the source of the data. Added in v3.6. |
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 must be one of tag_name , parsed_value . |
operatorstring Required |
The operation that will be performed to evaluate the condition. It 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. The following words are reserved and cannot be used as a name: id , batch_id , text , global_id , wf_sample_state , cleaned_text , filter , lang , any PostgreSQL reserved work. |
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. |
An action object has the following attributes:
Attribute | Default | Description |
---|---|---|
typestring Required |
The type of action that will be executed. For the moment, tag is the only valid type. |
|
targetstring Required |
The platform where the workflow will execute the action. The possible values are zendesk , front , promoter , and freshdesk . |
|
output_typestring Required |
Where the data that will be tagged is going to come from. The possible values are step , for the workflow to tag the result of a specific step; or string for it to tag a fixed string. |
|
output_valuestring Required |
The value of the data that will be tagged. If the output_type is step , valid values are tag_name and also parsed_value in case the step is an extractor one. If the output_type is string then this is the string that is going to be used. |
|
step_namestring | The name of the step from which the data that will be tagged is going to come from if output_type is step . In that case, this parameter is required. |
|
field_idinteger | The id of field where the data is going to be tagged. Only valid and required if the target is zendesk . |
|
conditionsarray [object] | [] |
A list of action condition objects that evaluate whether the action will be executed or not. All the conditions in the list must be true for it to execute. |
An action condition object has the following attributes:
Attribute | Description |
---|---|
target_step_namestring | The name of the step that this condition uses. If it’s empty and the target of the action is step , then the step_name of the action will be used by default. |
input_namestring Required |
The part of the result step that will be used in the condition. It must be one tag_name , parsed_value (only if the target_step is an extractor) or confidence (only if the target_step is a classifier). |
operatorstring Required |
The operation that will be performed to evaluate the condition. In the case that the input_name is tag_name or parsed_value , then it must be one of includes or not_includes . If the input_name is confidence , then it must be greater_than . |
input_valuestring Required |
The literal value against which the condition will be evaluated. If the input_name is confidence it must be a float between 0 and 1. |
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
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)
})
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 JavaScript 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
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)
})
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 must be one of tag_name , parsed_value . |
operatorstring Required |
The operation that will be performed to evaluate the condition. It 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 JavaScript 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
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)
})
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
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)
})
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]/custom-fields/"
from monkeylearn import MonkeyLearn
ml = MonkeyLearn('[YOUR_API_KEY]')
model_id = '[MODEL_ID]'
name = 'creation_date'
data_type = 'date'
response = ml.workflows.custom_fields.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.custom_fields.create(model_id, name: name, data_type: data_type)
puts response.body
const MonkeyLearn = require('monkeylearn')
const ml = new MonkeyLearn('[YOUR_API_KEY]')
model_id = '[MODEL_ID]'
name = 'creation_date'
data_type = 'date'
ml.workflows.custom_fields.create(model_id, {
name: name,
type: data_type
}).then(res => {
console.log(res.body)
})
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. The following words are reserved and cannot be used as a name: id , batch_id , text , global_id , wf_sample_state , cleaned_text , filter , lang , any PostgreSQL reserved work. |
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.6
Release date: 2019-12-03
- Added workflow actions attribute in create workflow.
v3.5
Release date: 2019-06-10
- Added input_duplicates_strategy attribute in classifiers upload data.
- Added existing_duplicates_strategy attribute in classifiers upload data.
v3.4
Release date: 2019-05-22
- Added workflows support.
- Added Train extractor endpoint
- Added preprocess_names attribute in classifiers.
- Added preprocess_emails attribute in classifiers.
- Added preprocess_urls attribute in classifiers.
- Added tagging_strategy attribute in classifiers.
- Added shortened_tags attribute in classifiers upload data response.
v3.3
Release date: 2018-09-18
- Added markers attribute in classifiers data upload request objects replacing the deprecated marks attribute. The old one is still supported for backwards compatibility.
v3.2
Release date: 2018-07-16
- Added order_by query string parameter in extractors and classifiers list responses.
- Added priotity, created and industries in extractors and classifiers.
v3.1
Release date: 2018-06-16
- Added train endpoint.
- Added is_public in extractors and classifiers responses.
- Added seconds_to_wait in plan rate limit responses.
- Bugfixes in pagination.
v3.0
Release date: 2018-06-01
- First v3 release.