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:

Name	Type	Required	Description
q	string	Yes	Search query
limit	int	No	Max 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"
}

Smart Search

GET /api/search/smart?q=QUERY&auto_scrape=true

Parameters:

Name	Type	Default	Description
q	string	required	Company name
country	string	"de"	Country code
auto_scrape	bool	true	Auto-trigger scraping

Response:

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

Notes:

In cloud mode, newly created scraping jobs are dispatched to workers immediately after creation.
Clients should use company_slug for canonical routing when present, while still treating company_name as the display label.

AI Chat Endpoints

Chat with AI

POST /api/ai/chat

Request:

{
  "message": "What's the Trust Score for BMW?",
  "conversation_id": "cw_abcd1234",
  "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,
  "execution": {
    "status": "ok",
    "grounded": false,
    "rag_used": true,
    "tools_used": true,
    "adk_agent": true,
    "adk_tools": ["search_company", "get_trust_score"],
    "adk_session_id": "s_ab12cd34ef56",
    "conversation_id": "cw_abcd1234",
    "sources_count": 0
  },
  "message_id": "uuid-message-id"
}

Notes:

conversation_id should be reused by clients across turns to preserve ADK session continuity.
execution.adk_tools is the canonical tool trace payload for UI message timelines and analytics.
Attachments (optional) are validated server-side with guardrails:
- allowed MIME types via CHAT_ALLOWED_MIME_TYPES
- max files via CHAT_MAX_ATTACHMENTS (default: 4)
- per-file size via CHAT_MAX_ATTACHMENT_BYTES (default: 5MB)
- total payload via CHAT_MAX_TOTAL_ATTACHMENT_BYTES (default: 10MB)

Health Check

GET /api/ai/chat/health

Response:

{
  "status": "operational",
  "model": "gemini-2.5-flash",
  "grounding_enabled": true,
  "rag_enabled": true
}

Public API Endpoints

Public Company Trust Score

GET /api/v1/trust-score/{company}

Notes:

Includes last_updated and data_freshness
Successful responses expose public rate-limit headers
Error payloads use the canonical error.code / error.message / error.status schema

Public Crypto Trust Score

GET /api/v1/crypto/{slug}

Notes:

Includes last_updated and data_freshness
Successful responses expose public rate-limit headers
Error payloads use the canonical error.code / error.message / error.status schema

Public Unified Search

GET /api/v1/search?q=QUERY&type=all&limit=5&sort_by=trust_score&sort_order=desc

Notes:

Cursor-based pagination via the opaque cursor parameter
Per-result freshness plus response-level freshness block
Stable nested pagination and freshness response objects
Error payloads use the canonical error.code / error.message / error.status schema
Language examples live in Public API (v1)

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"
}

Notes:

sort_by: "trust_score" uses canonical 6-factor Trust Score per company and is ranked after runtime score computation (not SQL proxy formulas).

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

Magic Search

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

These control endpoints share one repository-backed job-status contract across the scraping API and legacy compatibility helpers.

Trigger Worker (Protected)

POST /api/scraping/trigger-worker

Auth required: X-Internal-Key or X-Admin-Token Rate limit: 5/minute

Analytics Endpoints

Get Company Stats

GET /api/stats?company=BMW

Response (excerpt):

{
  "total_reviews": 5621,
  "avg_rating": 3.97,
  "sentiment_coverage": 96.4,
  "recent_reviews": 312,
  "trust_score": 74,
  "score_breakdown": {
    "rating_quality": 19,
    "sentiment": 14,
    "volume": 15,
    "source_diversity": 15,
    "consistency": 7,
    "recency": 4
  }
}

Sentiment Distribution

GET /api/sentiment-distribution?company=BMW

Response:

{
  "distribution": [
    {"label": "POSITIVE", "count": 2810},
    {"label": "NEGATIVE", "count": 1960},
    {"label": "NEUTRAL", "count": 851}
  ]
}

Rating Distribution

GET /api/rating-distribution?company=BMW

Get Reviews

GET /api/reviews?company=BMW&limit=50

Get Aspects (ABSA)

GET /api/aspects?company=BMW

Response:

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

Get Vacancies

GET /api/vacancies?company=BMW

Timeline

GET /api/timeline?company=BMW

Notes:

