Name: Review Classification API: Complaints, Sentiment, Intent
Brand: leoworks
SKU: api-leoworks-review-comment-classifier
Availability: InStock
Author: API Market

Leo Lee

# Review & Comment Classifier API

## Overview

The Review & Comment Classifier API labels customer reviews and social media comments with typed labels and a probability for each label. It has two endpoints. The reviews endpoint returns complaint types, sentiment and one extra signal that depends on the model: return intent for English product reviews, reply needed for English local business reviews, or purchase motive for Korean, Japanese and Spanish reviews. The comments endpoint returns a comment type (purchase intent, question, complaint, request, praise, spam or other), sentiment, and whether the comment needs a reply. Both endpoints accept up to 20 records per call and up to 5 custom yes/no labels written in plain language, so you can add your own checks such as "mentions the battery" to the same request.

It is built for e-commerce sellers, brand and social media teams, customer support leads, and developers who want structured feedback data without writing prompts or hosting a model. You send JSON with your own record IDs and get JSON back: one result per record in input order, each with a `labels` object holding the label names and probabilities, plus a `summary` with counts per complaint type, comment type and sentiment for the whole batch. The response also names the model version and the variant that answered, so you can tell which label set applies. Because every label carries a probability, you can pick your own threshold for each use.

## Features

*   **2 endpoints**: Classify reviews and classify social media comments.
*   **Review complaint types**: English product reviews use defect, not_as_described, size_fit, performance, usability, shipping, value, safety, seller_service and other. English local business reviews use staff, wait, quality, cleanliness, price, booking, facilities, trust and other. Korean, Japanese and Spanish reviews use product review complaint types for each market.
*   **Comment types**: purchase_intent, question, complaint, request, praise, spam and other.
*   **Sentiment on every record**: positive, neutral or negative, with a probability and a confidence value.
*   **Extra signals**: Return intent for English product reviews, reply needed for English local business reviews and for comments, and purchase motive for Korean, Japanese and Spanish reviews.
*   **Custom labels**: Add up to 5 yes/no criteria per request in plain language (up to 200 characters each). Each one gets its own probability in `labels.custom`.
*   **Languages**: English (`en`), Korean (`ko`), Japanese (`ja`) and Spanish (`es`, beta) for reviews.
*   **Batch input**: Up to 20 records per call. The first 4,000 characters of each text are used. Optional context fields include `title`, `rating`, `category` and `variant` for reviews and `postTitle` for comments.
*   **Batch summary**: Each response includes counts of records classified and failed, and totals per label.
*   **Pinned model**: Every response reports the model version (`jev-1.13.0` at the time of writing) and the variant that answered.
*   **Rate limit**: 1 request per second on the Free plan and 10 requests per second on the Pro, Ultra and Mega plans.

## Use Cases

*   **Low-rating analysis**: Find out why products get 1 to 3 star reviews and which reviews mention a return.
*   **Comment routing**: Answer buying questions first, hide spam and escalate complaints on Instagram, TikTok, YouTube, Facebook or any other channel.
*   **Complaint trend tracking**: Track the complaint mix over time across products, stores, languages and markets.
*   **Local business reputation**: Spot reviews about staff, wait times or cleanliness and see which ones need a reply.
*   **Feedback pipelines**: Feed labelled reviews and comments into dashboards, CRMs, support tools or AI agents.
*   **Custom checks**: Flag reviews or comments that mention a specific feature, product line or shipping region with your own plain-language labels.

## API Documentation

### Base URL

All requests go through the API.market gateway at this base URL:

```
https://prod.api.market/api/v1/leoworks/review-comment-classifier
```

### Authentication

Every request needs your API.market key in the `x-api-market-key` header:

```
x-api-market-key: YOUR_API_KEY
```

Replace `YOUR_API_KEY` with your actual API key.

### Endpoints

#### 1. Classify reviews

Classifies up to 20 reviews and returns complaint types, sentiment and one extra signal per review, plus a batch summary. `language` picks the model. For English, `type` picks the complaint set: `product` or `local_business`. Results come back in input order with your `id` unchanged.

**Method:** `POST`

