# Sentor AI - For LLMs

> **Title:** Sentor AI
> **Description:** Entity-based sentiment analysis API for customer feedback analytics. Analyze sentiment on specific entities with high accuracy using fine-tuned BERT models.
> **Homepage:** https://sentor.app
> **Documentation:** https://sentor.app/docs
> **MCP Server:** https://pypi.org/project/sentor-mcp/

## Introduction

Sentor AI provides a highly accurate, multi-language (en, nl) sentiment analysis API that detects sentiment at the entity-level, not just document-level. This is useful for analyzing customer feedback, product reviews, and support tickets where multiple subjects are discussed with varying sentiments.

The core differentiator is **entity masking** — the model scores sentiment specifically *toward named entities* (brands, products, features, people) rather than producing a single document-level score.

## MCP Server (Recommended for AI Assistants)

Install the official Sentor MCP server to use sentiment analysis directly in Claude Desktop, Cursor, Windsurf, and any MCP-compatible environment:

```bash
pip install sentor-mcp
```

Add to your MCP config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "sentor": {
      "command": "sentor-mcp",
      "env": {
        "SENTOR_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

Get your API key at https://dashboard.sentor.app/settings?tab=api-access

## Quick Start API Guide

### Authentication
Include the API key in the `x-api-key` header for all requests.

Base URL: `https://sentor.app/api`

### Endpoint: `POST /api/predicts`

**Description:** Analyze sentiment for one or more documents, highlighting specific entities.

**Request Structure:**
```json
{
  "docs": [
    {
      "doc": "The delivery was fast and the package arrived in perfect condition, but customer support was terrible.",
      "doc_id": "doc1",
      "entities": ["delivery", "support"]
    }
  ]
}
```

*Optional Query Parameter:* `?language=en` or `?language=nl` (Default: en).

**Response Structure:**
```json
{
  "results": [
    {
      "doc_id": "doc1",
      "predicted_class": 1,
      "predicted_label": "neutral",
      "probabilities": {
        "negative": 0.3,
        "neutral": 0.4,
        "positive": 0.3
      },
      "details": [
        {
          "sentence_index": 0,
          "sentence_text": "The delivery was fast...",
          "predicted_label": "positive",
          "probabilities": { "negative": 0.01, "neutral": 0.05, "positive": 0.94 }
        }
      ]
    }
  ]
}
```

### Endpoint: `POST /api/predicts/cluster`

**Description:** Cluster documents using BERTopic + HDBSCAN. Requires minimum 5 documents. The algorithm automatically discovers the number of clusters.

**Request Structure:**
```json
{
  "documents": [
    {
      "doc_id": "doc_123",
      "text": "This is a sample document for clustering.",
      "entities": ["Apple", "iPhone"]
    }
  ]
}
```
*Optional Query Parameter:* `?language=en` or `?language=nl` (Default: en).

**Response Structure:**
```json
{
  "clusters": [
    {
      "cluster_id": 0,
      "document_count": 3,
      "documents": [],
      "top_words": ["apple", "iphone", "quality"]
    }
  ],
  "total_documents": 10,
  "total_clusters": 3,
  "outliers_count": 1,
  "clustering_method": "HDBSCAN",
  "language": "en",
  "min_clusters": 3
}
```

### Endpoint: `POST /api/predicts/topic-name`

**Description:** Generate a descriptive topic name for a cluster using an LLM. Use this endpoint after clustering. Pass `top_words` from the clustering response for best results.

**Request Structure:**
```json
{
  "cluster_id": 0,
  "documents": [],
  "entities": ["Apple", "iPhone"],
  "top_words": ["apple", "iphone", "quality"]
}
```

**Response Structure:**
```json
{
  "cluster_id": 0,
  "topic_name": "Product Quality Concerns",
  "document_count": 3,
  "generation_method": "LLM",
  "api_key_source": "company"
}
```

### Endpoint: `GET /api/predicts/health`

**Description:** Check API and ML model availability.

**Response:**
```json
{
  "status": "healthy",
  "version": "1.0.0",
  "llm_provider": "google",
  "llm_status": "available",
  "embedding_model": "paraphrase-multilingual-mpnet-base-v2"
}
```

### Rate Limits by Plan

| Plan | Per Minute | Per Day | Per Month |
|------|-----------|---------|-----------|
| Free | 5 | 100 | 1,000 |
| Starter | 60 | 1,000 | 10,000 |
| Growth | 200 | 3,000 | 30,000 |
| Business | 500 | 10,000 | 100,000 |
| Enterprise | Custom | Custom | Custom |

## Developer Notes for AIs

- `docs` must be an array of objects, each with `doc_id` (string), `doc` (string), and `entities` (string array).
- `entities` are the subjects of interest — e.g. brand names, product features, service aspects.
- Clustering requires at least 5 documents. Pass `top_words` from the cluster response to `topic-name` for better labels.
- Languages supported: `en` (English) and `nl` (Dutch).
- For code generation, prefer `httpx` (Python) or `fetch` (JavaScript) with the `x-api-key` header.
- Full pricing and plan details: https://sentor.app/pricing
- Full API reference: https://sentor.app/docs