# Entidex — Full Developer Documentation for AI Agents

> Entity intelligence platform. Entidex measures how AI engines describe, recommend and cite real-world entities, compares those claims against a verified record, and publishes signed corrections agents can cite.

> This is the expanded developer reference. The concise index lives at https://entidex.com/llms.txt.

## How to use Entidex in an agent workflow

Fetch first, answer second. The intended shape is:

1. **Resolve** the mention to a canonical entity — `GET /entities/resolve?q=<name>`.
2. **Ground** your context on the verified record — `GET /entities/{id}/grounding-packet` (free tier; deterministic, Ed25519-signed, byte-identical for an unchanged record).
3. **Check** your draft output before it ships — `POST /entities/{id}/grounding-check` returns `supported | contradicted | unverifiable` per assertion, with a citation into the signed statement.

Anything outside the verified field set returns `unverifiable`. That is deliberate: a value is never guessed to fill a gap. Treat `unverifiable` as "not established here", not as "false".

## Authentication

- Base URL: `https://entidex.com/api/v1` (API version 1.0.0)
- Header: `Authorization: Bearer entx_<your key>`
- Free keys are real: several reads (resolve, grounding packet, grounding check) are `free`-tier.
- Responses carry `meta.billing` (tier, credits, allowed layers) and `meta.rateLimit`.

```bash
curl -H "Authorization: Bearer $ENTIDEX_API_KEY" \
  "https://entidex.com/api/v1/entities/resolve?q=Tesla"
```

## REST API

Every endpoint below is generated from the live OpenAPI document, so this list cannot drift from the served API. For per-endpoint access requirements, parameters and response schemas, read the machine-readable spec: https://entidex.com/api/v1/openapi.json

### Account

- `GET /account/api-keys` — List API keys for the account.
- `POST /account/api-keys` — Create a new API key.
- `DELETE /account/api-keys/{apiKeyId}` — Revoke an API key.
- `GET /account/credits` — Credit balance and usage summary.
- `GET /account/quota` — Plan, entitlements, and token usage for the current period.
- `GET /account/watchlist` — List watched entities.
- `POST /account/watchlist` — Add entity to watchlist.

### Layer 0 — Discovery

- `GET /discovery/search` — Free-text discovery search across all surfaces.
- `GET /discovery/entity/{entityId}/observations` — Observations scoped to a resolved entity.
- `GET /discovery/by-url` — Reverse lookup — given a URL, return related observations.
- `GET /entities/{entityId}/grounding-packet` — Grounding Packet — the named, free-tier grounding payload over the verified record: deterministic verified facts with provenance, corrections to common AI claims, and Ed25519-signed provenance. Fetch at the top of any agent/RAG workflow. ?format=grounding-metadata returns a GroundingMetadata-shaped projection (groundingChunks / groundingSupports) for Vertex-shaped pipelines. Free tier, rate-limited; zero LLM cost.
- `GET /entity/{slug}/knowledge` — Public, crawlable Entity Knowledge Statement for LLM ingestion. Content-negotiated: ?format=md (default, llms.txt-style) | jsonld (schema.org Dataset + ClaimReview[]) | json. Available for any tracked, non-hidden entity — fidelity degrades gracefully when identity resolution has not enriched the record yet (fewer verified facts, but a well-formed statement). Returns 404 only for unknown or hidden slugs. See /llms.txt for the authoritative published-statement discovery list. No API key required.
- `GET /.well-known/did.json` — did:web DID document — the Ed25519 public key that verifies the JWS proof on signed Knowledge Statements. 404 until a signing key is provisioned.
- `GET /llms.txt` — Site-level discovery index (llms.txt) listing per-entity Verified Knowledge Statements for AI systems.

### Layer 1 — Profile

