NAV
ruby python shell

Introduction

Welcome to the Hybrid ML API! You can use the API to programmatically create and apply classifiers.

Example

Let’s walk through a quick example of how to build a classifier that classifies Trump vs. Hillary tweets. If you’re currently signed in, we’ve already included your own API key in this example and all the examples below, in case you’d like to run them yourself.

First, we create the classifier.

curl https://www.hybridml.com/api/classifiers \
  -u {{YOUR_API_KEY}}: \
  -d name="Trump vs. Hillary classifier" \
  -d instructions="Check if a tweet is by Donald Trump or Hillary Clinton." \
  -d categories="trump, hillary" \
  -d accuracy=0.99
require 'httparty'

HTTParty.post("https://www.hybridml.com/api/classifiers",
  basic_auth: { username: "{{YOUR_API_KEY}}" },
  body: {
    name: "Trump vs. Hillary classifier",
    instructions: "Check if a tweet is by Donald Trump or Hillary Clinton.",
    categories: ["trump", "hillary"],
    accuracy: 0.99
  }
)
import requests

requests.post("https://www.hybridml.com/api/classifiers", 
  auth = ("{{YOUR_API_KEY}}", ""),
  json = {
    "name": "Trump vs. Hillary Classifier",
    "instructions": "Check if a tweet is by Donald Trump or Hillary Clinton.",
    "categories": ["trump", "hillary"],
    "accuracy": 0.99
  }
)

And that’s it – we can immediately start classifying. (Inspect the response from the previous command to get the classifier id.)

require 'httparty'

HTTParty.post("https://www.hybridml.com/api/classify", 
  basic_auth: { username: "{{YOUR_API_KEY}}" },
  body: {
    "classifier_id": "{{CLASSIFIER_ID}}",
    "text": "To all the little girls watching...never doubt that you are valuable and powerful & deserving of every chance & opportunity in the world."
  }
)
import requests

requests.post("https://www.hybridml.com/api/classify", 
  auth = ("{{YOUR_API_KEY}}", ""),
  json = {
    "classifier_id": "{{CLASSIFIER_ID}}",
    "text": "To all the little girls watching...never doubt that you are valuable and powerful & deserving of every chance & opportunity in the world."
  }
)
curl https://www.hybridml.com/api/classify \
  -u {{YOUR_API_KEY}}: \
  -d classifier_id="{{CLASSIFIER_ID}}", \
  -d text="To all the little girls watching...never doubt that you are valuable and powerful & deserving of every chance & opportunity in the world."

At first, all examples get routed to human labelers. Once enough labels are gathered (usually a minimum of around 50 labels in each category), the machines start taking over more and more of the classifications.

Machine and human classifications are not immediately returned by the classify endpoint, so you will need to check back to see the classification later. There are couple ways to do this:

  1. You can view the classification on your classifier’s page at https://www.hybridml.com/classifiers.
  2. You can also specify a callback_url in your project, where completed classifications will be POSTed, or you can perform a GET request to retrieve the classification later on (see the “Retrieve a classification” API endpoint).

Authentication

To authorize, use this code.

require 'httparty'

# For POST requests
HTTParty.post("{{API_ENDPOINT}}", 
  basic_auth: { username: "{{YOUR_API_KEY}}" },
  body: {
    ... # Parameters in the POST request
  }
)

# For GET requests
HTTParty.get("{{API_ENDPOINT}}", 
  basic_auth: { username: "{{YOUR_API_KEY}}" }
)
import requests

# For POST requests
requests.post("{{API_ENDPOINT}}", 
  auth = ("{{YOUR_API_KEY}}", ""),
  json = {
    ... # Parameters in the POST request
  }
)

# For GET requests
requests.get("{{API_ENDPOINT}}", 
  auth = ("{{YOUR_API_KEY}}", "")
)
# Note that the colon follows the API key and is not part of it.
curl {{API_ENDPOINT}} \
  -u {{YOUR_API_KEY}}:

Hybrid uses API keys to allow access to the API. You can find your API key in your profile.

Authentication is performed via HTTP Basic Auth. Your API key is your basic auth username, and you do not need to provide a password.

If you need to authenticate via bearer auth (e.g., for a cross-origin request), use -H "Authorization: {{YOUR_API_KEY}}:" instead of -u {{YOUR_API_KEY}}:.

Classifiers

The classifier object

Example Response

{
  "id": "17e323f1-f7e4-427c-a2d5-456743aba8",
  "name": "Spam Classifier",
  "instructions": "A text message counts as spam if...",
  "categories": ["spam", "not spam"]  ,
  "accuracy": 0.99,
  "callback_url": "https://www.mywebsite.com/callback",
  "created_at": "2016-11-01T18:56:56.000Z"
}
Parameter Type Description
id string
callback_url string URL where completed classifications are POSTed.
categories array An array of the categories that an example can be classified into.
created_at string
accuracy float Examples will be classified by a machine or human based on this accuracy threshold.
instructions string Instructions given to workers for labeling.
name string Name of the classifier, helpful mainly for organizational purposes.

