ENFAVORI AI DATA GATEWAY

Developer Documentation

Public, read-only access to EnFavori preference rankings, permanent entities, history, graph relations and provenance evidence.

Discovery

API base: https://ai.enfavori.com/v1
OpenAPI 3.1: https://ai.enfavori.com/v1/openapi.json
Well-known service document: https://ai.enfavori.com/.well-known/enfavori-ai.json

Core endpoints

GET/v1/catalog

Discover published EnFavori ranking resources.

GET/v1/lists/{slug-or-list-uid}

Read current ranking, history, graph and provenance.

GET/v1/entities/{entity-uid}

Resolve a public permanent EnFavori entity.

GET/v1/changes?since={iso8601}

Consume immutable ranking snapshot changes.

Data semantics

Ranking: net score descending; net score = positive votes − negative votes.
Ties: positive votes descending, negative votes ascending, then placement ID ascending.
Votes: preference interactions, not star ratings.
Unique voters: intentionally null until reliably measured.
Evidence: SHA-256 digests can verify immutable ranking snapshots.

HTTP behavior

Responses are UTF-8 JSON, CORS-enabled, cacheable where appropriate and support ETag revalidation. Published visibility follows the same public-list rules as EnFavori.com. No write operation is exposed in V1.

Example

GET https://ai.enfavori.com/v1/catalog?per_page=20
Accept: application/json

Production readiness

The gateway exposes live dependency, freshness and contract health without exposing infrastructure secrets.

GET/v1/status

Read gateway status

GET/robots.txt

Read crawler policy

AI Business Passport

Resolve a supported public permanent entity into a machine-readable identity, profile, graph, ranking evidence, history, freshness, dedicated verification state and public action document.

GET/v1/passports/{entity-uid}

Read one public Business Passport.

Trust boundary: Passport existence does not mean the entity is verified. verified_business=true is emitted only from a separate current entity verification record. Publisher, sponsorship or payment state cannot create verification and cannot alter organic EnFavori ranking. Profile completeness measures factual field coverage only; it is not an AI visibility score.

Action Layer

Resolve a public entity into canonical action targets such as Call, WhatsApp, Website, Get Quote, Reservation, Buy, Affiliate and Hotel Booking when first-party data supports them.

GET/v1/actions/{entity-uid}

Read one canonical Action Layer document.

TOOLget_actions

Available through Agent Gateway and MCP.

Safety boundary: Actions require user confirmation and provide a signed attribution handoff. EnFavori does not autonomously execute purchases or bookings. Placement and price actions continue through the existing signed EnFavori redirect gateway when available. Actions never affect organic ranking.

Conversion Attribution

Action handoffs are attributed to their source surface (API, Agent Gateway, MCP, web or Passport) together with the permanent entity, action, provider and list placement when available.

EVENTaction_handoff

Intent/handoff evidence. This is not a sale, booking or completed lead.

EVENTconfirmed_conversion

Recorded only when independent provider or transaction evidence exists.

Privacy boundary: Attribution does not store IP addresses, email addresses, member identifiers or personal voter identity. External transaction references are stored only as SHA-256 hashes when supplied. Attribution has no effect on organic ranking.

Model Context Protocol (MCP)

EnFavori exposes the Agent Gateway through a stateless MCP 2026-07-28 endpoint. MCP is an access protocol over the same public, read-only entity, ranking, evidence, trend, action and change logic; it is not a separate ranking system.

POST/mcp

MCP endpoint

RPCserver/discover · tools/list · tools/call

Modern stateless MCP methods.

Protocol: 2026-07-28. Tool calls are read-only. MCP action handoffs are attributed as mcp; a handoff is not treated as a confirmed conversion. Verification, sponsorship and payment cannot change organic EnFavori ranking.

Agent Gateway

Deterministic, public read-only tools over EnFavori permanent entities, rankings, evidence, history, actions and change data. The gateway does not run an LLM and does not expose personal voter data.

GET/v1/agent/tools

Discover agent tools

GET/v1/agent/search?q=...

Search public entities.

GET/v1/agent/actions/{uid}

Read safe user-confirmed action targets.

GET/v1/agent/rankings/{selector}

Read organic ranking facts.

GET/v1/agent/evidence/{selector}

Read provenance and methodology.

Trust boundary: agent access is read-only; action discovery never autonomously purchases or books; verification, sponsorship and payment cannot alter organic ranking. MCP is a protocol layer over these same tools.

Commercial API · EnFavori Insights

Authenticated clients can license aggregate Preference Intelligence derived from EnFavori historical ranking snapshots and Preference Graph segments.

GET/v1/commercial/insights/overview

Aggregate preference snapshot overview.

GET/v1/commercial/insights/momentum

Observed historical entity movement; not prediction.

GET/v1/commercial/insights/segments

Category or list-location aggregate segments.

GET/v1/commercial/insights/lists/{selector}

Historical list trend and item movement.

Authentication: Bearer Commercial API key with insights.read scope. Client credential storage keeps only a prefix and SHA-256 token hash. Per-minute limits and monthly quotas apply.

Trust boundary: No personal data or individual voter identity is exposed. Momentum is observed snapshot change, not an AI prediction or score. Commercial access never changes organic EnFavori ranking.