API Reference

Parameters

Taylor's API is designed to be simple to use, but flexible enough to handle a wide range of use cases.

You have control over how many and what types of labels are returned, and you can customize the output to fit your needs.

Required Parameters

model (string): The model you want to use. The below are out-of-the-box models you can use right away:
- topics
- intent
- job_postings
- products
texts (list of strings): The text you want to analyze. You can provide multiple texts in a single request. Each text should be a string. The maximum number of texts you can provide in a single request is 100.

Optional Parameters

threshold (float, default=0.1): The minimum score required for a label to be included in the response. The threshold should be a float between 0 and 1. The right threshold depends on your use case. If you set a high threshold, you may not get any labels.
top_k (int, default=10): The maximum number of labels to return for each text segment. top_k is applied after the threshold filter, so you are not guaranteed to get k labels unless you set the threshold to 0.
prefix (string, default=""): When provided, labels will be filtered to only include those that start with the prefix. This is useful for models that return hierarchical labels, as you can specify to only classify within a predetermined domain. For example, if you are classifying medical texts with our Topics Classifier, you can set the prefix to "/health" to only get the topic labels related to Health.

Use Case: Get 3 labels

For example, I want to get at most 3 topic labels for recent news that I webscraped, such as the below news about over-the-counter continuous glucose monitors.

Request Body:

"model": "topics",
"texts": [
  """
  On Mar 5, 2024, the USFDA cleared for marketing the first over-the-counter continuous glucose monitor (CGM). The Dexcom Stelo Glucose Biosensor medical device is an integrated CGM (iCGM) intended for adults who do not use insulin, such as individuals with diabetes treating their condition with oral medications, or those without diabetes who want to better understand how diet and exercise may impact blood sugar levels.
  """,
],
"top_k": 3,

Response:

{
  "results": [
    {
      "labels": [
        "/Health/Health Conditions/Blood Sugar & Diabetes",
        "/Health/Medical Devices & Equipment",
        "/Finance & Business/Chemicals Industry"
      ],
      "scores": [0.81, 0.5053460308422771, 0.19]
    }
  ],
  "runtime": 0.10980463027954102,
  "message": null
}

Use Case: Get 3 labels within prefix

For example, I want to get at most 3 topic labels for recent news that I webscraped, such as the below news about over-the-counter continuous glucose monitors. I also want to restrict labels to within the Health domain.

Request Body:

"model": "topics",
"texts": [
  """
  On Mar 5, 2024, the USFDA cleared for marketing the first over-the-counter continuous glucose monitor (CGM). The Dexcom Stelo Glucose Biosensor medical device is an integrated CGM (iCGM) intended for adults who do not use insulin, such as individuals with diabetes treating their condition with oral medications, or those without diabetes who want to better understand how diet and exercise may impact blood sugar levels.
  """,
],
"top_k": 3,
"prefix": "/Health"

Response:

{
  "results": [
    {
      "labels": [
        "/Health/Health Conditions/Blood Sugar & Diabetes",
        "/Health/Medical Devices & Equipment",
        "/Health/Medical Research"
      ],
      "scores": [0.81, 0.6735198012071111, 0.21578222999279698]
    }
  ],
  "runtime": 0.11744523048400879,
  "message": null
}

Authentication

The Taylor API uses API keys to authorize and authenticate requests. You can generate and revoke keys from the "API Keys" section of the Taylor dashboard. For security, keys will be shown once, and expire after 30 days. Do not share API keys in GitHub repositories or client-side code. The best practice is typically to store API keys in environment variables for production use.

When making API requests, provide the key in the Authorization header as a Bearer token. For example:

Request Format

Requests to the Taylor API should be made using the POST method to the following URL:

https://api.trytaylor.ai/api/public_classifiers/predict

The request body should be a JSON object with the following fields:

model (string): The model to use for classification. Currently, we offer the following models:
- topics: Categorizes text by topic (over 1,000 hierarchical categories).
- products: Categorizes text (e.g. listings, reviews, etc.) into hierarchical product categories.
- intents: Categorizes user queries by intent (e.g. search, booking a hotel, conversational, programming help, etc.)
- job_postings: Categorizes job postings into around 30 high-level job categories, like Customer Service, Data and Analytics, Education, etc.
texts (list of strings): The texts to classify. Each text segment should be a string. We support batching up to 20 texts per request. Note that each text is billed as 1 prediction.
threshold (float, optional): The minimum score required for a label to be included in the response. The threshold should be a float between 0 and 1. The right threshold depends on your use case, but it is set to 0.1 by default. If you set a high threshold, you may not get any labels.
top_k (int, optional): The maximum number of labels to return for each text segment. The default is 10. top_k is applied after the threshold filter, so you are not guaranteed to get k labels unless you set the threshold to 0.
prefix (string, optional): When provided, labels will be filtered to only include those that start with the prefix. This is useful for models that return hierarchical labels, as you can specify to only classify within a predetermined domain.

Response Format

A successful response (status code 200) contains 3 fields:

runtime (float): The time taken to process the request in seconds.
results (list): List of classification results, one per input text. Each result has a labels field with a list of the labels, and a scores field with the corresponding scores.
message (string): An optional message which may include helpful information about the request or response (e.g. calling out a deprecated endpoint or model, a note about setting the threshold, etc.).

Empty Responses

The Taylor API may return an empty response. If you encounter a successful status with no labels provided, the reasons could include:

The threshold value is set too high. Consider reducing it.
The model yielded inconclusive results. If you do not define a threshold, the default threshold = 0.1. It's likely your text input cannot be definitively categorized into labels, which will result in the Taylor API delivering an empty list.

Entity Extraction Parallel Processing