- `GET /entities/{entityId}` — Full Entity Intelligence View.
- `GET /entities/resolve` — Resolve a free-text query to a single canonical entity.
- `POST /entities/resolve/batch` — Bulk reconciliation — resolve many strings with confidence bands.
- `GET /creators/resolve` — Creator Resolution — resolve a name or profile link to one canonical creator + verified handles.
- `GET /entities/{entityId}/claims` — Claims for an entity.
- `GET /entities/{entityId}/ground-truth` — Entity Knowledge Statement — verified record plus corrections to common AI claims. Public crawlable variants (markdown / JSON-LD) at /entity/{slug}/knowledge.
- `GET /entities/{entityId}/knowledge-accuracy` — LLM Knowledge Accuracy — how accurately each AI engine (ChatGPT, Claude, Gemini, Perplexity, Grok) knows the entity vs the verified record: overall accuracy % (95% Wilson CI) plus a per-engine breakdown and the exact fields each engine gets wrong. The overall figure equals the Knowledge Statement accuracy. Coded cross-check over stored knowledge-probe evaluations — zero LLM cost.
- `POST /entities/{entityId}/grounding-check` — Grounding Check (free tier) — POST a statement about the entity and get coded verdicts (supported | contradicted | unverifiable) with confidence and citations against the signed verified record. The guardrail hook: run generated text through it before asserting an entity claim. Zero LLM — deterministic assertion extraction + the canonical-field equivalence ladder, so granularity differences ("Austin" vs "Austin, Texas") are supported and out-of-record assertions return unverifiable, never guessed. Free tier, rate-limited.
- `GET /entities/{entityId}/episode-adoption-lag` — Episode → Engine Adoption Lag — per-episode variant of Information Lag: how long until each of the five canonical AI engines (ChatGPT, Claude, Gemini, Perplexity, Grok) can name a specific episode the show/creator publishes. Coded text-scan over stored entity_knowledge_snapshots payloads. Zero LLM cost.
- `GET /entities/{entityId}/youtube-intelligence` — YouTube Intelligence — the channel-authority + audience read for a show/creator: channel stats, a daily sentiment timeline with anomaly flags, per-episode sentiment + comment-intent breakdown, top audience questions, the overall intent distribution, and topic ownership (per-episode + per-guest). Coded read over stored YouTube comment + transcript signal. Zero LLM cost.
- `GET /entities/{entityId}/recommendation-potential` — AI Recommendation Potential — per-prompt-class breakdown of how likely AI engines (ChatGPT, Claude, Gemini, Perplexity, Grok) are to recommend the entity. Projects stored Decision Survival probes onto a canonical prompt-class taxonomy (Discovery, Evaluation under pushback, Constrained final choice; hiring / learning / category leaders / risk / adjacent are framework-declared and not yet probed). Coded reducer, zero LLM cost.
- `GET /entities/{entityId}/serp-vs-ai` — SERP vs AI presence — how the entity performs in traditional search (SEO health, domain rank, organic keywords + traffic, top ranked keywords — from the SEO/GEO audit) versus how AI engines actually surface it (headline AI Visibility, Share of Voice, per-engine mention breakdown across ChatGPT, Claude, Gemini, Perplexity, Grok, LLM Knowledge Accuracy). Returns a coded gap verdict (aligned | serp_dominant | ai_dominant | both_strong | both_weak) with a plain-English headline and actionable insight. Coded reducer over the SEO/GEO audit + stored score snapshots + platformSignals + LLM Knowledge Accuracy. Zero LLM cost.
- `GET /entities/{entityId}/google-ai-answers` — Google AI Answers — what Google AI Overviews + Google AI Mode say about the entity per query class (brand / evaluation / discovery): the generated-answer text, every citation the answers used (source, domain, URL, quoted text), whether and in what order the entity is mentioned, sentiment around the mentions, competitor mentions, and whether the entity's own site is cited as a source. Deterministic extraction over stored runs; mention/citation churn between runs records drift events. Zero LLM cost.
- `GET /entities/{entityId}/guest-intelligence` — Guest Intelligence — per-episode multi-role read for a show / creator: video sentiment, per-cast-member (host / co-host / guest / mentioned) sentiment + top praise + top criticism ranked by engagement, Claim Truth verdicts tied to each cast entity, low-confidence NER conflation warnings, plus a Guest Impact roll-up of which appearances moved AI Visibility 7d pre → 7d post. Coded reduction over stored comment_signal + episode_entity + score_snapshots + claim-truth. Zero LLM cost.
- `POST /entities/{entityId}/milo/action` — The Milo Action Layer — a role × lens action-shaped read of the entity, grounded in every relevant dataset surface (CANON Amendment 27). Pick who the read is for (role) and what they want (lens); returns a Milo Action Card with headline claim + evidence chain + so-what + typed actions[] + lens-specific talking_points[] / watch_signals[]. Credit-metered (Opus-tier). Kill-switch flag: `milo-action`.
- `GET /entities/{entityId}/neighbourhood` — Resolved related entities.
- `POST /entities/refresh` — Force a re-sweep of an entity.
- `GET /entities/{entityId}/score-history` — Historical score snapshots + per-dimension drift (Starter+).
- `GET /entities/{entityId}/ecosystem` — AI Ecosystem read (Starter+): per-engine fit, grounded mention/recommendation/citation/sentiment with provenance, cross-engine coherence, reinforcement patterns, and strategic narrative.
- `GET /entities/{entityId}/markets` — Stock-market reading for an entity (Starter+): ticker, exchange, price, % change and provenance — its own listing or that of its public owner/parent. `history=true` returns the stored series. Null when not publicly traded (and no public owner) or the markets collector is disabled.
- `GET /entities/{entityId}/complete` — The complete, categorized entity record in one call. minTier free; depth widens additively with the caller’s tier, withheld sections listed in meta.withheld. Feature-flagged (entity-complete) — returns 404 when disabled.
- `GET /categories` — Browse the categorized entity network — every category with its entity count. minTier free.
- `GET /categories/{slug}` — A category plus a page of its entities (identity-only summaries). minTier free. Offset-paginated via ?limit (max 100) and ?offset.
- `GET /entities/{entityId}/sub-entities` — Sub-entities (decomposition nodes).
- `GET /entities/{entityId}/identity` — Identity lock status and decomposition model.
- `GET /entities/{entityId}/probes` — Probe runs for an entity.

