Skip to main content

Public API (v1)

Overview​

The Vartovii Public API provides programmatic access to Trust Intelligence scores for companies and crypto projects. Designed for external developers, integrations, and partners.

Base URL: https://api.vartovii.com/api/v1

Authentication & Rate Limits​

  • Free Tier: No key required. Limited to 10 requests/day per IP.
  • Pro Tier: Unlimited access (Contact sales for API key).
  • Successful rate-limited responses now include:
    • X-RateLimit-Limit
    • X-RateLimit-Policy
    • X-RateLimit-Window
    • X-RateLimit-Tier
  • Error responses use one canonical payload:
{
  "error": {
    "code": "company_not_found",
    "message": "Company 'google' not found",
    "status": 404
  },
  "api_version": "v1"
}

🏢 Corporate Intelligence​

Get Corporate Trust Score​

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

Retrieve the unified Trust Score for a company.

Parameters:

  • company: Company name or slug (e.g., google or Volkswagen).

Response:

{
  "company": "Google",
  "trust_score": 87.5,
  "risk_level": "LOW",
  "total_reviews": 1245,
  "avg_rating": 4.2,
  "last_updated": "2026-01-28T22:00:00Z",
  "data_freshness": "fresh",
  "api_version": "v1"
}

last_updated reflects the latest source review timestamp used for the matched company, not the time when the API request was processed.

🪙 Crypto Intelligence​

Get Project Trust Score​

GET /api/v1/crypto/{slug}

Retrieve the Trust Score for a crypto project/protocol.

Parameters:

  • slug: CoinGecko-style slug (e.g., bitcoin, ethereum, solana).

Response:

{
  "name": "Bitcoin",
  "symbol": "BTC",
  "slug": "bitcoin",
  "trust_score": 92.5,
  "risk_level": "LOW",
  "price_usd": 65000.0,
  "market_cap": 1200000000000,
  "commits_last_30d": 125,
  "active_devs": 42,
  "last_updated": "2026-01-28T22:00:00Z",
  "data_freshness": "recent"
}

🔎 Unified Search​

Search Entities​

GET /api/v1/search

Search across both Corporate and Crypto databases.

Parameters:

  • q: Search query (min 2 chars).
  • type: Filter by type (all, company, crypto). Default: all.
  • limit: Page size (1-25). Default: 5.
  • cursor: Opaque cursor returned by the previous page.
  • sort_by: trust_score, name, or last_updated. Default: trust_score.
  • sort_order: asc or desc. Default: desc.

Response:

{
  "query": "google",
  "count": 2,
  "results": [
    {
      "type": "company",
      "name": "Google",
      "trust_score": 87.5,
      "risk_level": "LOW",
      "last_updated": "2026-03-12T14:20:00+00:00",
      "data_freshness": "fresh"
    }
  ],
  "pagination": {
    "limit": 5,
    "next_cursor": null,
    "has_more": false,
    "sort_by": "trust_score",
    "sort_order": "desc"
  },
  "freshness": {
    "generated_at": "2026-03-15T09:00:00+00:00",
    "freshest_record_at": "2026-03-12T14:20:00+00:00",
    "stalest_record_at": "2026-03-08T11:10:00+00:00"
  }
}

next_cursor is opaque. Clients should treat it as a token and should not attempt to parse or construct it themselves.

Error Codes​

Current stable codes on the active /api/v1 surface:

  • invalid_cursor
  • company_not_found
  • project_not_found
  • rate_limit_exceeded
  • internal_service_error

SDK Examples​

Python​

import requests

BASE_URL = "https://api.vartovii.com/api/v1"


def get_company_score(company: str) -> dict:
    response = requests.get(f"{BASE_URL}/trust-score/{company}", timeout=15)
    response.raise_for_status()
    return response.json()


def search_entities(query: str, cursor: str | None = None) -> dict:
    params = {
        "q": query,
        "type": "all",
        "limit": 5,
        "sort_by": "trust_score",
        "sort_order": "desc",
    }
    if cursor:
        params["cursor"] = cursor

    response = requests.get(f"{BASE_URL}/search", params=params, timeout=15)
    response.raise_for_status()
    return response.json()


company = get_company_score("google")
search_page = search_entities("google")

print(company["trust_score"], company["data_freshness"])
print(search_page["pagination"]["next_cursor"])

JavaScript​

const BASE_URL = "https://api.vartovii.com/api/v1";

async function getCompanyScore(company) {
  const response = await fetch(
    `${BASE_URL}/trust-score/${encodeURIComponent(company)}`,
  );

  if (!response.ok) {
    throw new Error(`Public API request failed: ${response.status}`);
  }

  return response.json();
}

async function searchEntities(query, cursor = null) {
  const params = new URLSearchParams({
    q: query,
    type: "all",
    limit: "5",
    sort_by: "trust_score",
    sort_order: "desc",
  });

  if (cursor) {
    params.set("cursor", cursor);
  }

  const response = await fetch(`${BASE_URL}/search?${params.toString()}`);

  if (!response.ok) {
    throw new Error(`Public API request failed: ${response.status}`);
  }

  return response.json();
}

const company = await getCompanyScore("google");
const searchPage = await searchEntities("google");

console.log(company.trust_score, company.data_freshness);
console.log(searchPage.pagination.next_cursor);

🩺 System​

Health Check​

GET /api/v1/health

Check API operational status. Use this for monitoring. No rate limit.