{
  "name": "Sentor AI",
  "version": "1.0.0",
  "description": "Entity-based sentiment analysis API for customer feedback analytics. Analyze sentiment on specific entities with high accuracy using advanced BERT and RoBERTa models.",
  "icon": "https://sentor.app/assets/images/logo.svg",
  "homepage": "https://sentor.app",
  "documentation": "https://sentor.app/docs",
  "author": {
    "name": "NIKX Technologies B.V.",
    "email": "sentor@nikx.one",
    "url": "https://sentor.app"
  },
  "authentication": {
    "type": "api_key",
    "header": "x-api-key",
    "description": "API key authentication via x-api-key header"
  },
  "capabilities": {
    "sentiment_analysis": {
      "description": "Entity-based sentiment analysis with support for English and Dutch",
      "features": [
        "Entity-level sentiment detection",
        "Multi-language support (en, nl)",
        "High accuracy predictions",
        "Batch processing",
        "Sub-second response times"
      ]
    },
    "clustering": {
      "description": "Cluster documents using BERTopic machine learning algorithm",
      "features": [
        "HDBSCAN natural cluster count",
        "Multi-language support (en, nl)"
      ]
    },
    "topic_naming": {
      "description": "Generate descriptive topic names for clusters using LLM",
      "features": [
        "LLM-based naming",
        "Multi-language support (en, nl)"
      ]
    }
  },
  "endpoints": {
    "predicts": {
      "method": "POST",
      "path": "/api/predicts",
      "description": "Analyze sentiment for one or more documents with entity focus",
      "parameters": {
        "language": {
          "type": "query",
          "description": "Language code (en, nl). Default: en",
          "optional": true
        }
      },
      "request": {
        "type": "object",
        "required": [
          "docs"
        ],
        "properties": {
          "docs": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "doc",
                "doc_id",
                "entities"
              ],
              "properties": {
                "doc": {
                  "type": "string",
                  "description": "Text to analyze"
                },
                "doc_id": {
                  "type": "string",
                  "description": "Unique document identifier"
                },
                "entities": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  },
                  "description": "List of entities to analyze sentiment for"
                }
              }
            }
          }
        }
      },
      "response": {
        "type": "object",
        "properties": {
          "results": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "doc_id": {
                  "type": "string"
                },
                "predicted_class": {
                  "type": "integer",
                  "description": "0=negative, 1=neutral, 2=positive"
                },
                "predicted_label": {
                  "type": "string",
                  "enum": [
                    "negative",
                    "neutral",
                    "positive"
                  ]
                },
                "probabilities": {
                  "type": "object",
                  "properties": {
                    "negative": {
                      "type": "number"
                    },
                    "neutral": {
                      "type": "number"
                    },
                    "positive": {
                      "type": "number"
                    }
                  }
                },
                "entity_sentiments": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "entity": {
                        "type": "string"
                      },
                      "sentiment": {
                        "type": "string",
                        "enum": [
                          "negative",
                          "neutral",
                          "positive"
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "health": {
      "method": "GET",
      "path": "/api/predicts/health",
      "description": "Health check endpoint",
      "response": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "healthy"
            ]
          },
          "version": {
            "type": "string"
          },
          "models": {
            "type": "object"
          },
          "uptime": {
            "type": "string"
          }
        }
      }
    },
    "cluster": {
      "method": "POST",
      "path": "/api/predicts/cluster",
      "description": "Cluster documents using BERTopic",
      "parameters": {
        "language": {
          "type": "query",
          "description": "Language code (en, nl). Default: en",
          "optional": true
        }
      },
      "request": {
        "type": "object",
        "required": [
          "documents"
        ],
        "properties": {
          "documents": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "doc_id",
                "text",
                "entities"
              ],
              "properties": {
                "doc_id": {
                  "type": "string"
                },
                "text": {
                  "type": "string"
                },
                "entities": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              }
            }
          }
        }
      },
      "response": {
        "type": "object",
        "properties": {
          "clusters": {
            "type": "array"
          },
          "total_documents": {
            "type": "integer"
          },
          "total_clusters": {
            "type": "integer"
          }
        }
      }
    },
    "topic-name": {
      "method": "POST",
      "path": "/api/predicts/topic-name",
      "description": "Generate a descriptive topic name for a cluster",
      "parameters": {
        "language": {
          "type": "query",
          "description": "Language code (en, nl). Default: en",
          "optional": true
        }
      },
      "request": {
        "type": "object",
        "required": [
          "cluster_id",
          "documents"
        ],
        "properties": {
          "cluster_id": {
            "type": "integer"
          },
          "documents": {
            "type": "array"
          },
          "entities": {
            "type": "array"
          },
          "top_words": {
            "type": "array"
          }
        }
      },
      "response": {
        "type": "object",
        "properties": {
          "cluster_id": {
            "type": "integer"
          },
          "topic_name": {
            "type": "string"
          },
          "document_count": {
            "type": "integer"
          },
          "generation_method": {
            "type": "string"
          }
        }
      }
    }
  },
  "rate_limits": {
    "free": {
      "requests_per_minute": 3,
      "requests_per_day": 30,
      "requests_per_month": 300
    },
    "starter": {
      "requests_per_minute": 60,
      "requests_per_day": 500,
      "requests_per_month": 3000
    },
    "growth": {
      "requests_per_minute": 200,
      "requests_per_day": 2000,
      "requests_per_month": 15000
    },
    "business": {
      "requests_per_minute": 500,
      "requests_per_day": 5000,
      "requests_per_month": 60000
    },
    "enterprise": {
      "requests_per_minute": 10000,
      "requests_per_day": 100000,
      "requests_per_month": "unlimited"
    }
  },
  "environments": {
    "production": {
      "base_url": "https://sentor.app/api",
      "mcp_url": "https://sentor.app/.well-known/mcp.json"
    },
    "development": {
      "base_url": "https://dev.sentor.app/api",
      "mcp_url": "https://dev.sentor.app/.well-known/mcp.json"
    },
    "qa": {
      "base_url": "https://qa.sentor.app/api",
      "mcp_url": "https://qa.sentor.app/.well-known/mcp.json"
    },
    "uat": {
      "base_url": "https://uat.sentor.app/api",
      "mcp_url": "https://uat.sentor.app/.well-known/mcp.json"
    }
  },
  "support": {
    "email": "sentor@nikx.one",
    "documentation": "https://sentor.app/docs",
    "discord": "https://discord.gg/kRJCMMU6MM",
    "status": "https://status.sentor.app"
  },
  "examples": {
    "sentiment_analysis": {
      "description": "Analyze sentiment for delivery entity",
      "request": {
        "docs": [
          {
            "doc": "The delivery was fast and the package arrived in perfect condition",
            "doc_id": "doc1",
            "entities": [
              "delivery"
            ]
          }
        ]
      },
      "response": {
        "results": [
          {
            "doc_id": "doc1",
            "predicted_class": 2,
            "predicted_label": "positive",
            "probabilities": {
              "negative": 0.0001,
              "neutral": 0.0003,
              "positive": 0.9997
            },
            "entity_sentiments": [
              {
                "entity": "delivery",
                "sentiment": "positive"
              }
            ]
          }
        ]
      }
    }
  }
}