Docs
Back to site Get started

🔌 API Endpoints

🌐 Base URL

https://sentor.app/api

For environment-specific URLs, see our API Overview.

🔑 Authentication

All endpoints require API key authentication using the x-api-key header. See our Authentication Guide for details.

📡 Available Endpoints

Entity-Based Sentiment Analysis Endpoints

1. Predict Sentiment

POST /predicts

Analyzes sentiment for one or more documents, with specific focus on entities mentioned in the text.

Query Parameters:

  • language (optional): Language code for sentiment analysis. Supported values: en (English, default), nl (Dutch)

Headers:

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

Request Format:

{
  "docs": [
    {
      "doc": "Text to analyze",
      "doc_id": "unique_id",
      "entities": ["entity1", "entity2"]
    }
  ]
}

Single Document Example (English):

POST /predicts
{
  "docs": [
    {
      "doc": "The new Apple iPhone camera is incredible, but the battery life is disappointing.",
      "doc_id": "doc1",
      "entities": ["Apple", "iPhone", "camera", "battery life"]
    }
  ]
}

Single Document Example (Dutch):

POST /predicts?language=nl
{
  "docs": [
    {
      "doc": "De nieuwe Apple iPhone camera is geweldig, maar de batterijduur is teleurstellend.",
      "doc_id": "doc1",
      "entities": ["Apple", "iPhone", "camera", "batterijduur"]
    }
  ]
}

Response:

{
  "results": [
    {
      "doc_id": "doc1",
      "predicted_class": 1,
      "predicted_label": "neutral",
      "probabilities": {
        "negative": 0.3201063738600350,
        "neutral": 0.6502509312762413,
        "positive": 0.0296427297592163
      },
      "entity_sentiments": [
        {
          "entity": "Apple",
          "sentiment": "neutral"
        },
        {
          "entity": "iPhone",
          "sentiment": "neutral"
        },
        {
          "entity": "camera",
          "sentiment": "positive"
        },
        {
          "entity": "battery life",
          "sentiment": "negative"
        }
      ]
    }
  ]
}

Multiple Documents Example: See our Code Examples for batch processing.

2. Cluster Documents

POST /predicts/cluster

Cluster documents using BERTopic machine learning algorithm to automatically group similar documents together.

Query Parameters:

  • language (optional): Language code for clustering. Supported values: en (English, default), nl (Dutch)

Headers:

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

Request Format:

{
  "documents": [
    {
      "doc_id": "string",
      "text": "string",
      "entities": ["string"]
    }
  ]
}

Requirements:

  • Minimum 5 documents required for clustering
  • Each document must have a unique doc_id

Example Request:

POST /predicts/cluster
{
  "documents": [
    {
      "doc_id": "doc_123",
      "text": "Apple announced new features for the upcoming iPhone 16 series.",
      "entities": ["Apple", "iPhone 16", "Tech"]
    },
    {
      "doc_id": "doc_124",
      "text": "Samsung launched its latest Galaxy phone with an improved camera.",
      "entities": ["Samsung", "Galaxy", "Camera"]
    },
    {
      "doc_id": "doc_125",
      "text": "Microsoft introduced new AI tools for Office 365 users.",
      "entities": ["Microsoft", "AI", "Office 365"]
    },
    {
      "doc_id": "doc_126",
      "text": "Tesla's new update improves autopilot accuracy in city environments.",
      "entities": ["Tesla", "Autopilot", "Software Update"]
    },
    {
      "doc_id": "doc_127",
      "text": "Google released Android 15 with enhanced privacy features.",
      "entities": ["Google", "Android 15", "Privacy"]
    }
  ]
}

Response:

{
  "total_clusters": 3,
  "min_clusters": 2,
  "outliers": 1,
  "clusters": [
    {
      "cluster_id": 0,
      "documents": [
        {
          "doc_id": "doc_123",
          "text": "Apple announced new features for the upcoming iPhone 16 series.",
          "entities": ["Apple", "iPhone 16", "Tech"],
          "cluster_probability": 0.92
        },
        {
          "doc_id": "doc_124",
          "text": "Samsung launched its latest Galaxy phone with an improved camera.",
          "entities": ["Samsung", "Galaxy", "Camera"],
          "cluster_probability": 0.89
        }
      ],
      "top_words": ["phone", "mobile", "device", "camera", "feature"],
      "entities": ["Apple", "Samsung", "iPhone 16", "Galaxy"]
    },
    {
      "cluster_id": 1,
      "documents": [
        {
          "doc_id": "doc_125",
          "text": "Microsoft introduced new AI tools for Office 365 users.",
          "entities": ["Microsoft", "AI", "Office 365"],
          "cluster_probability": 0.94
        }
      ],
      "top_words": ["ai", "tools", "software", "office", "productivity"],
      "entities": ["Microsoft", "AI", "Office 365"]
    }
  ]
}

Note: The min_clusters field shows HDBSCAN’s natural cluster count, which may differ from total_clusters. Documents with low cluster probability may be classified as outliers.

3. Generate Topic Name

POST /predicts/topic-name

Generate a descriptive topic name for a cluster using LLM (Large Language Model). This endpoint should be called after clustering to name each cluster.

Query Parameters:

  • language (optional): Language code for topic naming. Supported values: en (English, default), nl (Dutch)

Headers:

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

Request Format:

{
  "cluster_id": 0,
  "documents": [
    {
      "doc_id": "string",
      "text": "string",
      "entities": ["string"],
      "cluster_probability": 0.92
    }
  ],
  "entities": ["string"],
  "top_words": ["string"]
}

Example Request:

POST /predicts/topic-name
{
  "cluster_id": 0,
  "documents": [
    {
      "doc_id": "doc_123",
      "text": "Apple announced new features for the upcoming iPhone 16 series.",
      "entities": ["Apple", "iPhone 16", "Tech"],
      "cluster_probability": 0.92
    },
    {
      "doc_id": "doc_124",
      "text": "Apple plans to integrate generative AI into its iOS ecosystem next year.",
      "entities": ["Apple", "Generative AI", "iOS"],
      "cluster_probability": 0.87
    }
  ],
  "entities": ["Apple", "iPhone", "iOS"],
  "top_words": ["apple", "iphone", "ios", "features", "ecosystem", "technology", "mobile", "device"]
}

Response:

{
  "cluster_id": 0,
  "topic_name": "Apple iPhone and iOS Technology Updates",
  "generated_using": "company_key"
}

Workflow Tip: You can process topic naming for multiple clusters in parallel to reduce total processing time.

System Endpoints

1. Health Check

GET /predicts/health

Response:

{
    "status": "healthy",
    "version": "1.0.0",
    "models": {
        "sentiment": "v2.1"
    },
    "uptime": "99.99%"
}

📚 Additional Resources

💬 Support