Skip to main content

API Reference

Complete API reference for Vartovii.

Base URL: https://sentryanalytic.com

Authentication​

Most endpoints are public. Agent tool endpoints require API key:

curl -H "X-API-Key: your-api-key" https://sentryanalytic.com/api/agent/...

Company Endpoints​

Search Companies​

GET /api/company/search?q=QUERY

Parameters:

NameTypeRequiredDescription
qstringYesSearch query
limitintNoMax results (default: 10)

Response:

{
  "companies": [
    {
      "company_name": "BMW",
      "company_slug": "bmw",
      "trust_score": 74,
      "review_count": 5621
    }
  ]
}

Get Company Details​

GET /api/company/SLUG

Response:

{
  "company_name": "BMW",
  "company_slug": "bmw",
  "trust_score": 74,
  "risk_level": "MEDIUM",
  "avg_rating": 3.97,
  "review_count": 5621,
  "sentiment": {
    "positive": 50,
    "negative": 40,
    "neutral": 10
  },
  "data_freshness": "fresh",
  "last_updated": "2025-12-27"
}
GET /api/search/smart?q=QUERY&auto_scrape=true

Parameters:

NameTypeDefaultDescription
qstringrequiredCompany name
countrystring"de"Country code
auto_scrapebooltrueAuto-trigger scraping

Response:

{
  "status": "found",
  "company_name": "BMW",
  "data_status": "fresh",
  "review_count": 5621,
  "scraping_jobs": []
}

AI Chat Endpoints​

Chat with AI​

POST /api/ai/chat

Request:

{
  "message": "What's the Trust Score for BMW?",
  "language": "auto",
  "enable_grounding": false,
  "enable_rag": true
}

Response:

{
  "response": "BMW has a Trust Score of 74/100...",
  "status": "ok",
  "grounded": false,
  "rag_used": true,
  "tools_used": true,
  "tool_calls": [
    {"name": "search_company", "args": {"company_name": "BMW"}}
  ]
}

Health Check​

GET /api/ai/chat/health

Response:

{
  "status": "healthy",
  "model": "gemini-2.5-flash",
  "rag_corpus": "active"
}

Agent Tool Endpoints​

⚠️ Requires API Key: X-API-Key header

Search Company​

POST /api/agent/search-company

Request:

{
  "company_name": "BMW",
  "country": "de"
}

Get Trust Score​

POST /api/agent/trust-score

Request:

{
  "company_name": "BMW"
}

Response:

{
  "company_name": "BMW",
  "trust_score": 74,
  "risk_level": "MEDIUM",
  "breakdown": {
    "rating_quality": 22.2,
    "sentiment": 12.5,
    "volume": 20.0,
    "consistency": 9.0,
    "recency": 10.0
  }
}

List Companies​

POST /api/agent/list-companies

Request:

{
  "country": "de",
  "limit": 10,
  "sort_by": "trust_score"
}

Compare Companies​

POST /api/agent/compare-companies

Request:

{
  "company1": "BMW",
  "company2": "Audi"
}

Run Analysis​

POST /api/agent/run-analysis

Request:

{
  "company_name": "Spotify",
  "country": "de"
}

Response:

{
  "action": "analysis_started",
  "company_name": "Spotify",
  "company_slug": "spotify-ab1",
  "scraping_jobs": ["uuid1", "uuid2", "uuid3", "uuid4"],
  "message": "🚀 Analysis started!"
}

Get Company Reviews​

POST /api/agent/get-reviews

Request:

{
  "company_name": "BMW",
  "sentiment": "positive",
  "limit": 5
}

Scraping Endpoints​

POST /api/scraping/magic-search

Request:

{
  "company_name": "Spotify",
  "country": "de",
  "months_back": 24
}

Get Job Status​

GET /api/scraping/jobs/JOB_ID

Response:

{
  "job_id": "uuid",
  "status": "running",
  "source": "kununu",
  "company_name": "Spotify",
  "reviews_collected": 156,
  "progress_percent": 78
}

List All Jobs​

GET /api/scraping/jobs

List Active Jobs​

GET /api/scraping/jobs/active

Job Control​

POST /api/scraping/jobs/{job_id}/pause
POST /api/scraping/jobs/{job_id}/resume
POST /api/scraping/jobs/{job_id}/cancel

Analytics Endpoints​

Get Company Stats​

GET /api/stats?company_slug=bmw

Sentiment Distribution​

GET /api/sentiment-distribution?company_slug=bmw

Response:

{
  "positive": 50,
  "negative": 35,
  "neutral": 15
}

Rating Distribution​

GET /api/rating-distribution?company_slug=bmw

Get Reviews​

GET /api/reviews?company_slug=bmw&limit=50

Get Aspects (ABSA)​

GET /api/aspects?company_slug=bmw

Response:

{
  "aspects": [
    {"name": "Work-Life Balance", "positive": 120, "negative": 45},
    {"name": "Salary", "positive": 80, "negative": 90}
  ]
}

Get Vacancies​

GET /api/vacancies?company_slug=bmw

Timeline​

GET /api/timeline?company_slug=bmw

Reports Endpoints​

Generate Report​

Trigger AI analysis for a company and save results to database.

POST /api/analyze/{company_slug}

Response:

{
  "status": "success",
  "company": "BMW",
  "analysis": {
    "EXECUTIVE SUMMARY": "BMW shows strong employee satisfaction...",
    "STRENGTHS": "Work-life balance, career growth opportunities...",
    "CONCERNS": "Management communication, workload in some departments...",
    "RECOMMENDATIONS": "Focus on improving internal communication..."
  }
}

Notes:

  • Analysis runs in background thread (async)
  • Results cached in company_reports table
  • Re-triggering overwrites previous analysis

Get Report​

GET /api/reports/{company_name}

Download PDF Report​

GET /api/download-report/{company_name}

Response: PDF file download

Crypto Endpoints​

Search Crypto Projects​

GET /api/v2/crypto/search?q=QUERY

Get Crypto Project​

GET /api/v2/crypto/project/SLUG

Response:

{
  "name": "Polkadot",
  "symbol": "DOT",
  "trust_score": 81,
  "risk_level": "LOW",
  "price_usd": 7.25,
  "market_cap": 9500000000,
  "tvl": 1200000000
}

Error Responses​

All endpoints return errors in this format:

{
  "detail": "Company not found",
  "status_code": 404
}

Common Status Codes:

CodeMeaning
200Success
400Bad request
401Unauthorized (missing API key)
404Not found
429Rate limited
500Server error

API documentation is also available at /docs (Swagger UI).

Forensic Agent Endpoints​

⚠️ Available via AI Chat or Agent Tools - These endpoints power the Forensic Agent

Check Wallet Balance​

POST /api/forensic/check_wallet

Request:

{
  "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
}

Response:

{
  "address": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
  "eth_balance": 32.1112,
  "usd_value": 94241.62,
  "found": true,
  "chain": "ethereum",
  "etherscan_link": "https://etherscan.io/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
}

Get Transaction History​

POST /api/forensic/transaction_history

Request:

{
  "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
  "limit": 10,
  "days": 30
}

Response:

{
  "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
  "transactions": [
    {
      "hash": "0x123...",
      "from": "0xabc...",
      "to": "0xd8dA...",
      "value_eth": 2.5,
      "value_usd": 7334.15,
      "timestamp": "2026-01-20T10:30:00Z",
      "direction": "in"
    }
  ],
  "count": 5,
  "etherscan_link": "https://etherscan.io/address/0xd8dA...#transactions"
}

Get Token Holders​

POST /api/forensic/token_holders

Request:

{
  "contract_address": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
  "limit": 20
}

Response:

{
  "contract_address": "0xdac17f958d2ee523a2206206994597c13d831ec7",
  "token_symbol": "USDT",
  "token_price_usd": 0.998,
  "holders": [
    {
      "rank": 1,
      "address": "0xf977814e90da44bfa03b6295a0616a897441acec",
      "balance": "21,951,179,974.29 USDT",
      "balance_usd": 21925650751.98,
      "percentage": 18.5
    }
  ],
  "count": 20,
  "total_supply": 118490426863.74,
  "etherscan_link": "https://etherscan.io/token/0xdac17f..."
}

Get Contract Info​

POST /api/forensic/contract_info

Request:

{
  "contract_address": "0xdAC17F958D2ee523a2206206994597C13D831ec7"
}

Response:

{
  "address": "0xdac17f958d2ee523a2206206994597c13d831ec7",
  "found": true,
  "is_erc20": true,
  "is_erc721": false,
  "deployed_at": "2017-11-28T00:41:21+00:00",
  "has_bytecode": true,
  "contract_type": "ERC20 Token",
  "etherscan_link": "https://etherscan.io/address/0xdac17f..."
}

Health Check​

GET /api/forensic/health

Response:

{
  "status": "healthy",
  "bigquery_available": true,
  "coingecko_available": true
}