company is resolved to canonical entity identity before querying.
Filtering uses exact match (LOWER(company_name) = LOWER(%s)).
Unresolved company identifiers return {"timeline": []}.

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 resolves the slug/input to the canonical reviews.company_name before fetching AI source data
Frontend clients should refresh report data immediately after a successful response; a fixed wait is not required
Results cached in company_reports table
Re-triggering overwrites previous analysis
Auth required: X-Internal-Key or X-Admin-Token

Get Report

GET /api/reports/{company_name}

Response (excerpt):

{
  "company_name": "BMW",
  "trust_score": 74,
  "report_status": "cached",
  "stats": {
    "avg_rating": 3.9,
    "total_reviews": 5621
  }
}

Download PDF Report

GET /api/reports/download/{company_name}

Response: PDF file download Headers: X-Report-Status (ok, quality-degraded, no-data, fallback), X-Topics-Status (ok, empty, unavailable)

Topic fallback behavior: synthetic placeholder topics are not injected when topic query fails; status is surfaced via X-Topics-Status.

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:

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

Protected Write Endpoints (Internal/Admin)

These heavy write endpoints require X-Internal-Key or X-Admin-Token:

POST /api/analyze/{company_slug}
POST /api/analytics/analyze/{company_slug}
POST /api/ai/run-analysis
POST /api/crypto/refresh/{slug}
POST /api/scraping/trigger-worker

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"
}

Validation rules (2026-03-04):

Must match 0x + 40 hex chars.
Mixed-case addresses must pass EIP-55 checksum validation.
Invalid format/checksum returns 422.

Response:

{
  "address": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
  "eth_balance": 32.1112,
  "usd_value": 94241.62,
  "eth_price": 2934.2,
  "token_balances": [
    {
      "contract_address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      "symbol": "USDC",
      "name": "USD Coin",
      "decimals": 6,
      "balance": 2500.0,
      "balance_raw": 2500000000.0,
      "token_price_usd": 1.0,
      "usd_value": 2500.0
    }
  ],
  "found": true,
  "chain": "ethereum"
}

Get Transaction History

POST /api/forensic/transaction_history

Request:

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

Response:

{
  "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
  "transactions": [
    {
      "tx_hash": "0x123...",
      "from": "0xabc...",
      "to": "0xd8dA...",
      "eth_value": 2.5,
      "gas_price_gwei": 12.4,
      "status": "success",
      "timestamp": "2026-01-20T10:30:00Z",
      "direction": "in"
    }
  ],
  "count": 5
}

Error contract:

On forensic backend/query failures, endpoint returns HTTP 503 with stable error detail (no list-wrapped error payloads).

Get Token Holders

POST /api/forensic/token_holders

Request:

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

Response:

{
  "contract_address": "0xdac17f958d2ee523a2206206994597c13d831ec7",
  "holders": [
    {
      "rank": 1,
      "address": "0xf977814e90da44bfa03b6295a0616a897441acec",
      "balance": 21951179974.29,
      "balance_raw": 21951179974290000,
      "usd_value": 21907277614.34
    }
  ],
  "count": 20,
  "total_balance": 118490426863.74,
  "decimals": 6,
  "token_price_usd": 0.998,
  "total_usd_value": 118253446010.01
}

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,
  "is_verified_source": true,
  "verification_source": "etherscan",
  "verification_url": "https://etherscan.io/address/0xdac17f958d2ee523a2206206994597c13d831ec7#code",
  "contract_name": "Tether USD"
}

Health Check

GET /api/forensic/health

Response:

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

Live Endpoint Inventory (Auto-generated)

Source: synchronized from backend OpenAPI via scripts/sync_api_endpoints_doc.py

Base URL: https://sentryanalytic.com