Create a classifier

Definition

POST https://www.hybridml.com/api/classifiers

Example Request

curl https://www.hybridml.com/api/classifiers \
  -u {{YOUR_API_KEY}}: \
  -d name="Spam Classifier" \
  -d instructions="A text message counts as spam if..." \
  -d categories="spam, not spam" \
  -d accuracy=0.99 \
  -d callback_url="https://www.mywebsite.com/callback"
require 'httparty'

HTTParty.post("https://www.hybridml.com/api/classifiers",
  basic_auth: { username: "{{YOUR_API_KEY}}" },
  body: {
    name: "Spam Classifier",
    instructions: "A text message counts as spam if...",
    categories: ["spam", "not spam"],
    accuracy: 0.99,
    callback_url: "https://www.mywebsite.com/callback"
  }
)
import requests

requests.post("https://www.hybridml.com/api/classifiers", 
  auth = ("{{YOUR_API_KEY}}", ""),
  json = {
    "name": "Spam Classifier",
    "instructions": "A text message counts as spam if...",
    "categories": ["spam", "not spam"],
    "accuracy": 0.99,
    "callback_url": "https://www.mywebsite.com/callback"
  }
)

Example Response

{
  "id": "17e323f1-f7e4-427c-a2d5-456743aba8",
  "name": "Spam Classifier",
  "instructions": "A text message counts as spam if...",
  "categories": ["spam", "not spam"],
  "accuracy": 0.99,
  "callback_url": "https://www.mywebsite.com/callback",
  "created_at": "2016-11-01T18:56:56.000Z"
}

Creates a classifier. You can also create a classifier through the web UI (instead of the API), and still add classifications through the API.

Parameters

Parameter Type Description
name string Name to give your classifier. (required)
categories array An array of the categories texts can be categorized into. (required)
instructions string Any instructions to help workers in their classifications. (optional, default null)
callback_url string URL where completed classifications will be POSTed. (optional, default null)
accuracy float A float between 0 and 1. Examples will be classified by a machine or human based on this accuracy threshold. (optional, default 0.99)

List all classifiers

Definition

GET https://www.hybridml.com/api/classifiers
GET https://www.hybridml.com/api/classifiers?page=n

Example Request

require 'httparty'

HTTParty.get("https://www.hybridml.com/api/classifiers", 
  basic_auth: { username: "{{YOUR_API_KEY}}" }
)
import requests

requests.get("https://www.hybridml.com/api/classifiers", 
  auth = ("{{YOUR_API_KEY}}", "")
)
curl https://www.hybridml.com/api/classifiers \
  -u {{YOUR_API_KEY}}:

Example Response

[
  {
    "id": "17e323f1-f7e4-427c-a2d5-456743aba8",
    "name": "Spam Classifier",
    "instructions": "A text message counts as spam if...",
    "categories": ["spam", "not spam"]  ,
    "accuracy": 0.99,
    "callback_url": "https://www.mywebsite.com/callback",
    "created_at": "2016-11-01T18:56:56.000Z"
  },
  {
    "id": "a20aoesw-039aow-ao093-2leow3",
    "name": "Tennis vs. Basketball Classifier",
    "instructions": "Classify an article as about tennis or basketball.",
    "categories": ["tennis", "basketball"],
    "accuracy": 0.95,
    "callback_url": "https://www.foobar.com/callback",
    "created_at": "2016-10-02T13:16:42.000Z"
  }
]

Lists all classifiers you have created.

Parameters

Parameter Type Description
page integer Classifiers are returned in descending created_at order. Each page contains a maximum of 25 classifiers. Pages start at 1. (optional, default 1)

Retrieve a classifier

Definition

GET https://www.hybridml.com/api/classifiers/{{CLASSIFIER_ID}}

Example Request

require 'httparty'

HTTParty.get("https://www.hybridml.com/api/classifiers/17e323f1-f7e4-427c-a2d5-456743aba8", 
  basic_auth: { username: "{{YOUR_API_KEY}}" }
)
import requests

requests.get("https://www.hybridml.com/api/classifiers/17e323f1-f7e4-427c-a2d5-456743aba8", 
  auth = ("{{YOUR_API_KEY}}", "")
)
curl https://www.hybridml.com/api/classifiers/17e323f1-f7e4-427c-a2d5-456743aba8 \
  -u {{YOUR_API_KEY}}:

Example Response

{
  "id": "17e323f1-f7e4-427c-a2d5-456743aba8",
  "name": "Spam Classifier",
  "instructions": "A text message counts as spam if...",
  "categories": ["spam", "not spam"],
  "accuracy": 0.99,
  "callback_url": "https://www.mywebsite.com/callback",
  "created_at": "2016-11-01T18:56:56.000Z"
}