**Endpoint:** `/v1/reviews/classify`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `language` | body | Review language: `en`, `ko`, `ja` or `es` (beta). | string | No | `en` | - |
| `type` | body | English only. Complaint set to use: `product` or `local_business`. | string | No | `product` | - |
| `reviews` | body | Array of review objects to classify. | array | Yes | - | 20 items |
| `reviews[].id` | body | Your identifier for the review, returned unchanged. | string or integer | No | Position in the array | - |
| `reviews[].text` | body | Review text. | string | Yes | - | First 4,000 characters are used |
| `reviews[].title` | body | Review headline. Added before the text for English product reviews. | string | No | - | - |
| `reviews[].rating` | body | Star rating, for example 1 to 5. | number | No | - | - |
| `reviews[].category` | body | Business category for local business reviews, for example "Dentist". | string | No | - | - |
| `reviews[].variant` | body | Purchased variant for product reviews, for example "Size L, Black". | string | No | - | - |
| `customLabels` | body | Plain-language yes/no criteria to check on every review. | array of strings | No | - | 5 items, 200 characters each |

**Example Request:**

```bash
curl -X POST "https://prod.api.market/api/v1/leoworks/review-comment-classifier/v1/reviews/classify" \
  -H "x-api-market-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"language":"en","type":"product","reviews":[{"id":"r1","title":"Stopped charging","text":"Stopped charging after two weeks. Returning it.","rating":1},{"id":"r2","text":"Fits great but the fabric is see-through when I squat.","rating":3}]}'
```

**Example Response (200 OK):**

```json
{
  "model": "jev-1.13.0",
  "variant": "reviews.en.product",
  "results": [
    {
      "id": "r1",
      "labels": {
        "complaint": [
          {
            "label": "defect",
            "probability": 0.97
          }
        ],
        "sentiment": {
          "label": "negative",
          "probability": 1,
          "confidence": 1
        },
        "returnIntent": {
          "probability": 0.98,
          "matched": true
        }
      }
    },
    {
      "id": "r2",
      "labels": {
        "complaint": [
          {
            "label": "defect",
            "probability": 0.74
          }
        ],
        "sentiment": {
          "label": "neutral",
          "probability": 0.99,
          "confidence": 0.98
        },
        "returnIntent": {
          "probability": 0.04,
          "matched": false
        }
      }
    }
  ],
  "summary": {
    "records": 2,
    "classified": 2,
    "failed": 0,
    "complaint": {
      "defect": 2
    },
    "sentiment": {
      "negative": 1,
      "neutral": 1
    }
  }
}
```

`complaint` is a list, so a review can carry more than one complaint type. `variant` tells you which model answered: `reviews.en.product`, `reviews.en.local_business`, `reviews.ko`, `reviews.ja` or `reviews.es`. If a single review cannot be classified, its result has an `error` field instead of `labels`, and it is counted under `failed` in the summary.

#### 2. Classify comments

Classifies up to 20 social media comments and returns the comment type, sentiment and whether each comment needs a reply, plus a batch summary. Add `postTitle` to give a comment the context of the post it was left on.

**Method:** `POST`

**Endpoint:** `/v1/comments/classify`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `comments` | body | Array of comment objects to classify. | array | Yes | - | 20 items |
| `comments[].id` | body | Your identifier for the comment, returned unchanged. | string or integer | No | Position in the array | - |
| `comments[].text` | body | Comment text. | string | Yes | - | First 4,000 characters are used |
| `comments[].postTitle` | body | Title or caption of the post the comment is on. | string | No | - | - |
| `customLabels` | body | Plain-language yes/no criteria to check on every comment. | array of strings | No | - | 5 items, 200 characters each |

**Example Request:**

```bash
curl -X POST "https://prod.api.market/api/v1/leoworks/review-comment-classifier/v1/comments/classify" \
  -H "x-api-market-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"comments":[{"id":"c1","text":"how much is this and where can I buy it?"},{"id":"c2","text":"my order never arrived, nobody answers emails"}]}'
```

**Example Response (200 OK):**