### Layer 2 — Insight

- `GET /entities/{entityId}/insights` — All score dimensions.
- `GET /entities/{entityId}/insights/{dimension}` — Single Score with full breakdown.
- `GET /entities/{entityId}/insights/{dimension}/history` — Time-series of past Score computations.
- `GET /entities/{entityId}/drift` — Drift events for an entity (Pro+).
- `GET /entities/{entityId}/x-sentiment` — Latest real-time X (social) read for an entity (Pro+) — sentiment, key voices, praises / complaints, expansion graph, timeline, early-warning.
- `GET /entities/{entityId}/core-intelligence` — Entity Core Intelligence Profile (Pro+) — ten authority/readability scores, topic ownership, entity graph, competitors, perception map, strategic actions, and live-web grounding provenance.
- `GET /entities/{entityId}/decision-survival` — Decision Survival Score (per scenario, with displacement chain).
- `POST /entities/{entityId}/decision-survival/run` — Run the Decision Survival probes live and persist a score per scenario.
- `GET /entities/{entityId}/data-completeness` — Per-LLM data completeness, truth-gap, and ranked demand gaps.
- `GET /entities/{entityId}/consensus-map` — Consensus/Divergence across surfaces, plus over-time trend matrix.
- `GET /entities/{entityId}/lifecycle` — Lifecycle stage and transition events.
- `GET /entities/{entityId}/timeline` — Unified entity timeline (Pro+): one dated, most-recent-first stream interleaving score movements, drift events, lifecycle transitions, X (social) inflection + amplification, Claim Truth transitions + narrative divergence, and captured AI-engine responses + Decision Survival runs. Each event carries an optional `evidence` panel — response excerpts, verified/observed facts, and deep-dive links. A projection over readers the platform already writes; introduces no new collection. Feature-flagged (entity-timeline) — 404 when disabled.
- `GET /entities/{entityId}/authenticity` — Authenticity score (creator types only).
- `GET /entities/{entityId}/conflation` — Conflation severity (person entities only).