Category	Method	Path
AI	`POST`	`/api/ai/chat`
AI	`GET`	`/api/ai/chat/health`
AI	`POST`	`/api/ai/feedback`
AI	`POST`	`/api/ai/run-analysis`
AI	`POST`	`/api/ai/search`
Admin	`POST`	`/api/admin/alerts/process-score-changes`
Admin	`GET`	`/api/admin/companies`
Admin	`DELETE`	`/api/admin/company/{company_slug}`
Admin	`GET`	`/api/admin/data-quality`
Admin	`GET`	`/api/admin/db-health`
Admin	`GET`	`/api/admin/farcaster/generate`
Admin	`GET`	`/api/admin/feedback`
Admin	`POST`	`/api/admin/feedback/classify-all`
Admin	`GET`	`/api/admin/feedback/stats`
Admin	`PATCH`	`/api/admin/feedback/{feedback_id}`
Admin	`POST`	`/api/admin/feedback/{feedback_id}/classify`
Admin	`GET`	`/api/admin/init-database`
Admin	`POST`	`/api/admin/init-database`
Admin	`POST`	`/api/admin/knowledge/create`
Admin	`GET`	`/api/admin/knowledge/learnings`
Admin	`POST`	`/api/admin/knowledge/sync`
Admin	`GET`	`/api/admin/marketing/content-types`
Admin	`POST`	`/api/admin/marketing/generate`
Admin	`POST`	`/api/admin/marketing/trigger`
Admin	`GET`	`/api/admin/marketing/version`
Admin	`POST`	`/api/admin/merge-companies`
Admin	`POST`	`/api/admin/refresh-views`
Admin	`DELETE`	`/api/admin/review/{review_id}`
Admin	`POST`	`/api/admin/run-absa`
Admin	`GET`	`/api/admin/telemetry/events`
Agent Tools	`POST`	`/api/agent/get-trust-score`
Agent Tools	`GET`	`/api/agent/health`
Agent Tools	`POST`	`/api/agent/list-companies`
Agent Tools	`POST`	`/api/agent/search-company`
Alerts	`GET`	`/api/alerts/health`
Alerts	`POST`	`/api/alerts/subscribe`
Alerts	`GET`	`/api/alerts/subscriptions`
Alerts	`POST`	`/api/alerts/test`
Alerts	`POST`	`/api/alerts/unsubscribe`
Alerts	`DELETE`	`/api/alerts/watchlist`
Alerts	`GET`	`/api/alerts/watchlist`
Alerts	`PATCH`	`/api/alerts/watchlist`
Alerts	`POST`	`/api/alerts/watchlist`
Analytics	`POST`	`/api/analyze/{company_slug}`
Analytics	`GET`	`/api/aspects`
Analytics	`GET`	`/api/companies`
Analytics	`GET`	`/api/market-pulse`
Analytics	`GET`	`/api/rating-distribution`
Analytics	`GET`	`/api/reviews`
Analytics	`GET`	`/api/sentiment-distribution`
Analytics	`GET`	`/api/stats`
Analytics	`GET`	`/api/vacancies`
Corporate	`POST`	`/api/analytics/analyze/{company_slug}`
Corporate	`GET`	`/api/corporate/overview`
Corporate	`GET`	`/api/corporate/trust-score-details/{company_name}`
Corporate	`GET`	`/api/corporate/vacancy-intelligence/{company_slug}`
Corporate	`GET`	`/api/employer/{company_name}/trust-score`
Corporate	`GET`	`/api/glassdoor/{company_name}`
Corporate	`GET`	`/api/google-reviews/{company_name}`
Corporate	`GET`	`/api/search/companies`
Corporate	`GET`	`/api/search/smart`
Corporate	`GET`	`/api/timeline`
Crypto	`GET`	`/api/crypto/chart/{slug}`
Crypto	`GET`	`/api/crypto/health`
Crypto	`GET`	`/api/crypto/live/{slug}`
Crypto	`GET`	`/api/crypto/project/{slug}`
Crypto	`POST`	`/api/crypto/refresh/{slug}`
Crypto	`GET`	`/api/crypto/report/{slug}`
Crypto	`GET`	`/api/crypto/search`
Crypto	`GET`	`/api/crypto/top`
Crypto	`GET`	`/api/crypto/whales/alerts`
Farcaster	`GET`	`/.well-known/farcaster.json`
Farcaster	`GET`	`/api/farcaster/contract/{address}`
Farcaster	`POST`	`/api/farcaster/events`
Farcaster	`GET`	`/api/farcaster/frame`
Farcaster	`POST`	`/api/farcaster/frame/check`
Forensic	`POST`	`/api/forensic/check_wallet`
Forensic	`POST`	`/api/forensic/contract_info`
Forensic	`GET`	`/api/forensic/health`
Forensic	`POST`	`/api/forensic/token_holders`
Forensic	`POST`	`/api/forensic/transaction_history`
Legacy Compatibility	`GET`	`/api/v2/crypto/health`
Other	`GET`	`/api/runtime/metadata`
Other	`POST`	`/api/telemetry/events`
Public API v1	`GET`	`/api/v1/crypto/{slug}`
Public API v1	`GET`	`/api/v1/health`
Public API v1	`GET`	`/api/v1/search`
Public API v1	`GET`	`/api/v1/trust-score/{company}`
Reports	`GET`	`/api/reports/download/{company_name}`
Reports	`GET`	`/api/reports/{company_name}`
Scraping	`POST`	`/api/scraping/find-slug`
Scraping	`GET`	`/api/scraping/jobs`
Scraping	`GET`	`/api/scraping/jobs/active`
Scraping	`GET`	`/api/scraping/jobs/{job_id}`
Scraping	`POST`	`/api/scraping/jobs/{job_id}/cancel`
Scraping	`POST`	`/api/scraping/jobs/{job_id}/pause`
Scraping	`POST`	`/api/scraping/jobs/{job_id}/resume`
Scraping	`POST`	`/api/scraping/magic-search`
Scraping	`GET`	`/api/scraping/progress/{company_slug}`
Scraping	`POST`	`/api/scraping/start`
Scraping	`GET`	`/api/scraping/stats`
Scraping	`POST`	`/api/scraping/trigger-worker`
System	`GET`	`/health`

