API & embed

In one sentence

Personal use of the Trust Index (extension + website) is free; organisations pay for Spaces; developers and companies pay for API and embedding.

Open pricing →

Endpoints

Base URL: your GriGsi server (e.g. https://your-domain.com). No auth required for read and vote; optional X-Api-Key for higher limits.

Single trust response (200)

{
  "hash": "a1b2c3...1",
  "plus1": 120,
  "minus1": 5,
  "weighted_score": 112.5,
  "tier": 2,
  "totalVotes": 125
}

With ?details=1 you also get: tierLabel, trustPercent, uniqueVisits, countries, spanHours, flagged, flagReason.

Hash format: SHA-256("<type>:<normalized_value>") first 32 hex chars + one digit (1=domain, 2=email, 3=phone, 4=iban, 5=string, 6=info_index). Example: domain:example.com → hash ending in 1. Normalize: domain = lowercase, no www/path; email = lowercase; phone = digits only.

Trust Check API

Runtime endpoints used by the Trust Check UI (hash/check/vote + interest signals).

Example: trust check

POST /api/trust-check
Content-Type: application/json

{ "hash": "6c57ebfc23cdad8e0ae18249defc8d285", "clientId": "opaque-id", "display": "example.com" }

→ { "hash": "...", "score": 0, "tier": 1, "trust": 0, "warn": 0 }

Source/claim workflows are UI-level features; this public runtime API focuses on trust hash checks and voting primitives.

Labour Coverage Index (LCI) API

Anonymous price observations and public index snapshots for the Labour Coverage Index. Same origin as your GriGsi server (e.g. dashboard for a web submit form). Canonical data-source definitions: GET /api/lci/registry/public (shared infrastructure for future Open Data Hub).

Crowd signal contract (POST /api/lci/signals)

Content-Type: application/json. Prices are converted server-side to EUR for aggregation when FX rates are available.

Example: submit signal

POST /api/lci/signals
Content-Type: application/json

{
  "schema_version": 1,
  "region_cell": "u05p88m",
  "category": "food_beverages",
  "product_label": "Milk 3.6% 1L store brand",
  "price": 2.49,
  "currency": "EUR",
  "barcode": "5901234123457",
  "country_iso": "BG",
  "monthly_net_income": 1800,
  "income_currency": "EUR",
  "timestamp": 1700000000000
}

→ { "ok": true, "id": 42, "received_at": 1700000000123, "price_eur": 2.49, "income_eur_monthly": 1800 }

Omit monthly_net_income if you do not want to send income; the response then has no income_eur_monthly field.

Errors

• 400 — invalid JSON or validation ({ "ok": false, "error": "…" }).
• 422 — EUR conversion unavailable (FX not ingested yet or unsupported currency).
• 429 — rate limit (rate_limited).

Pipeline

Signals persist in lci_signals. The scheduled LCI job runs ingest + aggregation (~6h by default). Regional lci_core / confidence use crowd data when density allows; global v0.1 snapshot remains a macro-only summary — check components_json / methodology notes on /api/lci/global.

Validation: from server/ run npm run test:lci (includes signal contract tests and an isolated end-to-end persist → aggregate → history check). Demo seed: npm run seed:lci:crowd (dry run); apply with GRIGSI_SEED_LCI_CONFIRM=1 node lci/seed-crowd-signals.cjs --apply.

Personal check contract (GET /api/lci/personal)

Computes a financial ease score (0–100, higher = more comfortable cushion after expenses) for a region_cell from your income and optional total expense. Regional lci_core slightly lowers ease when living costs are structurally high. When expense is omitted, the server uses an API-derived baseline from macro inputs. Optional country_iso (ISO 3166-1 alpha-2) selects World Bank macro series when there is no regional LCI snapshot yet for that geohash.

Monthly Breathing Room answers: “How much monthly flexibility do you have?”

Labour Coverage Index (labour_cost_of_life.lci, short LCI) — single headline derived from currency real value (CRV), labour conversion (LCR), and human necessity coverage (HNC); see docs/LCI-LABOUR-INDEX-PHASE1.md. GRV remains in the response for legacy clients.

Macro period (Phase 5): macro_year / macro_month align LCI Eurostat inputs with a calendar moment; re-run ingest so snapshots include an observations tail (HICP uses the last 96 periods by default). Breathing room and GRV still use the latest regional snapshot.

Labour Coverage Index — data gaps & overrides: labour_cost_of_life may include data_gaps (EN/BG messages) and user_value_hints when a HICP slice or HPI YoY is missing or the requested period is not in the stored series (server may fall back to latest). Optional query parameters let you supply official annual % YoY values: lci_override_CP00, lci_override_CP01, lci_override_CP03, lci_override_CP06, lci_override_CP07, lci_override_CP10, lci_override_CP041, lci_override_CP045, lci_override_hpi, lci_override_lending (World Bank–style domestic lending % for the transparency row). See docs/LCI-LABOUR-INDEX-PHASE1.md §9.

GriGsi Real Value Index (GRV) answers: “How strong is that flexibility in current real economic conditions?” It is part of an economic reality mapping engine for consumer purchasing power. Canonical driver IDs and labels: server/lci/grv-driver-ids.js (docs under docs/LCI-*.md are explanatory, not a second registry).

GET /api/lci/personal?region_cell=u05p88m&monthly_net_income=2500&income_currency=EUR&country_iso=BG

→ {
  "ok": true,
  "region_cell": "u05p88m",
  "country_iso": "BG",
  "lci_core": 67.8,
  "monthly": {
    "income_eur_monthly": 2500,
    "expense_eur_monthly": 1398.24,
    "expense_source": "api_baseline",
    "residual_eur_monthly": 1101.76
  },
  "personal_financial_ease_score": 74.5,
  "personal_financial_ease_label": "Manageable",
  "personal_stress_score": 74.5,
  "personal_stress_label": "Manageable"
}

personal_stress_* duplicates ease for backwards compatibility; prefer personal_financial_ease_*.

GRV contract: response includes grv (baseline 100) with score, label, interpretation, and a required drivers breakdown aligned with the five locked drivers (Cost of Living, Housing, Monetary, Utility & Energy, Tax & Policy Pressure — see grv_subcomponent_catalog). If market data is missing, market contribution is neutral (0). Drivers are directional estimates, not exact decomposed contributions.

Similarity API

The Similarity engine detects lookalike domains and emails (homograph/typosquat). It is used in the extension to warn when a visited domain or email is similar to one you already trust.

Current use: Logic runs in the extension (client-side). A list of your trusted domains/emails is compared locally with the current URL or email; similarity is computed on normalized labels (skeleton/NFKC) with thresholds (e.g. ≥90% almost identical, 80–89% suspicious).

API: A server-side Similarity API (e.g. GET /api/similarity/domains?domain=example.com or POST /api/similarity/check with a list of hashes) can be offered for embedding in your app — same rate limits as Trust API. Contact us for access or when it becomes available.

Rate limits

For production embedding or high traffic, use an API plan or call from your backend (server-to-server) to avoid browser CORS and rate limits.

Trust badge (embed)

Show your domain’s trust score on your site. Add a container and load the script (same origin as the GriGsi server, or use your backend to proxy the request).

1. HTML

<div id="grigsi-trust-badge" data-grigsi-domain="example.com"></div>
<script src="https://YOUR-GRIGSI-DOMAIN/js/trust-badge.js"></script>

Use data-grigsi-domain (e.g. example.com) or data-grigsi-base to point to another GriGsi server URL if needed.

2. Demo on this site

Free badge: links to GriGsi. Paid/white-label options: see Pricing.

CORS

For cross-origin requests from a browser (e.g. your site on another domain), the server may need to allow your origin. Alternatively, call the API from your backend and serve the result to your frontend — no CORS needed.

Trust Index Pricing Check trust