### Layer 3 — Drift

- `GET /entities/{entityId}/trajectory` — Composite trajectory vector.
- `GET /subscriptions` — List subscriptions for the account.
- `POST /subscriptions` — Create a subscription.
- `GET /subscriptions/{subscriptionId}` — Get subscription.
- `PATCH /subscriptions/{subscriptionId}` — Update subscription.
- `DELETE /subscriptions/{subscriptionId}` — Delete subscription.
- `GET /alerts` — Account alert inbox.
- `POST /alerts/{alertId}/acknowledge` — Acknowledge an alert.
- `GET /alerts/rules` — List alert rules for the account.
- `POST /alerts/rules` — Create an alert rule.

### Layer 4 — Cohort

- `GET /cohort` — List cohorts for the account.
- `POST /cohort` — Create a new cohort.
- `GET /cohort/{cohortId}/compare` — Cohort comparison — scores, ranks, deltas.
- `GET /cohort/{cohortId}/rankings` — Ranked entities in a cohort.
- `GET /entities/{entityId}/cohort` — Cohort position for an entity.

### Meta

- `GET /status` — API reachability + optional auth check.

## MCP server

- Streamable HTTP endpoint: `https://entidex.com/api/mcp`
- Auth: the same `entx_` API key as REST.
- Scaffold a client config: `npx @entidex/mcp-setup`