```json
{
  "model": "jev-1.13.0",
  "variant": "comments",
  "results": [
    {
      "id": "c1",
      "labels": {
        "type": {
          "label": "purchase_intent",
          "probability": 1,
          "confidence": 1
        },
        "sentiment": {
          "label": "neutral",
          "probability": 1,
          "confidence": 1
        },
        "needsReply": {
          "probability": 0.92,
          "matched": true
        }
      }
    },
    {
      "id": "c2",
      "labels": {
        "type": {
          "label": "complaint",
          "probability": 1,
          "confidence": 1
        },
        "sentiment": {
          "label": "negative",
          "probability": 1,
          "confidence": 1
        },
        "needsReply": {
          "probability": 0.95,
          "matched": true
        }
      }
    }
  ],
  "summary": {
    "records": 2,
    "classified": 2,
    "failed": 0,
    "type": {
      "purchase_intent": 1,
      "complaint": 1
    },
    "sentiment": {
      "neutral": 1,
      "negative": 1
    }
  }
}
```

## Status Codes

| Code | Status | Description |
|---|---|---|
| 200 | OK | The batch was processed. Labels for each record and the summary are in the response body. Check each result for an `error` field and the summary's `failed` count. |
| 400 | Bad Request | The request body is invalid, for example more than 20 records, an empty or missing `text`, an unknown `language`, or a missing `x-api-market-key` header. The body explains the reason. |
| 401 | Unauthorized | The `x-api-market-key` value is invalid or expired. |
| 403 | Forbidden | Your subscription does not include this endpoint. |
| 404 | Not Found | The path does not exist. Use `/v1/reviews/classify` or `/v1/comments/classify` with `POST`. |
| 429 | Too Many Requests | You went over your plan's requests-per-second limit or used up your plan's request quota. |
| 500 | Internal Server Error | Something failed while classifying the batch. Retry after a short delay. |

## Rate Limits

The Free plan allows 1 request per second. The Pro, Ultra and Mega plans allow 10 requests per second. Each call counts as one request against your plan's quota, whether it carries 1 record or 20, so batching up to 20 reviews or comments per call is the most efficient way to use your plan. Requests above the per-second limit, or beyond the plan's quota, return `429 Too Many Requests`. When that happens, back off before retrying (for example with exponential backoff) and honour any `Retry-After` header.

## FAQ

**How many reviews or comments can I send in one request?**

Up to 20 records per request. Only the first 4,000 characters of each text are used, so longer texts are not rejected but anything after that point is ignored. Each request counts once against your plan no matter how many records it holds.

**Which languages are supported?**

The reviews endpoint supports English (`en`, the default), Korean (`ko`), Japanese (`ja`) and Spanish (`es`, currently in beta). The `type` field (`product` or `local_business`) applies to English only. Korean, Japanese and Spanish reviews use product review complaint types for each market and return purchase motive as the extra signal.

**How accurate are the labels?**

The provider reports these results on hand-labelled check sets measured in October 2026: English comments 90% for comment type and 86% for sentiment; English product reviews 89% and 98%; English local business reviews 91% and 98%; Korean reviews 88% and 96%; Japanese reviews 91% and 96%; Spanish reviews (beta) 80% and 92%. The provider counts a complaint result as right when it includes a true complaint type and adds none that is wrong. Automated labels can be wrong, so check a sample before acting on large decisions.

**How do I use the probabilities?**

Every label carries a `probability`, and yes/no signals such as `returnIntent` and `needsReply` also return `matched`. You can rely on `matched` or set your own threshold, for example only escalating comments where `needsReply.probability` is above 0.9.

**How do custom labels work?**

Add a `customLabels` array with up to 5 plain-language yes/no criteria, each up to 200 characters, such as "mentions the battery" or "asks about shipping to Canada". Each criterion is checked on every record in the batch and gets its own probability under `labels.custom`.

**What happens if one record in the batch fails?**

The rest of the batch is still returned. The failed record has an `error` field instead of `labels`, and the summary's `failed` count shows how many records could not be classified.

**Is the text I send stored?**

The provider states that this API does not store the review or comment text you send.

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.


Review classification API that labels reviews and social comments with complaint type, sentiment, return intent and reply needed in EN, KO, JA and ES.

Review Classification API: Complaints, Sentiment, Intent

Free