Notes

This block is generated by scripts/sync_api_endpoints_doc.py.
Alert endpoints may be loaded via fallback parsing when optional runtime dependencies are missing locally.
Public API v1 endpoints may be loaded via fallback parsing when rate-limiter dependencies are unavailable.
Crypto endpoints may be loaded via fallback parsing when crypto router runtime deps are unavailable.
For request/response schemas, use live OpenAPI at /docs and /openapi.json.

Authentication​

Company Endpoints​

Search Companies​

Get Company Details​

Smart Search​

AI Chat Endpoints​

Chat with AI​

Health Check​

Public API Endpoints​

Public Company Trust Score​

Public Crypto Trust Score​

Public Unified Search​

Agent Tool Endpoints​

Search Company​

Get Trust Score​

List Companies​

Compare Companies​

Run Analysis​

Get Company Reviews​

Scraping Endpoints​

Magic Search​

Get Job Status​

List All Jobs​

List Active Jobs​

Job Control​

Trigger Worker (Protected)​

Analytics Endpoints​

Get Company Stats​

Sentiment Distribution​

Rating Distribution​

Get Reviews​

Get Aspects (ABSA)​

Get Vacancies​

Timeline​

Reports Endpoints​

Generate Report​

Get Report​

Download PDF Report​

Crypto Endpoints​

Search Crypto Projects​

Get Crypto Project​

Error Responses​

Protected Write Endpoints (Internal/Admin)​

Forensic Agent Endpoints​

Check Wallet Balance​

Get Transaction History​

Get Token Holders​

Get Contract Info​

Health Check​

Live Endpoint Inventory (Auto-generated)​

Notes​

Authentication

Company Endpoints

Search Companies

Get Company Details

Smart Search

AI Chat Endpoints

Chat with AI

Health Check

Public API Endpoints

Public Company Trust Score

Public Crypto Trust Score

Public Unified Search

Agent Tool Endpoints

Search Company

Get Trust Score

List Companies

Compare Companies

Run Analysis

Get Company Reviews

Scraping Endpoints

Magic Search

Get Job Status

List All Jobs

List Active Jobs

Job Control

Trigger Worker (Protected)

Analytics Endpoints

Get Company Stats

Sentiment Distribution

Rating Distribution

Get Reviews

Get Aspects (ABSA)

Get Vacancies

Timeline

Reports Endpoints

Generate Report

Get Report

Download PDF Report

Crypto Endpoints

Search Crypto Projects

Get Crypto Project

Error Responses

Protected Write Endpoints (Internal/Admin)

Forensic Agent Endpoints

Check Wallet Balance

Get Transaction History

Get Token Holders

Get Contract Info

Health Check

Live Endpoint Inventory (Auto-generated)

Notes