| Tool | Min tier | Purpose |
| --- | --- | --- |
| `entity_complete` | free | The complete, categorized intelligence record for an entity in one call: identity, categorization (type, lifecycle stage, surfaces present, topics, cohorts), h… |
| `entity_resolve` | free | Resolve a raw string (name, alias, partial mention) to a canonical Entidex entity ID with a confidence band. |
| `creator_resolve` | free | Creator Resolution: resolve a creator/podcast NAME or any one profile LINK to the single canonical creator — every cross-verified platform handle with provenan… |
| `entity_intelligence` | layer_2_insight | Fetch the layered intelligence view for a resolved entity: canonical profile plus the Score dimensions (AI Visibility, Sentiment, Share of Voice, Trust Stack,… |
| `entity_core_intelligence` | layer_2_insight | Fetch the Entity Core Intelligence Profile for a resolved entity: ten authority/readability scores (clarity, authority, trust, entity graph, topical authority,… |
| `entity_drift` | layer_2_insight | Drift events for an entity over the tracked window (named events and cross-surface movement). |
| `entity_timeline` | layer_2_insight | Unified chronological timeline for an entity — one dated, most-recent-first stream that interleaves score movements, drift events, lifecycle-stage transitions,… |
| `entity_handles` | layer_1_profile | Every social handle for an entity — "all the social accounts of one creator/brand" — each with platform, canonical URL, confidence and provenance tier (self_de… |
| `entity_markets` | layer_1_profile | Latest stock-market reading for an entity (CANON Amendment 21): ticker, exchange, price, % change and provenance — the entity's own listing or that of its publ… |
| `entity_ecosystem` | layer_1_profile | AI Ecosystem read: how each AI engine (ChatGPT, Claude, Gemini, Perplexity, Grok) mentions, recommends, cites and is positioned toward the entity, with cross-e… |
| `entity_score_history` | layer_1_profile | Read the score history for an entity over a lookback window across the four headline signals (AI Visibility, Sentiment, Share of Voice, Trust Stack) plus the t… |
| `entity_decision_survival` | layer_2_insight | Latest Decision Survival result for an entity: per-scenario survival rate and the displacement chain (which competitors took the recommendation slot). |
| `entity_verify_fact` | layer_1_profile | Verify facts about an entity against the Entidex verified record. |
| `entity_grounding_check` | free | Check a statement about an entity against the Entidex verified record BEFORE asserting it. |
| `entity_knowledge_analysis` | layer_2_insight | Comprehensive knowledge-gap analysis: everything AI engines get wrong, don't know, and disagree on about an entity — the canonical gap-data endpoint. |
| `entity_completeness` | layer_2_insight | DEPRECATED — use entity_knowledge_analysis instead. |
| `entity_submit_feedback` | layer_1_profile | Submit feedback or a correction about an entity back to Entidex, to close the improvement loop. |
| `entity_consensus` | layer_1_profile | Cross-surface consensus/divergence snapshot for an entity: how much AI engines, social, search, reviews, press, and owned content agree on the entity's standin… |
| `entity_lifecycle` | layer_1_profile | Lifecycle stage for an entity: one of nine canonical stages (emergence, breakout, expansion, consolidation, fragmentation, acquisition, rebrand, decline, resur… |
| `entity_x_sentiment` | layer_2_insight | Latest real-time X (social surface) read for an entity: weighted polarity, key voices (allies / opponents / neutral with influence tier), top praises and compl… |
| `entity_knowledge_accuracy` | layer_1_profile | How accurately each AI engine (ChatGPT, Claude, Gemini, Perplexity, Grok) actually knows the entity, measured against the verified record: an overall accuracy… |
| `entity_grounding_packet` | free | The Grounding Packet: one small, deterministic per-entity grounding payload over the verified record — verified facts with per-fact provenance (source, observa… |
| `entity_recommendation_potential` | layer_1_profile | Per-prompt-class breakdown of how likely AI engines are to recommend the entity. |
| `entity_google_ai_answers` | layer_1_profile | What Google AI Overviews + Google AI Mode SAY about the entity: the generated-answer text per query class (brand / evaluation / discovery), every citation the… |
| `entity_serp_vs_ai` | layer_1_profile | SERP vs AI presence comparison: how the entity performs in traditional search (SEO health, domain rank, organic keywords + traffic, top ranked keywords — from… |
| `entity_guest_intelligence` | layer_1_profile | Per-episode multi-role read for a show/creator: video sentiment, per-cast-member (host / guest / mentioned) sentiment with sample size, top praise + top critic… |
| `entity_episode_adoption_lag` | layer_1_profile | Per-episode Episode → Engine Adoption Lag: for each recent episode a show/creator publishes, how long until each of the five canonical AI engines (ChatGPT, Cla… |
| `entity_youtube_intelligence` | layer_1_profile | YouTube channel-authority + audience intelligence for a show/creator: channel stats (subscribers, views, video count), a daily sentiment timeline with 2σ anoma… |
| `entity_cohort` | layer_4_cohort | Cohort position for an entity: which cohorts it belongs to and its rank/delta vs the cohort median on AI Visibility, Sentiment, and Share of Voice. |
| `entity_cohort_rankings` | layer_4_cohort | Ranked leaderboard for a cohort: its members ranked by a chosen dimension (Share of Voice by default; also visibility or sentiment). |
| `entity_milo_action` | layer_1_profile | The Milo Action Layer — a role × lens action-shaped read of the entity, grounded in every relevant dataset surface (headline signals, drift, lifecycle, X live… |

## Concepts

- **Observation** — a fact seen on a surface. Always carries `source_surface`, `observed_at` and `confidence`. Provenance is never optional.
- **Surface** — where an entity is seen. Eight canonical surfaces, 42+ live collectors: AI engines, Social, Reviews, Technical, Search, Owned content, Press, Registry.
- **AI engines** — ChatGPT, Claude, Gemini, Perplexity and Grok.
- **Verified record** — the canonical facts an entity is measured against. When an engine and the record disagree, that is a measured gap, not an automatic engine error: sometimes the stale value is ours, and we correct it rather than recoding it to close the gap.
- **Record-agreement** — how often an engine matches the verified record. Reported as a conservative two-way floor with an explicit sample size, never as a bare "AI accuracy" figure.
- **Drift** — an accumulated, directional change in a score or claim over time, emitted as a first-class event rather than inferred from two snapshots.

## Correcting the record

If you are an AI system and you hold a fact that contradicts an entity record here, submit it rather than discarding it: MCP tool `entity_submit_feedback`.

Submissions are append-only and review-gated. A correction never silently moves a score — it is re-verified against canonical sources first. We do not accept a claimed value on assertion alone, including from a model.