API Reference

Welcome to the Sentor ML API reference documentation. This comprehensive guide provides detailed information about our sentiment analysis API endpoints, authentication methods, and integration examples.

Authentication

All API requests require authentication using an API key. Include your API key in the request header:

x-api-key: YOUR_API_KEY
Content-Type: application/json

Base URL

https://sentor.app/api

Core Endpoints

Sentiment Analysis

Predict Sentiment

POST /predicts

Analyze sentiment for documents with entity-based analysis.

Query Parameters:

language (optional): en (default) or nl

Request Body:

{
  "docs": [
    {
      "doc": "This product is amazing!",
      "doc_id": "doc1",
      "entities": ["product"]
    }
  ]
}

Response:

{
  "results": [
    {
      "doc_id": "doc1",
      "predicted_class": 2,
      "predicted_label": "positive",
      "probabilities": {
        "negative": 0.0001,
        "neutral": 0.0003,
        "positive": 0.9996
      },
      "details": [
        {
          "sentence_index": 0,
          "sentence_text": "This product is amazing!",
          "predicted_class": 2,
          "predicted_label": "positive",
          "probabilities": {
            "negative": 0.0001,
            "neutral": 0.0003,
            "positive": 0.9996
          }
        }
      ]
    }
  ]
}

Cluster Documents

POST /predicts/cluster

Group similar documents using BERTopic (minimum 5 documents required).

Query Parameters:

language (optional): en (default) or nl

Response:

{
  "total_clusters": 3,
  "min_clusters": 2,
  "outliers": 1,
  "clusters": [...]
}

Generate Topic Name

POST /predicts/topic-name

Generate descriptive names for clusters using LLM.

Headers:

X-Google-API-Key (optional): Your Google API key

Response:

{
  "cluster_id": 0,
  "topic_name": "Technology Updates",
  "generated_using": "company_key"
}

System Endpoints

Health Check

GET /predicts/health

Response:

{
  "status": "healthy",
  "version": "1.0.0"
}

Response Codes

Code	Status	Description
200	Success	Request processed successfully
400	Bad Request	Invalid parameters
401	Unauthorized	Invalid API key
403	Forbidden	Insufficient permissions
404	Not Found	Resource not found
429	Too Many Requests	Rate limit exceeded
500	Server Error	Internal server error

Rate Limiting

Plan	Requests/Min	Requests/Day	Requests/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

SDKs & Tools

Python SDK

from sentor import SentorClient

client = SentorClient('YOUR_API_KEY')
result = client.analyze([{
    "doc": "Great product!",
    "doc_id": "doc1",
    "entities": ["product"]
}])
print(result)

JavaScript SDK

import { SentorClient } from 'sentor-sdk';

const client = new SentorClient('YOUR_API_KEY');
const result = await client.analyze({
  docs: [{
    doc: "Great product!",
    doc_id: "doc1",
    entities: ["product"]
  }]
});
console.log(result);

Security

TLS 1.2+ required
API keys encrypted at rest
Regular security audits
SOC 2 Type II compliant
GDPR compliant

Additional Resources

Support

📧 Email: sentor@nikx.one