Retrieves a specific classifier you have created.

Classifications

The classification object

Example Response

{
  "id": "38da6bc5-a644-41b9-a964-4678bc7375c6",
  "classifier_id": "17e323f1-f7e4-427c-a2d5-456743aba8",
  "text": "2016-11-01T18:56:56.000Z",
  "label": "spam",
  "source": "machine"
}
Parameter Type Description
id string
classifier_id string ID of the classifier this classification belongs to.
created_at string
text string The text being classified.
label string The category that the text falls into.
source string The source of the label (one of machine or human).
status string One of pending or complete.

Classify a piece of text

Definition

POST https://www.hybridml.com/api/classify

Example Request

require 'httparty'

HTTParty.post("https://www.hybridml.com/api/classify", 
  basic_auth: { username: "{{YOUR_API_KEY}}" },
  body: {
    "classifier_id": "38da6bc5-a644-41b9-a964-4678bc7375c6",
    "text": "Send me $10 if you want to make a billion."
  }
)
import requests

requests.post("https://www.hybridml.com/api/classify", 
  auth = ("{{YOUR_API_KEY}}", ""),
  json = {
    "classifier_id": "38da6bc5-a644-41b9-a964-4678bc7375c6",
    "text": "Send me $10 if you want to make a billion."
  }
)
curl https://www.hybridml.com/api/classify \
  -u {{YOUR_API_KEY}}: \
  -d classifier_id="38da6bc5-a644-41b9-a964-4678bc7375c6", \
  -d text="Send me $10 if you want to make a billion."

Example Response

{
  "id": "38da6bc5-a644-41b9-a964-4678bc7375c6",
  "classifier_id": "17e323f1-f7e4-427c-a2d5-456743aba8",
  "text": "2016-11-01T18:56:56.000Z",
  "status": "pending",
  "label": "",
  "source": ""
}

Classifies a piece of text.

Parameters

Parameter Type Description
classifier_id string The ID of the classifier to use to classify the piece of text. (required)
text string The text to be classified. (required)

List all classifications

Definition

GET https://www.hybridml.com/api/classifiers/{{CLASSIFIER_ID}}/classifications
GET https://www.hybridml.com/api/classifiers/{{CLASSIFIER_ID}}/classifications?page=n

Example Request

require 'httparty'

HTTParty.get("https://www.hybridml.com/api/classifiers/17e323f1-f7e4-427c-a2d5-456743aba8/classifications", 
  basic_auth: { username: "{{YOUR_API_KEY}}" }
)
import requests

requests.post("https://www.hybridml.com/api/classifiers/17e323f1-f7e4-427c-a2d5-456743aba8/classifications", 
  auth = ("{{YOUR_API_KEY}}", "")
)
curl https://www.hybridml.com/api/classifiers/b31ede78-afdf-4938-b775-8813453c7fc5/classifications \
  -u {{YOUR_API_KEY}}: \
  ...

Example Response

[
  {
    "id": "38da6bc5-a644-41b9-a964-4678bc7375c6",
    "classifier_id": "17e323f1-f7e4-427c-a2d5-456743aba8",
    "text": "2016-11-01T18:56:56.000Z",
    "status": "pending",
    "label": "",
    "source": ""
  },
  {
    "id": "09ouzac-zae03w2s-21904eta-oel2wj",
    "classifier_id": "17e323f1-f7e4-427c-a2d5-456743aba8",
    "text": "2016-11-01T18:51:23.000Z",
    "status": "complete",
    "label": "spam",
    "source": "machine"
  }
]

Lists all classifications belonging to a classifier.

Query Parameters

Parameters

Parameter Type Description
page integer Classifications are returned in ascending created_at order. Each page contains a maximum of 25 classifications. Pages start at 1. (optional, default 1)

Retrieve a classification

Definition

GET https://www.hybridml.com/api/classifications/{{CLASSIFICATION_ID}}

Example Request

require 'httparty'

HTTParty.get("https://www.hybridml.com/api/classifications/38da6bc5-a644-41b9-a964-4678bc7375c6", 
  basic_auth: { username: "{{YOUR_API_KEY}}" }
)
import requests

requests.get("https://www.hybridml.com/api/classifications/38da6bc5-a644-41b9-a964-4678bc7375c6", 
  auth = ("{{YOUR_API_KEY}}", "")
)
curl https://www.hybridml.com/api/classifications/38da6bc5-a644-41b9-a964-4678bc7375c6 \
  -u {{YOUR_API_KEY}}:

Example Response

{
  "id": "38da6bc5-a644-41b9-a964-4678bc7375c6",
  "classifier_id": "17e323f1-f7e4-427c-a2d5-456743aba8",
  "text": "2016-11-01T18:56:56.000Z",
  "status": "complete",
  "label": "spam",
  "source": "machine"
}

Retrieves a specific classification you have created.