{"openapi":"3.1.0","info":{"title":"Entidex API","version":"1.0.0","description":"Entidex public API. Six object shapes, four discovery layers, frozen v1 contract.","contact":{"name":"Entidex","url":"https://entidex.com"}},"servers":[{"url":"https://entidex.com/api/v1","description":"Production"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"entx_{env}_sk_*"}},"schemas":{"EntityComplete":{"type":"object","description":"The complete, categorized entity record assembled once and projected to every channel. Free callers receive a generous taste (entity, categorization, headline, coverage); higher tiers unlock the remaining sections additively. Withheld sections are listed in meta.withheld.","properties":{"entity":{"$ref":"#/components/schemas/Entity"},"categorization":{"type":"object","properties":{"category":{"type":"string","nullable":true},"primaryType":{"$ref":"#/components/schemas/EntityType"},"subtype":{"type":"string","nullable":true},"decompositionModel":{"type":"string","nullable":true,"enum":["commercial","person","organisation","mixed"]},"entityClass":{"type":"string","nullable":true},"lifecycleStage":{"type":"string","nullable":true},"surfacesPresent":{"type":"array","items":{"type":"string"}},"topics":{"type":"array","items":{"type":"string"}},"cohorts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}}}}},"headline":{"type":"object","properties":{"aiVisibility":{"type":"number","nullable":true},"sentiment":{"type":"number","nullable":true},"shareOfVoice":{"type":"number","nullable":true},"trustStack":{"type":"number","nullable":true}}},"coverage":{"type":"object","properties":{"totalObservations":{"type":"integer","description":"Discovery-layer observation rows in signals.observations (Reddit / press / SERP / owned-content / registry). Does NOT include AI-engine probes — see `aiEngineProbes`."},"aiEngineProbes":{"type":"integer","description":"AI-engine probe passes captured on entity.platformSignals (one per queried engine on the last pass). Additive with `totalObservations`."},"surfaces":{"type":"array","items":{"type":"object","properties":{"surface":{"type":"string"},"observationCount":{"type":"integer"},"lastObservedAt":{"type":"string","format":"date-time","nullable":true}}}}}},"scores":{"type":"array","items":{"$ref":"#/components/schemas/Score"}},"perception":{"type":"object","nullable":true,"properties":{"consensusScore":{"type":"number","nullable":true},"divergenceScore":{"type":"number","nullable":true},"surfaces":{"type":"array","items":{"type":"object","properties":{"surface":{"type":"string"},"label":{"type":"string"},"value":{"type":"number"},"sampleSize":{"type":"integer"}}}}}},"derivedInsights":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"value":{"type":"number","description":"0–100 scale."},"confidence":{"type":"number","description":"0–100 scale (NOT the 0–1 Score.confidence range)."},"contributingSources":{"type":"array","items":{"type":"string"}}}}},"lifecycle":{"type":"object","properties":{"stage":{"type":"string","nullable":true},"label":{"type":"string","nullable":true},"confidence":{"type":"number","nullable":true},"drivers":{"type":"array","items":{"type":"string"}},"predictedNext":{"type":"object","nullable":true,"properties":{"stage":{"type":"string"},"label":{"type":"string"},"confidence":{"type":"number"}}}}},"drift":{"type":"array","items":{"$ref":"#/components/schemas/DriftEvent"}},"relationships":{"type":"array","items":{"$ref":"#/components/schemas/NeighbourhoodEdge"}},"typedRelationships":{"type":"array","items":{"type":"object","properties":{"entityId":{"type":"string"},"name":{"type":"string"},"type":{"type":"string"},"label":{"type":"string"},"direction":{"type":"string","enum":["forward","inverse"]},"strength":{"type":"number","nullable":true},"confidence":{"type":"number"},"sourceSurface":{"type":"string","nullable":true},"observedAt":{"type":"string","format":"date-time"}}}},"ecosystem":{"type":"object","nullable":true,"properties":{"influenceScore":{"type":"number","nullable":true},"coherenceScore":{"type":"number","nullable":true},"engines":{"type":"array","items":{"type":"object","properties":{"engine":{"type":"string"},"label":{"type":"string"},"maker":{"type":"string","nullable":true},"fit":{"type":"number"},"mentionRate":{"type":"number","nullable":true},"recommendationRate":{"type":"number","nullable":true},"citationRate":{"type":"number","nullable":true},"sentiment":{"type":"string","nullable":true},"confidence":{"type":"number"},"lastObservedAt":{"type":"string","nullable":true}}}}}},"authenticity":{"type":"object","nullable":true,"properties":{"available":{"type":"boolean"},"reason":{"type":"string"},"entityClass":{"type":"string"},"score":{"type":"number"},"sampleSize":{"type":"integer"},"lastObservedAt":{"type":"string"}}},"truthGap":{"type":"array","items":{"type":"object","properties":{"aspect":{"type":"string"},"divergence":{"type":"number","description":"0–1 composite divergence."},"computedAt":{"type":"string"}}}},"selfCheck":{"type":"object","nullable":true,"properties":{"lastComputedAt":{"type":"string"},"schemaConformant":{"type":"boolean"},"perEngine":{"type":"array","items":{"type":"object","properties":{"engine":{"type":"string"},"completenessPct":{"type":"number","nullable":true},"truthGapPct":{"type":"number","nullable":true}}}},"topGaps":{"type":"array","items":{"type":"string"}}}},"youtubeIntelligence":{"type":"object","nullable":true,"description":"YouTube Intelligence summary — YouTubers/podcasts only (layer_1_profile, flag youtube-intelligence).","properties":{"channel":{"type":"object","nullable":true,"properties":{"subscriberCount":{"type":"integer","nullable":true},"totalViewCount":{"type":"integer","nullable":true},"videoCount":{"type":"integer","nullable":true},"fetchedAt":{"type":"string","nullable":true}}},"episodeCount":{"type":"integer"},"commentsAnalysed":{"type":"integer"},"topIntent":{"type":"string","nullable":true},"intentDistributionPct":{"type":"object","properties":{"praise":{"type":"number"},"question":{"type":"number"},"complaint":{"type":"number"},"suggestion":{"type":"number"},"neutral":{"type":"number"}}},"lastFetchedAt":{"type":"string","nullable":true}}},"subEntities":{"type":"object","properties":{"available":{"type":"boolean"},"requiresTier":{"type":"string"},"data":{"type":"object","nullable":true,"properties":{"count":{"type":"integer"}}}}},"decisionSurvival":{"type":"object","properties":{"available":{"type":"boolean"},"requiresTier":{"type":"string"},"data":{"type":"object","nullable":true}}},"cohort":{"type":"object","properties":{"available":{"type":"boolean"},"requiresTier":{"type":"string"},"data":{"type":"array","nullable":true,"items":{"type":"object","properties":{"cohortId":{"type":"string"},"cohortName":{"type":"string"},"rank":{"type":"integer"},"percentile":{"type":"number"},"visibilityDelta":{"type":"number"},"sentimentDelta":{"type":"number"},"entityCount":{"type":"integer"}}}}}},"meta":{"type":"object","properties":{"assembledAt":{"type":"string","format":"date-time"},"tier":{"type":"string","enum":["free","layer_0_discovery","layer_1_profile","layer_2_insight","layer_3_drift","layer_4_cohort"]},"recordVersion":{"type":"string"},"withheld":{"type":"array","items":{"type":"object","properties":{"section":{"type":"string"},"requiresTier":{"type":"string"}}}},"upgrade":{"type":"string"}}}}},"EntityType":{"type":"string","enum":["organization","person","product","location","event","concept","podcast"]},"SourceSurface":{"type":"string","description":"Provenance surface of an observation. `ai_engine_copilot` and the registry sources (gleif/edgar/opencorporates/ofac/hm_treasury/pep) are retained for observation provenance compatibility; collectors are flag-gated.","enum":["serp_organic","serp_ai_overview","serp_knowledge_graph","news","reddit","hackernews","bluesky","trustpilot","google_maps","wikipedia","linkedin","companies_house","crunchbase","github","scholar","patents","youtube","ai_engine_chatgpt","ai_engine_claude","ai_engine_gemini","ai_engine_perplexity","ai_engine_grok","ai_engine_copilot","own_site","gleif","edgar","opencorporates","ofac","hm_treasury","pep","other"]},"ScoreDimension":{"type":"string","enum":["completeness","visibility","sentiment","shareOfVoice","trustStack","narrativeCoverage","maturity"]},"Trajectory":{"type":"string","enum":["improving","stable","declining","volatile","accelerating","decelerating","recovering"]},"ClaimStatus":{"type":"string","enum":["current","superseded","contested","historical"]},"DriftType":{"type":"string","enum":["sentiment_spike","compounding_sentiment","source_divergence","fact_drift","velocity_change","neighbourhood_shift","trust_stack_change","ai_engine_drift","surface_divergence_trend"]},"DriftPattern":{"type":"string","enum":["breakout","erosion","pivot","crisis","drift_to_irrelevance","authority_lag"]},"Severity":{"type":"string","enum":["low","moderate","high","critical"]},"DeliveryChannel":{"type":"string","enum":["webhook","email","slack","none"]},"ApiTier":{"type":"string","enum":["free","layer_0_discovery","layer_1_profile","layer_2_insight","layer_3_drift","layer_4_cohort"]},"EntityIdentifiers":{"type":"object","properties":{"wikidataQid":{"type":"string","nullable":true},"companiesHouseNumber":{"type":"string","nullable":true},"linkedinSlug":{"type":"string","nullable":true},"domain":{"type":"string","nullable":true},"duns":{"type":"string","nullable":true}},"additionalProperties":{"type":"string","nullable":true}},"NeighbourhoodEdge":{"type":"object","required":["entityId","edgeType","weight","lastObservedAt"],"properties":{"entityId":{"type":"string","example":"entx_8f3a2b1c9d4e"},"edgeType":{"type":"string"},"weight":{"type":"number"},"lastObservedAt":{"type":"string","format":"date-time"}}},"Entity":{"type":"object","required":["id","type","canonicalName","aliases","identifiers","createdAt"],"properties":{"id":{"type":"string","example":"entx_8f3a2b1c9d4e"},"type":{"$ref":"#/components/schemas/EntityType"},"subtype":{"type":"string","nullable":true},"canonicalName":{"type":"string"},"aliases":{"type":"array","items":{"type":"string"}},"identifiers":{"$ref":"#/components/schemas/EntityIdentifiers"},"primaryMarket":{"type":"string","nullable":true},"markets":{"type":"array","items":{"type":"string"}},"claims":{"type":"array","items":{"$ref":"#/components/schemas/Claim"}},"completeness":{"$ref":"#/components/schemas/Score"},"neighbourhood":{"type":"array","items":{"$ref":"#/components/schemas/NeighbourhoodEdge"}},"createdAt":{"type":"string","format":"date-time"},"lastObservedAt":{"type":"string","format":"date-time","nullable":true},"lastResolvedAt":{"type":"string","format":"date-time","nullable":true}}},"PublicEntityLite":{"type":"object","description":"Trimmed Entity projection returned to `free`-tier API keys: canonical identity + identifiers + last-cached headline signals (AI Visibility / Sentiment / Share of Voice) only — no claims, insights, or neighbourhood. Full fidelity (Entity) is layer_1_profile+. See CANON §4 (Entity Profile, Free = lite).","required":["id","type","canonicalName","identifiers","headline","tier","upgrade"],"properties":{"id":{"type":"string","example":"entx_8f3a2b1c9d4e"},"type":{"$ref":"#/components/schemas/EntityType"},"canonicalName":{"type":"string"},"identifiers":{"$ref":"#/components/schemas/EntityIdentifiers"},"primaryMarket":{"type":"string","nullable":true},"lastObservedAt":{"type":"string","format":"date-time","nullable":true},"headline":{"type":"object","description":"Last-cached headline signals (zero compute). `null` where no snapshot exists yet.","required":["aiVisibility","sentiment","shareOfVoice"],"properties":{"aiVisibility":{"type":"number","nullable":true},"sentiment":{"type":"number","nullable":true},"shareOfVoice":{"type":"number","nullable":true}}},"tier":{"type":"string","enum":["free"]},"upgrade":{"type":"string","description":"Upgrade hint pointing to paid tiers."}}},"DiscoveryPath":{"type":"object","required":["method","query","queryType","depth"],"properties":{"method":{"type":"string"},"query":{"type":"string"},"queryType":{"type":"string"},"depth":{"type":"integer"}}},"Observation":{"type":"object","required":["id","entityId","sourceSurface","sourceProvider","observedAt","extractedClaims","extractedEntities"],"properties":{"id":{"type":"string","example":"obs_a4f8c2e1b9d3"},"entityId":{"type":"string"},"sourceSurface":{"$ref":"#/components/schemas/SourceSurface"},"sourceProvider":{"type":"string"},"sourceUrl":{"type":"string","nullable":true},"sourceTitle":{"type":"string","nullable":true},"snippet":{"type":"string","nullable":true},"discoveryPath":{"$ref":"#/components/schemas/DiscoveryPath","nullable":true},"observedAt":{"type":"string","format":"date-time"},"publishedAt":{"type":"string","format":"date-time","nullable":true},"sentimentScore":{"type":"number","nullable":true},"sentimentConfidence":{"type":"number","nullable":true},"extractedClaims":{"type":"array","items":{"type":"string"}},"extractedEntities":{"type":"array","items":{"type":"string"}},"rawPayload":{"nullable":true}}},"ClaimAssertion":{"type":"object","required":["observationId","sourceSurface","sourceProvider","assertedAt","authorityWeight","recencyWeight"],"properties":{"observationId":{"type":"string"},"sourceSurface":{"$ref":"#/components/schemas/SourceSurface"},"sourceProvider":{"type":"string"},"assertedAt":{"type":"string","format":"date-time"},"authorityWeight":{"type":"number"},"recencyWeight":{"type":"number"}}},"Claim":{"type":"object","required":["id","entityId","predicate","valueType","assertions","supersedes","confidence","status","conflictingClaims"],"properties":{"id":{"type":"string","example":"clm_d7e2a1c8b3f4"},"entityId":{"type":"string"},"predicate":{"type":"string"},"value":{},"valueType":{"type":"string","enum":["string","integer","number","boolean","date","datetime","object","array","entityRef"]},"unit":{"type":"string","nullable":true},"asOf":{"type":"string","format":"date","nullable":true},"assertions":{"type":"array","items":{"$ref":"#/components/schemas/ClaimAssertion"}},"supersedes":{"type":"array","items":{"type":"string"}},"supersededBy":{"type":"string","nullable":true},"confidence":{"type":"number"},"status":{"$ref":"#/components/schemas/ClaimStatus"},"conflictingClaims":{"type":"array","items":{"type":"string"}}}},"ScoreBreakdown":{"type":"object","required":["key","value","confidence","observationCount","weight"],"properties":{"key":{"type":"string"},"value":{"type":"number"},"confidence":{"type":"number"},"observationCount":{"type":"integer"},"weight":{"type":"number"}}},"ScoreWindow":{"type":"object","required":["start","end","label"],"properties":{"start":{"type":"string","format":"date-time"},"end":{"type":"string","format":"date-time"},"label":{"type":"string"}}},"Score":{"type":"object","required":["dimension","scope","value","valueRange","confidence","window","breakdown","explanation","computedAt","trajectory"],"properties":{"dimension":{"$ref":"#/components/schemas/ScoreDimension"},"scope":{"type":"string"},"value":{"type":"number"},"valueRange":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2},"confidence":{"type":"number"},"window":{"$ref":"#/components/schemas/ScoreWindow"},"breakdown":{"type":"array","items":{"$ref":"#/components/schemas/ScoreBreakdown"}},"explanation":{"type":"string"},"computedAt":{"type":"string","format":"date-time"},"previousValue":{"type":"number","nullable":true},"delta30d":{"type":"number","nullable":true},"delta90d":{"type":"number","nullable":true},"trajectory":{"$ref":"#/components/schemas/Trajectory"}}},"DriftSignal":{"type":"object","required":["surface","metric","value","observationCount"],"properties":{"surface":{"type":"string"},"metric":{"type":"string"},"value":{},"baseline":{"type":"number","nullable":true},"zScore":{"type":"number","nullable":true},"observationCount":{"type":"integer"}}},"ScoreSnapshot":{"type":"object","description":"A single dated score observation. Carries the Confidence Layer fields per CANON §3 Amendment 7 (sample_size + algorithm_version; 95% Wilson interval is derived where binomial).","required":["date","value"],"properties":{"date":{"type":"string","format":"date","description":"UTC date of the snapshot (YYYY-MM-DD)."},"value":{"type":"number","description":"Score value, 0–100, rounded to 1dp."}}},"ScoreHistoryResponse":{"type":"object","description":"Per-dimension score history over the requested lookback window. Drift figures compare the most recent snapshot to the one before it.","required":["entityId","days","dimensions"],"properties":{"entityId":{"type":"string","description":"Canonical entity slug (mirrors the URL entityId)."},"days":{"type":"integer","description":"Resolved lookback window (1–90)."},"dimensions":{"type":"object","description":"Map of ScoreDimension → series.","additionalProperties":{"type":"object","required":["history","current","previous","delta","trend"],"properties":{"history":{"type":"array","items":{"$ref":"#/components/schemas/ScoreSnapshot"}},"current":{"type":"number","nullable":true},"previous":{"type":"number","nullable":true},"delta":{"type":"number","nullable":true,"description":"current − previous, rounded to 1dp."},"trend":{"type":"string","enum":["up","down","stable","no_data"]}}}}}},"CoreIntelligence":{"type":"object","description":"Entity Core Intelligence Profile projection. The ten scores are an internal authority/readability model (0–100), NOT the canonical §3 Score dimensions, and carry no Confidence Layer; auditability is via version, runCount, lastUpdated, and grounding.","required":["entityId","entityName","version","lastUpdated","runCount","summary","primaryClassification","blendedScore","scores","topicOwnership","strongAssociations","competitors","perception","strategicActions","grounding"],"properties":{"entityId":{"type":"string","description":"Canonical entity slug (mirrors the URL entityId)."},"entityName":{"type":"string"},"version":{"type":"integer"},"lastUpdated":{"type":"string","format":"date-time"},"runCount":{"type":"integer"},"summary":{"type":"string","description":"One-paragraph plain-English explanation of the entity."},"primaryClassification":{"type":"string"},"blendedScore":{"type":"number","description":"Weighted blend of the ten scores (0–100)."},"scores":{"type":"object","required":["clarity","authority","trust","entityGraph","topicalAuthority","recommendation","marketClarity","machineReadability","momentum","reputationSafety"],"properties":{"clarity":{"type":"number"},"authority":{"type":"number"},"trust":{"type":"number"},"entityGraph":{"type":"number"},"topicalAuthority":{"type":"number"},"recommendation":{"type":"number"},"marketClarity":{"type":"number"},"machineReadability":{"type":"number"},"momentum":{"type":"number"},"reputationSafety":{"type":"number","description":"0 = high reputation risk, 100 = low risk."}}},"topicOwnership":{"type":"array","items":{"type":"object","properties":{"topic":{"type":"string"},"strength":{"type":"string"},"reason":{"type":"string"}}}},"strongAssociations":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string"},"relationship":{"type":"string"}}}},"competitors":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"overlap":{"type":"string"}}}},"perception":{"type":"object","properties":{"positive":{"type":"array","items":{"type":"string"}},"neutral":{"type":"array","items":{"type":"string"}},"negative":{"type":"array","items":{"type":"string"}}}},"strategicActions":{"type":"array","items":{"type":"string"}},"grounding":{"type":"object","nullable":true,"description":"Live-web grounding provenance for the most recent run, or null if never grounded.","properties":{"status":{"type":"string","enum":["active","unavailable"]},"groundedAt":{"type":"string","format":"date-time"},"searchResults":{"type":"integer"},"newsArticles":{"type":"integer"},"latestSourceDate":{"type":"string"},"sources":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"title":{"type":"string"},"publishedAt":{"type":"string"},"kind":{"type":"string","enum":["news","web"]}}}},"note":{"type":"string"}}}}},"DriftEvent":{"type":"object","required":["id","entityId","type","severity","direction","detectedAt","windowStart","windowEnd","confidence","signals","explanation"],"properties":{"id":{"type":"string","example":"drift_2c8e1a9f4b6d"},"entityId":{"type":"string"},"type":{"$ref":"#/components/schemas/DriftType"},"pattern":{"$ref":"#/components/schemas/DriftPattern","nullable":true},"severity":{"$ref":"#/components/schemas/Severity"},"direction":{"type":"string","enum":["positive","negative","neutral"]},"detectedAt":{"type":"string","format":"date-time"},"windowStart":{"type":"string","format":"date-time"},"windowEnd":{"type":"string","format":"date-time"},"confidence":{"type":"number"},"signals":{"type":"array","items":{"$ref":"#/components/schemas/DriftSignal"}},"explanation":{"type":"string"},"relatedClaimChanges":{"type":"array","items":{"type":"string"}},"projectedTrajectory":{"type":"object","nullable":true}}},"Alert":{"type":"object","required":["id","subscriptionId","driftEventId","entityId","deliveredAt","deliveryChannel","deliveryStatus","deliveryAttempts","driftEvent"],"properties":{"id":{"type":"string","example":"alert_9b3e1c7a2d4f"},"subscriptionId":{"type":"string"},"driftEventId":{"type":"string"},"entityId":{"type":"string"},"deliveredAt":{"type":"string","format":"date-time"},"deliveryChannel":{"$ref":"#/components/schemas/DeliveryChannel"},"deliveryStatus":{"type":"string","enum":["pending","delivered","failed","retrying"]},"deliveryAttempts":{"type":"integer"},"acknowledgedAt":{"type":"string","format":"date-time","nullable":true},"driftEvent":{"$ref":"#/components/schemas/DriftEvent"}}},"ReconciliationCandidate":{"type":"object","required":["entityId","canonicalName","confidence"],"properties":{"entityId":{"type":"string","example":"entx_8f3a2b1c9d4e"},"canonicalName":{"type":"string"},"confidence":{"type":"number","description":"0..1 similarity to the input."}}},"ReconciliationResult":{"type":"object","required":["input","resolved","entityId","canonicalName","confidence","band","candidates"],"properties":{"input":{"type":"string"},"resolved":{"type":"boolean","description":"True for the auto/strong bands."},"entityId":{"type":"string","nullable":true},"canonicalName":{"type":"string","nullable":true},"confidence":{"type":"number","description":"0..1 confidence of the top candidate; 0 when nothing matched."},"band":{"type":"string","enum":["auto","strong","review","unresolved"]},"candidates":{"type":"array","items":{"$ref":"#/components/schemas/ReconciliationCandidate"}}}},"ScoreConfidence":{"type":"object","description":"95% Wilson confidence envelope under a Score (confidenceLayer.ts). All fields optional.","properties":{"interval95":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2,"description":"[lower, upper] on the same 0..N scale as the score value."},"variance":{"type":"number","nullable":true},"sampleSize":{"type":"integer","description":"Observations the score is computed over (enginesEvaluated for Decision Survival)."},"probeRunIds":{"type":"array","items":{"type":"string"},"description":"Contributing probe_run UUIDs (capped at 20)."},"lastObservedAt":{"type":"string","format":"date-time"},"version":{"type":"string","example":"7.0.0","description":"Confidence-Layer scoring version."}}},"DisplacementTurn":{"type":"object","required":["turn","replacedBy"],"properties":{"turn":{"type":"integer"},"replacedBy":{"type":"array","items":{"type":"object","properties":{"entitySlug":{"type":"string"},"mentions":{"type":"integer"}}}}}},"DecisionSurvivalScore":{"type":"object","required":["entityId","scenarioKey","scenarioLabel","survivalRate","enginesEvaluated","enginesSurvived","perEngine","displacementChain","computedAt"],"properties":{"entityId":{"type":"string"},"scenarioKey":{"type":"string","example":"final_choice_under_constraints"},"scenarioLabel":{"type":"string"},"depth":{"type":"integer","description":"Decision depth of the scenario (3–5)."},"survivalRate":{"type":"number","description":"0..1 share of all probe trials (reps × engines) where the entity survived to the final turn."},"insufficientData":{"type":"boolean","description":"True when this scenario sits below the minimum-evidence floor (< 3 engines or < 3 total trials) — the rate is carried but should be rendered as a \"measuring\" state, not a reading."},"enginesEvaluated":{"type":"integer"},"enginesSurvived":{"type":"integer","description":"Engines where the entity survived at least one replication."},"perEngine":{"type":"object","additionalProperties":{"type":"integer","minimum":0},"description":"Per-engine count of successful replications (0..reps; 0 | 1 in the legacy single-rep shape)."},"displacementChain":{"type":"array","items":{"$ref":"#/components/schemas/DisplacementTurn"}},"transcript":{"type":"array","description":"One representative captured transcript per engine — the exact prompts plus that engine's actual reply per turn. Empty for runs predating the transcript capture.","items":{"$ref":"#/components/schemas/DecisionSurvivalEngineTranscript"}},"computedAt":{"type":"string","format":"date-time"},"confidence":{"$ref":"#/components/schemas/ScoreConfidence"}}},"DecisionSurvivalEngineTranscript":{"type":"object","required":["engine","survived","turns"],"properties":{"engine":{"type":"string","description":"Engine id (e.g. 'chatgpt', 'claude').","example":"chatgpt"},"survived":{"type":"boolean","description":"Whether the focal entity was still recommended at the final turn of this captured run."},"turns":{"type":"array","items":{"type":"object","required":["turn","prompt","response"],"properties":{"turn":{"type":"integer"},"prompt":{"type":"string","description":"The user message posed at this turn."},"response":{"type":"string","description":"The engine's reply (truncated)."}}}}}},"DecisionSurvivalResponse":{"oneOf":[{"type":"object","required":["available","scores"],"properties":{"available":{"type":"boolean","enum":[true]},"survivalRate":{"type":"number","nullable":true,"description":"Aggregate survival rate across scenarios."},"insufficientData":{"type":"boolean","description":"True when every returned scenario is below the minimum-evidence floor."},"scores":{"type":"array","items":{"$ref":"#/components/schemas/DecisionSurvivalScore"}}}},{"type":"object","required":["available","reason"],"properties":{"available":{"type":"boolean","enum":[false]},"reason":{"type":"string","enum":["no_signal_yet","scenario_not_found","entity_type_out_of_scope"]}}}]},"SurfacePairConcordance":{"type":"object","required":["surfaceA","labelA","surfaceB","labelB","coMovement","concordance","meanGap","gapSlope","trend","sampleSize"],"description":"Over-time relationship between two surfaces across the perception history window.","properties":{"surfaceA":{"type":"string","description":"Canonical surface id (ai_engines is pinned here when present)."},"labelA":{"type":"string"},"surfaceB":{"type":"string"},"labelB":{"type":"string"},"coMovement":{"type":"number","minimum":-1,"maximum":1,"description":"Do the two surfaces rise and fall together (+1) or oppose (−1)."},"concordance":{"type":"integer","minimum":0,"maximum":100,"description":"Level agreement = 100 − mean absolute gap."},"meanGap":{"type":"integer","description":"Mean absolute gap between the surfaces, 0..100 space."},"gapSlope":{"type":"number","description":"Least-squares slope of the gap over time, points/day."},"trend":{"type":"string","enum":["converging","diverging","stable"]},"sampleSize":{"type":"integer","description":"Aligned snapshot pairs the row was computed from."},"lead":{"type":"object","nullable":true,"description":"Leading relationship via lagged cross-correlation; null when synchronous or history too short. Day resolution — present as \"≈N days\".","required":["leaderSurface","leaderLabel","followerSurface","followerLabel","lagDays","coMovementAtLag"],"properties":{"leaderSurface":{"type":"string"},"leaderLabel":{"type":"string"},"followerSurface":{"type":"string"},"followerLabel":{"type":"string"},"lagDays":{"type":"integer","minimum":1},"coMovementAtLag":{"type":"number","minimum":-1,"maximum":1}}}}},"SurfaceCorrelationMatrix":{"type":"object","required":["entitySlug","windowDays","computedAt","surfaces","pairs","aiEnginesPairs","overall","snapshots"],"description":"Cross-surface agreement over time. Null on the parent response until enough aligned history exists.","properties":{"entitySlug":{"type":"string"},"windowDays":{"type":"integer"},"computedAt":{"type":"string","format":"date-time"},"surfaces":{"type":"array","items":{"type":"object","required":["surface","label"],"properties":{"surface":{"type":"string"},"label":{"type":"string"}}}},"pairs":{"type":"array","items":{"$ref":"#/components/schemas/SurfacePairConcordance"}},"aiEnginesPairs":{"type":"array","description":"Pairs involving ai_engines — the LLMs-vs-other-sources view.","items":{"$ref":"#/components/schemas/SurfacePairConcordance"}},"overall":{"type":"object","required":["meanConcordance","meanGapSlope","trend"],"properties":{"meanConcordance":{"type":"integer","minimum":0,"maximum":100},"meanGapSlope":{"type":"number"},"trend":{"type":"string","enum":["converging","diverging","stable"]}}},"snapshots":{"type":"integer"}}},"PerLlmLens":{"type":"object","required":["engine","completenessPct","weightedCompletenessPct","truthGapPct","probingHealthy","wants"],"properties":{"engine":{"type":"string","enum":["claude","chatgpt","gemini","grok","perplexity"]},"completenessPct":{"type":"number","nullable":true,"description":"Raw completeness 0..100."},"weightedCompletenessPct":{"type":"number","nullable":true,"description":"Importance-weighted completeness 0..100."},"truthGapPct":{"type":"number","nullable":true,"description":"Share of confident answers that diverge from verified record."},"probingHealthy":{"type":"boolean","description":"False if the engine failed every probe (outage / missing key)."},"wants":{"type":"array","items":{"type":"string"},"description":"Fields the engine says it is missing (untrusted, demand signal)."}}},"WeightedGap":{"type":"object","required":["entitySlug","field","wrongOn","missingOn","wantedBy","importance"],"properties":{"entitySlug":{"type":"string"},"field":{"type":"string"},"wrongOn":{"type":"array","items":{"type":"string"}},"missingOn":{"type":"array","items":{"type":"string"}},"wantedBy":{"type":"array","items":{"type":"string"}},"importance":{"type":"number","minimum":0,"maximum":1,"description":"Blended importance — surface + collect highest first."}}},"DataCompletenessResponse":{"oneOf":[{"type":"object","required":["available","entitySlug","canonicalName","lastComputedAt","schemaConformant","schemaViolations","perLlm","topGaps"],"properties":{"available":{"type":"boolean","enum":[true]},"entitySlug":{"type":"string"},"canonicalName":{"type":"string"},"lastComputedAt":{"type":"string","format":"date-time"},"schemaConformant":{"type":"boolean"},"schemaViolations":{"type":"integer"},"perLlm":{"type":"array","items":{"$ref":"#/components/schemas/PerLlmLens"}},"topGaps":{"type":"array","items":{"$ref":"#/components/schemas/WeightedGap"}},"ingestionLag":{"type":"object","nullable":true,"description":"Per-engine truth-gap ingestion lag estimate (optional, needs history)."}}},{"type":"object","required":["available","reason"],"properties":{"available":{"type":"boolean","enum":[false]},"reason":{"type":"string","description":"Why completeness data is not yet available."}}}]},"ConsensusMapResponse":{"oneOf":[{"type":"object","required":["available","consensusScore","divergenceScore","surfaces","spread","lastObservedAt","trendMatrix"],"properties":{"available":{"type":"boolean","enum":[true]},"consensusScore":{"type":"integer","minimum":0,"maximum":100,"description":"100 = surfaces agree."},"divergenceScore":{"type":"integer","minimum":0,"maximum":100,"description":"Complement of consensus."},"surfaces":{"type":"array","items":{"type":"object","required":["surface","label","value","sampleSize","description"],"properties":{"surface":{"type":"string"},"label":{"type":"string"},"value":{"type":"integer","minimum":0,"maximum":100},"sampleSize":{"type":"integer"},"delta7d":{"type":"number","nullable":true},"description":{"type":"string","description":"Source-agnostic caption for what this surface's number measures. Provider mechanics stay internal (CANON §7)."}}}},"spread":{"type":"object","required":["min","max","range"],"properties":{"min":{"type":"integer"},"max":{"type":"integer"},"range":{"type":"integer"}}},"confidence":{"type":"object","description":"Confidence Layer envelope (Amendment 7)."},"lastObservedAt":{"type":"string","format":"date-time"},"trendMatrix":{"description":"Cross-surface agreement over time. Null until enough aligned history exists.","nullable":true,"allOf":[{"$ref":"#/components/schemas/SurfaceCorrelationMatrix"}]}}},{"type":"object","required":["available","reason"],"properties":{"available":{"type":"boolean","enum":[false]},"reason":{"type":"string","enum":["no_signal_yet","insufficient_surfaces"]}}}]},"XSentimentSource":{"type":"object","required":["url","author","postedAt"],"description":"A cited X post — the grounding for every claim, voice, expansion link, and timeline event.","properties":{"url":{"type":"string"},"author":{"type":"string","description":"Handle without the leading \"@\"."},"postedAt":{"type":"string","format":"date-time"},"kind":{"type":"string","enum":["post","reply","quote","unknown"]}}},"XSentimentClaim":{"type":"object","required":["claim","cites"],"description":"Citation-backed assertion. `cites` indexes into the snapshot's `sources[]`.","properties":{"claim":{"type":"string"},"cites":{"type":"array","items":{"type":"integer","minimum":0}}}},"XSentimentKeyVoice":{"type":"object","required":["handle","stance","influence","cites"],"properties":{"handle":{"type":"string","description":"Display with @ prefix."},"stance":{"type":"string","enum":["ally","opponent","neutral"]},"influence":{"type":"string","enum":["high","medium","low"],"description":"Engagement proxy — NOT a follower count."},"cites":{"type":"array","items":{"type":"integer","minimum":0}}}},"XSentimentExpansionLink":{"type":"object","required":["name","kind","relation","narrative","linkSentiment","coMentionStrength","cites"],"description":"A related entity / account / outlet linked to the subject by a shared X narrative.","properties":{"name":{"type":"string"},"kind":{"type":"string","enum":["person","org","product","outlet","account","topic"]},"relation":{"type":"string","enum":["host_of","owner_of","founder_of","member_of","affiliated_with","parent_of","subsidiary_of","competitor_of","collaborator_of","related_to"],"description":"1:1 with the typed entity relationship taxonomy (Amendment 14)."},"narrative":{"type":"string"},"linkSentiment":{"type":"number","minimum":-1,"maximum":1,"description":"Joint-narrative sentiment, -1..1."},"coMentionStrength":{"type":"string","enum":["weak","notable","dominant"]},"cites":{"type":"array","items":{"type":"integer","minimum":0}}}},"XSentimentTimelineEvent":{"type":"object","required":["at","event","summary","cites"],"properties":{"at":{"type":"string","format":"date-time"},"event":{"type":"string","enum":["volume_spike","sentiment_shift","key_post_viral","external_trigger","new_claim","notable_post"]},"summary":{"type":"string"},"sentimentAfter":{"type":"number","nullable":true,"minimum":-1,"maximum":1},"cites":{"type":"array","items":{"type":"integer","minimum":0}}}},"XSentimentAuthenticity":{"type":"object","required":["assessment","patterns","confidence"],"description":"Heuristic organic-vs-amplified read. Reported as heuristic only — never as definitive bot detection (CANON §7).","properties":{"assessment":{"type":"string"},"patterns":{"type":"array","items":{"type":"string"}},"confidence":{"type":"string","enum":["low","medium"]}}},"XSentimentEarlyWarning":{"type":"object","required":["spikeDetected","note"],"properties":{"spikeDetected":{"type":"boolean"},"note":{"type":"string"}}},"XSentimentSnapshot":{"type":"object","required":["entitySlug","found","sentimentScore","sentimentLabel","volumeBucket","approxMentions","windowHours","keyVoices","topPraises","topComplaints","authenticity","narrativeContext","expansion","timeline","earlyWarning","sources","citations","confidence","model","collectedAt"],"description":"Single calibrated X (social surface) read. Public-facing schema name omits the provider mechanic per CANON §7 — internally this maps to the GrokXSentimentResult shape.","properties":{"entitySlug":{"type":"string"},"found":{"type":"boolean"},"sentimentScore":{"type":"number","minimum":-1,"maximum":1,"description":"Weighted polarity, -1..1."},"sentimentLabel":{"type":"string","enum":["positive","mostly_positive","neutral","mixed","negative"]},"volumeBucket":{"type":"string","enum":["none","low","moderate","high","viral"],"description":"Volume is a lower-bound estimate — never a precise count."},"approxMentions":{"type":"integer","description":"Lower-bound approximate mention count — derived for weighting only."},"windowHours":{"type":"integer","description":"Look-back window of the read."},"keyVoices":{"type":"array","items":{"$ref":"#/components/schemas/XSentimentKeyVoice"}},"topPraises":{"type":"array","items":{"$ref":"#/components/schemas/XSentimentClaim"}},"topComplaints":{"type":"array","items":{"$ref":"#/components/schemas/XSentimentClaim"}},"authenticity":{"$ref":"#/components/schemas/XSentimentAuthenticity"},"narrativeContext":{"type":"string"},"expansion":{"type":"array","items":{"$ref":"#/components/schemas/XSentimentExpansionLink"}},"timeline":{"type":"array","items":{"$ref":"#/components/schemas/XSentimentTimelineEvent"}},"earlyWarning":{"$ref":"#/components/schemas/XSentimentEarlyWarning"},"sources":{"type":"array","items":{"$ref":"#/components/schemas/XSentimentSource"}},"citations":{"type":"array","items":{"type":"string"}},"confidence":{"type":"integer","minimum":0,"maximum":100},"model":{"type":"string","description":"Internal — read-model identifier."},"collectedAt":{"type":"string","format":"date-time"},"grokCoupling":{"$ref":"#/components/schemas/XGrokCoupling","description":"Additive (latest-read only): day-aligned co-movement of the X conversation vs Grok’s perception of the entity."},"xProfile":{"$ref":"#/components/schemas/XProfileSnapshot","description":"Additive (latest-read only): latest official X profile snapshot, or null while the collector is dormant."},"xNarrative":{"$ref":"#/components/schemas/XNarrativeRead","description":"Additive (latest-read only): latest official-API narrative read (sampled mention sentiment, intent classes, emerging topics, amplification events), or null while the collector is dormant."}}},"XGrokCoupling":{"type":"object","description":"X → Grok coupling read: day-aligned co-movement and level concordance between the observed X conversation about the entity and Grok’s own perception of it, with a lead/lag read when one side clearly moves first. Observational — a coupling read, not a causal claim. `available: false` with reason `insufficient_history` until enough overlapping days accrue.","required":["available"],"properties":{"available":{"type":"boolean"},"reason":{"type":"string","enum":["insufficient_history"],"description":"Present when available=false."},"coMovement":{"type":"number","minimum":-1,"maximum":1,"description":"Day-aligned co-movement of the two series."},"concordance":{"type":"number","minimum":0,"maximum":100,"description":"100 − mean level gap between the day-aligned series."},"lead":{"type":"object","nullable":true,"properties":{"leader":{"type":"string","enum":["x","grok"]},"lagDays":{"type":"integer","minimum":1},"coMovementAtLag":{"type":"number","minimum":-1,"maximum":1}}},"sampleDays":{"type":"integer"},"windowDays":{"type":"integer"},"methodology":{"type":"string"},"computedAt":{"type":"string","format":"date-time"}}},"XProfileSnapshot":{"type":"object","nullable":true,"description":"Official X profile snapshot for the entity’s cross-verified X handle: follower/following/post counts, platform verification state, and bio. Collected at most once per 24h; null while no official-API credential is provisioned.","properties":{"entitySlug":{"type":"string"},"username":{"type":"string"},"userId":{"type":"string"},"displayName":{"type":"string"},"followers":{"type":"integer"},"following":{"type":"integer"},"postCount":{"type":"integer"},"listedCount":{"type":"integer"},"verified":{"type":"boolean"},"verifiedType":{"type":"string","nullable":true},"bio":{"type":"string","nullable":true},"accountCreatedAt":{"type":"string","format":"date-time","nullable":true},"collectedAt":{"type":"string","format":"date-time"},"source":{"type":"string","enum":["x_api"]}}},"XNarrativeRead":{"type":"object","nullable":true,"description":"Official-API narrative read of the X conversation about the entity: a sampled set of mentions of the entity’s cross-verified X handle, scored for sentiment and intent, with emerging topics and amplification events (viral post, contested post, pile-on, volume surge). Collected at most once per 24h; null while no official-API credential is provisioned.","properties":{"entitySlug":{"type":"string"},"username":{"type":"string"},"sampleSize":{"type":"integer","description":"Number of X posts sampled in the read."},"sentimentScore":{"type":"integer","minimum":0,"maximum":100,"description":"Mean 0–100 polarity over the sampled posts."},"sentimentLabel":{"type":"string","enum":["positive","mixed","negative"]},"intentDistribution":{"type":"object","description":"Counts of sampled posts by intent class.","properties":{"praise":{"type":"integer"},"question":{"type":"integer"},"complaint":{"type":"integer"},"suggestion":{"type":"integer"},"neutral":{"type":"integer"}}},"emergingTopics":{"type":"array","items":{"type":"string"},"description":"Deterministic top topics across the sampled posts."},"amplification":{"type":"array","items":{"$ref":"#/components/schemas/XAmplificationEvent"}},"postsPerHour":{"type":"number","description":"Observed density of the X conversation across the sampled window."},"windowHours":{"type":"number","description":"Span of the sampled window in hours."},"collectedAt":{"type":"string","format":"date-time"},"source":{"type":"string","enum":["x_api"]}}},"XAmplificationEvent":{"type":"object","description":"A detected amplification event in the X conversation.","required":["kind","summary","direction","confidence","at"],"properties":{"kind":{"type":"string","enum":["viral_post","ratio","pile_on","volume_surge"]},"summary":{"type":"string"},"evidencePostId":{"type":"string","nullable":true},"direction":{"type":"string","enum":["positive","negative"]},"confidence":{"type":"number","minimum":0,"maximum":1},"at":{"type":"string","format":"date-time"}}},"XSentimentHistoryResponse":{"type":"array","description":"Append-only series of stored X sentiment reads (oldest first).","items":{"$ref":"#/components/schemas/XSentimentSnapshot"}},"TimelineResponseExcerpt":{"type":"object","description":"One AI-engine reply excerpt attached to a `response` timeline event.","required":["engine","label","text","at"],"properties":{"engine":{"type":"string","description":"Engine id — chatgpt / claude / gemini / perplexity / grok."},"label":{"type":"string","description":"Public engine label (§7 casing)."},"text":{"type":"string","description":"Truncated response text (≤ ~500 chars)."},"at":{"type":"string","format":"date-time"},"mentionedEntity":{"type":"boolean"}}},"TimelineFactRow":{"type":"object","description":"One verified / observed / model-said fact row attached to a `truthGap` event.","required":["label","value"],"properties":{"label":{"type":"string"},"value":{"type":"string"}}},"TimelineEvidence":{"type":"object","description":"Optional expandable evidence panel — response excerpts, verified/observed fact rows, deep-dive links, or a supporting narrative note. The UI reveals this on click.","properties":{"responses":{"type":"array","items":{"$ref":"#/components/schemas/TimelineResponseExcerpt"}},"facts":{"type":"array","items":{"$ref":"#/components/schemas/TimelineFactRow"}},"links":{"type":"array","items":{"type":"object","required":["label","href"],"properties":{"label":{"type":"string"},"href":{"type":"string"}}}},"note":{"type":"string","description":"Free-form supporting text (e.g. X narrative context)."}}},"TimelineEvent":{"type":"object","required":["id","at","kind","title","detail","tone"],"properties":{"id":{"type":"string","description":"Stable, deterministic id."},"at":{"type":"string","format":"date-time"},"kind":{"type":"string","enum":["score","drift","lifecycle","x","truthGap","response","googleAi"],"description":"Event class. `x` = X (social) inflection or amplification event; `truthGap` = Claim Truth transition or narrative divergence (Amendment 20); `response` = captured AI-engine responses or a Decision Survival run."},"title":{"type":"string"},"detail":{"type":"string"},"tone":{"type":"string","enum":["positive","negative","risk","neutral"]},"dimension":{"type":"string","description":"Score dimension (score events only)."},"magnitude":{"type":"number","description":"Signed delta magnitude (score events)."},"severity":{"type":"string","description":"Drift severity, or `high` for early-warning X spikes / pile-on."},"evidence":{"$ref":"#/components/schemas/TimelineEvidence"}}},"EntityTimeline":{"type":"object","required":["events","windowDays","generatedAt","counts"],"description":"Unified chronological timeline — 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. Every event carries an optional `evidence` panel the UI reveals on click.","properties":{"events":{"type":"array","items":{"$ref":"#/components/schemas/TimelineEvent"}},"windowDays":{"type":"integer","minimum":1,"maximum":90},"generatedAt":{"type":"string","format":"date-time"},"counts":{"type":"object","required":["score","drift","lifecycle","x","truthGap","response","googleAi"],"properties":{"score":{"type":"integer"},"drift":{"type":"integer"},"lifecycle":{"type":"integer"},"x":{"type":"integer"},"truthGap":{"type":"integer"},"response":{"type":"integer"},"googleAi":{"type":"integer"}}}}},"PublicMarketData":{"type":"object","description":"Stock-market reading for an entity (CANON Amendment 21): its own listing or that of its public owner/parent. The price provider is internal (CANON §7) — `source` is a freshness class.","required":["found","symbol","exchange","price","currency","changePct","marketCapUsd","asOf","live","source","viaPublicOwner","confidence","collectedAt"],"properties":{"found":{"type":"boolean","enum":[true]},"symbol":{"type":"string","nullable":true},"exchange":{"type":"string","nullable":true},"price":{"type":"number","nullable":true},"currency":{"type":"string","nullable":true},"changePct":{"type":"number","nullable":true},"marketCapUsd":{"type":"number","nullable":true},"asOf":{"type":"string","format":"date-time","nullable":true,"description":"ISO timestamp the quote reflects."},"live":{"type":"boolean","description":"true = near-real-time, false = end-of-day / delayed."},"source":{"type":"string","enum":["real-time","delayed"],"nullable":true,"description":"Quote freshness class — provider names are internal (CANON §7)."},"viaPublicOwner":{"type":"object","nullable":true,"description":"Set when the reading comes from a public owner/parent, not the entity itself.","properties":{"ownerSlug":{"type":"string"},"relationship":{"type":"string"}}},"confidence":{"type":"integer","minimum":0,"maximum":100,"description":"0–100 (lower for EOD / owner-derived)."},"collectedAt":{"type":"string","format":"date-time"}}},"EcosystemEngine":{"type":"object","description":"Per-engine read. Presence metrics (mention/recommendation/citation/sentiment) are GROUNDED in observed AI-engine signals and carry provenance (groundedIn/sampleSize/confidence); fit/strengths/gaps/advice are an AI strategic assessment (advisory) — see the snapshot `methodology` field (CANON §3/§7).","required":["engine","label","maker","fit","mentionRate","recommendationRate","citationRate","sentiment","groundedIn","sampleSize","confidence","lastObservedAt","communicationMatch","strengths","gaps","advice"],"properties":{"engine":{"type":"string","enum":["chatgpt","claude","gemini","perplexity","grok"],"description":"Canonical AI engine id."},"label":{"type":"string"},"maker":{"type":"string","nullable":true,"description":"Engine maker name (e.g. OpenAI, Anthropic)."},"fit":{"type":"integer","minimum":0,"maximum":100,"description":"AI-assessed engine fit (advisory)."},"mentionRate":{"type":"integer","minimum":0,"maximum":100,"description":"Grounded."},"recommendationRate":{"type":"integer","minimum":0,"maximum":100,"description":"Grounded."},"citationRate":{"type":"integer","minimum":0,"maximum":100,"description":"Grounded."},"sentiment":{"type":"string","enum":["positive","neutral","negative","mixed"]},"groundedIn":{"type":"string","enum":["signals","llm_estimated"],"description":"Provenance of the presence metrics."},"sampleSize":{"type":"integer","minimum":0},"confidence":{"type":"integer","minimum":0,"maximum":100},"lastObservedAt":{"type":"string","format":"date-time"},"communicationMatch":{"type":"string"},"strengths":{"type":"array","items":{"type":"string"}},"gaps":{"type":"array","items":{"type":"string"}},"advice":{"type":"string"}}},"EcosystemResponse":{"oneOf":[{"type":"object","required":["available","entityId","influenceScore","coherenceScore","engines","feedbackLoops","coherenceGaps","narrative","priorityActions","lastAssessedAt","methodology"],"properties":{"available":{"type":"boolean","enum":[true]},"entityId":{"type":"string","description":"Canonical entx_ entity id."},"influenceScore":{"type":"integer","minimum":0,"maximum":100},"coherenceScore":{"type":"integer","minimum":0,"maximum":100,"nullable":true},"engines":{"type":"array","items":{"$ref":"#/components/schemas/EcosystemEngine"}},"feedbackLoops":{"type":"array","items":{"type":"object","required":["type","engine","strength","description"],"properties":{"type":{"type":"string"},"engine":{"type":"string"},"strength":{"type":"integer","minimum":0,"maximum":100},"description":{"type":"string"}}}},"coherenceGaps":{"type":"array","items":{"type":"object","required":["engine","impact","issue","recommendation"],"properties":{"engine":{"type":"string"},"impact":{"type":"string","enum":["high","medium","low"]},"issue":{"type":"string"},"recommendation":{"type":"string"}}}},"narrative":{"type":"string","nullable":true,"description":"AI strategic narrative (advisory)."},"priorityActions":{"type":"array","items":{"type":"string"}},"lastAssessedAt":{"type":"string","format":"date-time","nullable":true},"methodology":{"type":"string","description":"Disclosure that presence metrics are grounded while fit/strengths/advice are advisory."}}},{"type":"object","required":["available","reason"],"properties":{"available":{"type":"boolean","enum":[false]},"reason":{"type":"string","enum":["not_assessed_yet"]}}}]},"ResponseMeta":{"type":"object","required":["requestId","timestamp","apiVersion"],"properties":{"requestId":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"apiVersion":{"type":"string"},"pagination":{"type":"object","properties":{"cursor":{"type":"string","nullable":true},"hasMore":{"type":"boolean"},"limit":{"type":"integer"}}},"rateLimit":{"type":"object","properties":{"limit":{"type":"integer"},"remaining":{"type":"integer"},"resetAt":{"type":"string","format":"date-time"}}},"billing":{"type":"object","properties":{"creditsUsed":{"type":"integer"},"creditsRemaining":{"type":"integer","nullable":true},"tier":{"$ref":"#/components/schemas/ApiTier"},"allowedLayers":{"type":"array","items":{"type":"integer","minimum":0,"maximum":4},"description":"Cumulative layer ladder unlocked by this key (0=discovery … 4=cohort). free → []; layer_2_insight → [0,1,2]."},"mode":{"type":"string","enum":["demo","free","payg","keyed"],"description":"How the caller is billed: demo (feedback-loop key), free (monthly allowance), payg (Developer PAYG), keyed (paid subscription)."}}}}},"ApiError":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["ENTITY_NOT_RESOLVED","ENTITY_NOT_FOUND","INVALID_PARAMETER","RATE_LIMITED","INSUFFICIENT_CREDITS","TIER_NOT_AVAILABLE","UNAUTHENTICATED","FORBIDDEN","INTERNAL_ERROR"]},"message":{"type":"string"},"field":{"type":"string"},"candidates":{"type":"array","items":{"type":"object"}}}},"VerifiedFact":{"type":"object","description":"A single canonical fact, anchored to the highest-authority source available.","required":["field","value","source","confidence","asOf"],"properties":{"field":{"type":"string","description":"Canonical display label (e.g. \"Headquarters\")."},"value":{"type":"string"},"source":{"type":"string","description":"Original source label (e.g. \"Wikidata\", \"Entidex pipeline\")."},"confidence":{"type":"number","minimum":0,"maximum":100},"asOf":{"type":"string","format":"date-time","nullable":true}}},"Confirmation":{"type":"object","description":"A lower-authority observation that was superseded by a higher-authority record. Surfaced explicitly so consumers can render corroboration, narrowing context, or dissent against the verified value. Introduced in schemaVersion 1.1.","required":["canonicalId","field","value","source","confidence","asOf","relationshipToVerified","verifiedValue","verifiedSource"],"properties":{"canonicalId":{"type":"string","description":"Stable canonical-field id from the catalog."},"field":{"type":"string","description":"Canonical display label."},"value":{"type":"string","description":"The demoted value."},"source":{"type":"string"},"confidence":{"type":"number","minimum":0,"maximum":100},"asOf":{"type":"string","format":"date-time","nullable":true},"relationshipToVerified":{"type":"string","enum":["corroboration","narrowing_for_context","alternate_claim"],"description":"corroboration = same logical value; narrowing_for_context = subset/superset of the verified value; alternate_claim = genuine disagreement at lower authority."},"verifiedValue":{"type":"string","description":"The winning value, for self-contained rendering."},"verifiedSource":{"type":"string"}}},"KnowledgeCorrection":{"type":"object","description":"A point where AI engines diverge from the verified record (the gap-closure core).","required":["field","commonAiClaim","verifiedValue","source","status","asOf"],"properties":{"field":{"type":"string"},"commonAiClaim":{"type":"string","nullable":true,"description":"What AI engines commonly say (null when no confident answer)."},"verifiedValue":{"type":"string","nullable":true,"description":"The verified value."},"source":{"type":"string","description":"Verified-record source (e.g. \"Wikidata.P571\")."},"status":{"type":"string","enum":["contradiction","ai_unaware"]},"asOf":{"type":"string","format":"date-time","nullable":true}}},"NarrativeCorrection":{"type":"object","description":"A point where the entity's own published view diverges from external perception.","required":["aspect","ownView","externalView","divergence"],"properties":{"aspect":{"type":"string","description":"Canonical aspect label."},"ownView":{"type":"string","description":"Entity's own claim."},"externalView":{"type":"string","description":"External perception summary."},"divergence":{"type":"number","minimum":0,"maximum":100,"description":"0–100 composite divergence."}}},"KnowledgeAccuracy":{"type":"object","description":"Cross-check summary: how often AI engines agreed with the verified record.","required":["evaluated","matches","mismatches","pct","confidence"],"properties":{"evaluated":{"type":"integer","description":"Total fields cross-checked across AI engines."},"matches":{"type":"integer"},"mismatches":{"type":"integer"},"pct":{"type":"integer","nullable":true,"minimum":0,"maximum":100,"description":"matches / (matches + mismatches), as a percentage."},"confidence":{"type":"object","nullable":true,"description":"95% Wilson interval over the binomial (Amendment 7 Confidence Layer).","properties":{"version":{"type":"string"},"sampleSize":{"type":"integer"},"interval95":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2,"description":"Lower/upper bound, scaled to the count domain (0..sampleSize)."}}}}},"KnowledgeAccuracyCorrection":{"type":"object","required":["field","aiClaim","verifiedValue","source","kind"],"description":"A field one engine gets wrong (contradiction) or is unaware of (ai_unaware) vs the verified record.","properties":{"field":{"type":"string","description":"Human-readable field label, e.g. \"Headquarters\"."},"aiClaim":{"type":"string","nullable":true,"description":"What the engine claimed (null for an ai_unaware gap)."},"verifiedValue":{"type":"string","nullable":true,"description":"The verified value the engine should hold."},"source":{"type":"string","nullable":true,"description":"Provenance of the verified value, e.g. \"Wikidata\"."},"kind":{"type":"string","enum":["contradiction","ai_unaware"]}}},"EngineKnowledgeAccuracy":{"type":"object","required":["engine","maker","makerHref","evaluated","matches","mismatches","modelNulls","decidable","accuracyPct","corrections"],"properties":{"engine":{"type":"string","description":"Canonical model label, e.g. \"ChatGPT\"."},"maker":{"type":"string","description":"Maker company, e.g. \"OpenAI\"."},"makerHref":{"type":"string","description":"Maker entity page, e.g. \"/entity/openai\"."},"evaluated":{"type":"integer","description":"All fields cross-checked for this engine."},"matches":{"type":"integer"},"mismatches":{"type":"integer"},"modelNulls":{"type":"integer","description":"Fields the engine made no claim about (coverage gap, not an accuracy miss)."},"decidable":{"type":"integer","description":"matches + mismatches — the accuracy denominator."},"accuracyPct":{"type":"integer","nullable":true,"minimum":0,"maximum":100,"description":"matches / decidable, or null when nothing decidable."},"corrections":{"type":"array","items":{"$ref":"#/components/schemas/KnowledgeAccuracyCorrection"}}}},"LlmKnowledgeAccuracy":{"type":"object","description":"Per-engine accuracy of AI engines vs the verified record. The overall figure equals the Entity Knowledge Statement accuracy, promoted here to a first-class per-engine surface.","required":["entityId","available","computationVersion","accuracyPct","evaluated","matches","mismatches","modelNulls","decidable","enginesEvaluated","confidence","perEngine","methodology","provenance"],"properties":{"entityId":{"type":"string","description":"Canonical entx_xxxx id."},"available":{"type":"boolean","enum":[true]},"computationVersion":{"type":"string","example":"llm-knowledge-accuracy@1"},"accuracyPct":{"type":"integer","nullable":true,"minimum":0,"maximum":100,"description":"Overall accuracy across all engines — the headline %. Null when nothing decidable."},"evaluated":{"type":"integer"},"matches":{"type":"integer"},"mismatches":{"type":"integer"},"modelNulls":{"type":"integer"},"decidable":{"type":"integer"},"enginesEvaluated":{"type":"integer","description":"Engines that contributed at least one decidable check."},"confidence":{"$ref":"#/components/schemas/ScoreConfidence"},"perEngine":{"type":"array","items":{"$ref":"#/components/schemas/EngineKnowledgeAccuracy"}},"methodology":{"type":"string"},"provenance":{"type":"object","required":["issuer","methodologyUrl","note"],"properties":{"issuer":{"type":"string","example":"Entidex"},"methodologyUrl":{"type":"string","format":"uri"},"note":{"type":"string"}}}}},"LlmKnowledgeAccuracyUnavailable":{"type":"object","required":["entityId","available","reason"],"properties":{"entityId":{"type":"string"},"available":{"type":"boolean","enum":[false]},"reason":{"type":"string","enum":["no_knowledge_probes","disabled"]}}},"GroundingCheckRequest":{"type":"object","required":["statement"],"properties":{"statement":{"type":"string","maxLength":1000,"description":"The statement to check against the verified record (max 1000 characters). Treated strictly as data — pattern-matched, never interpolated.","example":"Tesla is headquartered in Palo Alto and was founded in 2003."}}},"GroundingCitation":{"type":"object","required":["url","source","asOf"],"properties":{"url":{"type":"string","format":"uri","description":"Deep link into the public Knowledge Statement backing the verdict."},"source":{"type":"string","description":"Provenance of the verified value, e.g. \"Wikidata\"."},"asOf":{"type":"string","nullable":true,"description":"Observation date of the verified value (ISO)."}}},"GroundingAssertionVerdict":{"type":"object","required":["text","field","canonicalFieldId","claimedValue","verdict","relationship","confidence","verifiedValue","citation","reason"],"description":"One extracted field/value assertion and its coded verdict against the verified record.","properties":{"text":{"type":"string","description":"The clause of the statement the assertion was extracted from."},"field":{"type":"string","nullable":true,"description":"Canonical field label, e.g. \"Headquarters\"."},"canonicalFieldId":{"type":"string","nullable":true,"description":"Stable canonical-field id, e.g. \"headquarters\"."},"claimedValue":{"type":"string","description":"The value the statement claims."},"verdict":{"type":"string","enum":["supported","contradicted","unverifiable"]},"relationship":{"type":"string","nullable":true,"enum":["exact","equivalent","narrowing","conflict",null],"description":"How the claim relates to the verified value. A granularity difference (\"Austin\" vs \"Austin, Texas\") is narrowing and SUPPORTS the record."},"confidence":{"type":"integer","nullable":true,"minimum":0,"maximum":100,"description":"The verified fact's stored confidence; null when unverifiable."},"verifiedValue":{"type":"string","nullable":true},"citation":{"oneOf":[{"$ref":"#/components/schemas/GroundingCitation"}],"nullable":true},"reason":{"type":"string","nullable":true,"enum":["field_not_in_verified_record","unrecognized_assertion",null],"description":"Why the assertion is unverifiable — out-of-record assertions are never guessed."}}},"GroundingCheck":{"type":"object","description":"Grounding Check — coded verdicts for a statement vs the signed verified record. Zero LLM: deterministic assertion extraction + the canonical-field equivalence ladder. A verdict against the verified record, not a global truth adjudication. NOT a §3 Score.","required":["entityId","entity","available","verdict","confidence","assertions","checkedAssertions","unverifiableReason","computationVersion","checkedAt","provenance"],"properties":{"entityId":{"type":"string","description":"Canonical entx_xxxx id."},"entity":{"type":"string","description":"Canonical entity name."},"available":{"type":"boolean","enum":[true]},"verdict":{"type":"string","enum":["supported","contradicted","unverifiable"],"description":"Overall roll-up — worst verdict wins (contradicted > unverifiable > supported)."},"confidence":{"type":"integer","nullable":true,"minimum":0,"maximum":100,"description":"Minimum verified-fact confidence across decided assertions; null when none decided."},"assertions":{"type":"array","items":{"$ref":"#/components/schemas/GroundingAssertionVerdict"}},"checkedAssertions":{"type":"integer"},"unverifiableReason":{"type":"string","nullable":true,"enum":["no_recognized_assertion","no_decidable_assertion",null]},"computationVersion":{"type":"string","example":"grounding-check@1"},"checkedAt":{"type":"string","format":"date-time"},"provenance":{"type":"object","required":["verifiedRecordUrl","methodologyUrl","note"],"properties":{"verifiedRecordUrl":{"type":"string","format":"uri"},"methodologyUrl":{"type":"string","format":"uri"},"note":{"type":"string"}}}}},"GroundingCheckUnavailable":{"type":"object","required":["entityId","available","reason"],"properties":{"entityId":{"type":"string"},"available":{"type":"boolean","enum":[false]},"reason":{"type":"string","enum":["disabled","no_verified_record"]}}},"EnginePromptClassRead":{"type":"object","required":["engine","maker","makerHref","trials","survived","recommendationPct"],"properties":{"engine":{"type":"string","example":"ChatGPT"},"maker":{"type":"string","nullable":true,"example":"OpenAI"},"makerHref":{"type":"string","nullable":true,"example":"/entity/openai"},"trials":{"type":"integer","description":"Replications this engine ran for the class."},"survived":{"type":"integer","description":"Trials in which the entity was still recommended at the final turn."},"recommendationPct":{"type":"integer","nullable":true,"minimum":0,"maximum":100}}},"PromptClassRead":{"type":"object","required":["classId","label","description","example","measured","reading"],"properties":{"classId":{"type":"string","enum":["discovery","evaluation","constrained_choice","hiring","learning","category_leader","risk_assessment","adjacent"],"description":"Canonical prompt-class id (CANON Amendment 22 taxonomy)."},"label":{"type":"string","example":"Discovery"},"description":{"type":"string"},"example":{"type":"string","description":"Illustrative prompt; the probes use canonical scenarios, not this string."},"measured":{"type":"boolean","description":"True when derived from stored Decision Survival probes."},"reading":{"type":"object","nullable":true,"required":["trials","survived","recommendationPct","enginesEvaluated","lastObservedAt","perEngine"],"properties":{"trials":{"type":"integer"},"survived":{"type":"integer"},"recommendationPct":{"type":"integer","minimum":0,"maximum":100},"interval95":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2,"description":"95% Wilson interval on 0..100."},"enginesEvaluated":{"type":"integer"},"lastObservedAt":{"type":"string","format":"date-time","nullable":true},"perEngine":{"type":"array","items":{"$ref":"#/components/schemas/EnginePromptClassRead"}}}}}},"RecommendationPotential":{"type":"object","description":"Per-prompt-class breakdown of AI recommendation likelihood. Projects stored Decision Survival probes onto a canonical 8-class prompt-class taxonomy (3 measured, 5 planned). Coded reducer, zero LLM cost.","required":["entityId","available","computationVersion","overallPct","trials","survived","classesEvaluated","confidence","classes","strongestClasses","weakestClasses","methodology","provenance"],"properties":{"entityId":{"type":"string","description":"Canonical entx_xxxx id."},"available":{"type":"boolean","enum":[true]},"computationVersion":{"type":"string","example":"ai-recommendation-potential@1"},"overallPct":{"type":"integer","nullable":true,"minimum":0,"maximum":100,"description":"Weighted-mean recommendation rate across measured classes."},"trials":{"type":"integer"},"survived":{"type":"integer"},"classesEvaluated":{"type":"integer","description":"Number of measured classes that contributed a reading."},"confidence":{"$ref":"#/components/schemas/ScoreConfidence"},"classes":{"type":"array","items":{"$ref":"#/components/schemas/PromptClassRead"}},"strongestClasses":{"type":"array","items":{"$ref":"#/components/schemas/PromptClassRead"}},"weakestClasses":{"type":"array","items":{"$ref":"#/components/schemas/PromptClassRead"}},"methodology":{"type":"string"},"provenance":{"type":"object","required":["issuer","methodologyUrl","note"],"properties":{"issuer":{"type":"string","example":"Entidex"},"methodologyUrl":{"type":"string","format":"uri"},"note":{"type":"string"}}}}},"RecommendationPotentialUnavailable":{"type":"object","required":["entityId","available","reason"],"properties":{"entityId":{"type":"string"},"available":{"type":"boolean","enum":[false]},"reason":{"type":"string","enum":["no_signal_yet","entity_out_of_scope","disabled"]}}},"LocalSurvivalCitation":{"type":"object","required":["source","domain","url","title"],"properties":{"source":{"type":"string","nullable":true},"domain":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"title":{"type":"string","nullable":true}}},"LocalSurvivalCompetitor":{"type":"object","required":["name","rank","leader","href"],"properties":{"name":{"type":"string"},"rank":{"type":"integer"},"leader":{"type":"boolean","description":"true when this business held slot 1 (the one Google's AI led with)."},"href":{"type":"string","nullable":true,"description":"Entity page href when tracked, else null."}}},"LocalSurvivalTurn":{"type":"object","required":["turn","role","query","answered","named","rank","totalNamed","replyExcerpt","droppedHere","citations","competitors"],"properties":{"turn":{"type":"string","example":"T1"},"role":{"type":"string","enum":["open","constrain","constrain_2","force_pick"]},"query":{"type":"string","description":"The simulated buyer’s search at this step (a plain query, never an instruction)."},"answered":{"type":"boolean"},"named":{"type":"boolean","description":"The focal business is named in Google's AI answer at this step."},"rank":{"type":"integer","nullable":true},"totalNamed":{"type":"integer"},"replyExcerpt":{"type":"string","description":"Verbatim excerpt of Google's AI answer for this step — the evidence."},"droppedHere":{"type":"boolean","description":"true when this is the step where the focal dropped out."},"citations":{"type":"array","items":{"$ref":"#/components/schemas/LocalSurvivalCitation"}},"competitors":{"type":"array","items":{"$ref":"#/components/schemas/LocalSurvivalCompetitor"}}}},"LocalSurvivalJourney":{"type":"object","required":["path","outcome","survived","firstDropTurn","offrampConstraint","neverSurfaced","displacer","turns"],"properties":{"path":{"type":"string","enum":["urgency","quality"]},"outcome":{"type":"string","enum":["survived","eliminated","never_surfaced","measuring"]},"survived":{"type":"boolean"},"firstDropTurn":{"type":"string","nullable":true},"offrampConstraint":{"type":"string","nullable":true,"description":"The plain-English constraint that dropped the focal."},"neverSurfaced":{"type":"boolean"},"displacer":{"type":"string","nullable":true,"description":"The business that took the slot the focal lost."},"turns":{"type":"array","items":{"$ref":"#/components/schemas/LocalSurvivalTurn"}}}},"LocalSurvivalStagePoint":{"type":"object","required":["turn","role","presentPct","sample"],"properties":{"turn":{"type":"string"},"role":{"type":"string"},"presentPct":{"type":"number","nullable":true,"minimum":0,"maximum":100},"sample":{"type":"integer"}}},"LocalSurvivalOfframp":{"type":"object","required":["label","count","sharePct"],"properties":{"label":{"type":"string","description":"Plain-English constraint label (which follow-up dropped the focal)."},"count":{"type":"integer"},"sharePct":{"type":"number","minimum":0,"maximum":100}}},"LocalSurvivalDisplacer":{"type":"object","required":["name","href","count"],"properties":{"name":{"type":"string"},"href":{"type":"string","nullable":true},"count":{"type":"integer"}}},"LocalSurvival":{"type":"object","description":"Whether a local business survives as Google's AI recommendation across a simulated near-me buyer journey (broad search → narrowing follow-ups → forced pick), with per-step AI replies, competitor mentions, and cited sources. Deterministic zero-LLM read.","required":["entityId","available","business","locality","category","categoryLabel","survivalRatePct","wilsonLowPct","wilsonHighPct","sampleJourneys","measuring","stageSurvival","offrampConcentration","topDisplacers","journeys","collectedAt","computationVersion","methodology","provenance"],"properties":{"entityId":{"type":"string","description":"Canonical entx_xxxx id."},"available":{"type":"boolean","enum":[true]},"business":{"type":"string"},"locality":{"type":"string"},"category":{"type":"string"},"categoryLabel":{"type":"string"},"survivalRatePct":{"type":"number","nullable":true,"minimum":0,"maximum":100,"description":"Share of journeys the business survived to Google's AI forced pick. Null = Measuring."},"wilsonLowPct":{"type":"number","nullable":true},"wilsonHighPct":{"type":"number","nullable":true},"sampleJourneys":{"type":"integer"},"measuring":{"type":"boolean","description":"True below the minimum-evidence floor — render \"Measuring\", never the numeric."},"stageSurvival":{"type":"array","items":{"$ref":"#/components/schemas/LocalSurvivalStagePoint"}},"offrampConcentration":{"type":"array","items":{"$ref":"#/components/schemas/LocalSurvivalOfframp"}},"topDisplacers":{"type":"array","items":{"$ref":"#/components/schemas/LocalSurvivalDisplacer"}},"journeys":{"type":"array","items":{"$ref":"#/components/schemas/LocalSurvivalJourney"}},"collectedAt":{"type":"string","format":"date-time"},"computationVersion":{"type":"string","example":"local-survival@2"},"methodology":{"type":"string"},"provenance":{"type":"object","required":["issuer","methodologyUrl","note"],"properties":{"issuer":{"type":"string","example":"Entidex"},"methodologyUrl":{"type":"string","format":"uri"},"note":{"type":"string"}}}}},"LocalSurvivalUnavailable":{"type":"object","required":["entityId","available","reason"],"properties":{"entityId":{"type":"string"},"available":{"type":"boolean","enum":[false]},"reason":{"type":"string","enum":["disabled","entity_out_of_scope","no_signal_yet"]}}},"BusinessProfileAxis":{"type":"object","required":["label","fragment"],"properties":{"label":{"type":"string"},"fragment":{"type":"string","description":"The plain buyer phrasing appended to narrow the search (never an internal key)."}}},"BusinessProfileOffering":{"type":"object","required":["id","name","useCase","decisionAxes"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"useCase":{"type":"string","nullable":true,"description":"The job a buyer solves with this offering."},"decisionAxes":{"type":"array","items":{"$ref":"#/components/schemas/BusinessProfileAxis"}}}},"BusinessProfile":{"type":"object","description":"The self-configuring profile that makes Recommendation Survival adapt to any business: its model, category, locality, offerings, and buyer decision-axes. Auto-detected once (cached) with a governed LLM-assist, or declared (declared fields win).","required":["entityId","available","model","category","locality","offerings","source","confidence","provenance","version","derivedAt"],"properties":{"entityId":{"type":"string"},"available":{"type":"boolean","enum":[true]},"model":{"type":"string","enum":["local_service","product","online_service","b2b_saas","marketplace","content_creator","other"]},"category":{"type":"string"},"locality":{"type":"string","nullable":true},"offerings":{"type":"array","items":{"$ref":"#/components/schemas/BusinessProfileOffering"}},"source":{"type":"string","enum":["detected","declared","hybrid"]},"confidence":{"type":"number","minimum":0,"maximum":1},"provenance":{"type":"object","required":["detectedFrom","llmAssisted","note"],"properties":{"detectedFrom":{"type":"array","items":{"type":"string"}},"llmAssisted":{"type":"boolean"},"note":{"type":"string"}}},"version":{"type":"string","example":"business-profile@1"},"derivedAt":{"type":"string","format":"date-time"}}},"BusinessProfileUnavailable":{"type":"object","required":["entityId","available","reason"],"properties":{"entityId":{"type":"string"},"available":{"type":"boolean","enum":[false]},"reason":{"type":"string","enum":["disabled","no_profile_yet"]}}},"DeclareOfferingsRequest":{"type":"object","description":"Declare a business's model and/or offerings (any subset; declared fields win over detection).","properties":{"model":{"type":"string","enum":["local_service","product","online_service","b2b_saas","marketplace","content_creator","other"]},"category":{"type":"string"},"locality":{"type":"string","nullable":true},"offerings":{"type":"array","items":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"useCase":{"type":"string","nullable":true},"axes":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"fragment":{"type":"string"}}}}}}},"note":{"type":"string"}}},"OfferingSurvival":{"type":"object","required":["offering","survivalRatePct","wilsonLowPct","wilsonHighPct","sampleJourneys","measuring","stageSurvival","offrampConcentration","topDisplacers","journeys"],"properties":{"offering":{"type":"object","required":["id","name","useCase"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"useCase":{"type":"string","nullable":true}}},"survivalRatePct":{"type":"number","nullable":true,"minimum":0,"maximum":100},"wilsonLowPct":{"type":"number","nullable":true},"wilsonHighPct":{"type":"number","nullable":true},"sampleJourneys":{"type":"integer"},"measuring":{"type":"boolean"},"stageSurvival":{"type":"array","items":{"$ref":"#/components/schemas/LocalSurvivalStagePoint"}},"offrampConcentration":{"type":"array","items":{"$ref":"#/components/schemas/LocalSurvivalOfframp"}},"topDisplacers":{"type":"array","items":{"$ref":"#/components/schemas/LocalSurvivalDisplacer"}},"journeys":{"type":"array","items":{"$ref":"#/components/schemas/LocalSurvivalJourney"}}}},"RecommendationSurvival":{"type":"object","description":"Business-adaptive Recommendation Survival: whether a business survives as the AI recommendation across a simulated buyer journey shaped by its Business Profile, decomposed per offering, with per-step AI replies, competitor mentions, cited sources, and the drop-out point.","required":["entityId","available","business","model","category","locality","survivalRatePct","wilsonLowPct","wilsonHighPct","sampleJourneys","measuring","stageSurvival","offrampConcentration","topDisplacers","offerings","collectedAt","computationVersion","methodology","provenance"],"properties":{"entityId":{"type":"string"},"available":{"type":"boolean","enum":[true]},"business":{"type":"string"},"model":{"type":"string","enum":["local_service","product","online_service","b2b_saas","marketplace","content_creator","other"]},"category":{"type":"string"},"locality":{"type":"string","nullable":true},"survivalRatePct":{"type":"number","nullable":true,"minimum":0,"maximum":100},"wilsonLowPct":{"type":"number","nullable":true},"wilsonHighPct":{"type":"number","nullable":true},"sampleJourneys":{"type":"integer"},"measuring":{"type":"boolean"},"stageSurvival":{"type":"array","items":{"$ref":"#/components/schemas/LocalSurvivalStagePoint"}},"offrampConcentration":{"type":"array","items":{"$ref":"#/components/schemas/LocalSurvivalOfframp"}},"topDisplacers":{"type":"array","items":{"$ref":"#/components/schemas/LocalSurvivalDisplacer"}},"offerings":{"type":"array","items":{"$ref":"#/components/schemas/OfferingSurvival"}},"collectedAt":{"type":"string","format":"date-time"},"computationVersion":{"type":"string","example":"recommendation-survival@1"},"methodology":{"type":"string"},"provenance":{"type":"object","required":["issuer","methodologyUrl","note"],"properties":{"issuer":{"type":"string"},"methodologyUrl":{"type":"string","format":"uri"},"note":{"type":"string"}}}}},"RecommendationSurvivalUnavailable":{"type":"object","required":["entityId","available","reason"],"properties":{"entityId":{"type":"string"},"available":{"type":"boolean","enum":[false]},"reason":{"type":"string","enum":["disabled","no_signal_yet"]}}},"SerpVsAiIndexContribution":{"type":"object","required":["label","value","weight"],"properties":{"label":{"type":"string"},"value":{"type":"integer","minimum":0,"maximum":100},"weight":{"type":"number","minimum":0,"maximum":1}}},"SerpVsAiSideRead":{"type":"object","required":["index","measured","contributions"],"properties":{"index":{"type":"integer","nullable":true,"minimum":0,"maximum":100,"description":"0–100 weighted composite; null when the side has no data on file."},"measured":{"type":"boolean"},"contributions":{"type":"array","items":{"$ref":"#/components/schemas/SerpVsAiIndexContribution"}}}},"SerpVsAiEngineMention":{"type":"object","required":["engine","maker","makerHref","mentioned","mentionPosition","recommendationLevel","citedUrlCount"],"properties":{"engine":{"type":"string","example":"ChatGPT"},"maker":{"type":"string","nullable":true,"example":"OpenAI"},"makerHref":{"type":"string","nullable":true,"example":"/entity/openai"},"mentioned":{"type":"boolean"},"mentionPosition":{"type":"integer","nullable":true},"recommendationLevel":{"type":"string","example":"primary"},"citedUrlCount":{"type":"integer"}}},"SerpVsAiKeyword":{"type":"object","required":["keyword","position","intent"],"properties":{"keyword":{"type":"string"},"position":{"type":"integer","minimum":1},"intent":{"type":"string","nullable":true}}},"SerpVsAiVerdict":{"type":"object","required":["gapClass","gap","headline","insight"],"properties":{"gapClass":{"type":"string","enum":["serp_dominant","ai_dominant","aligned","both_weak","both_strong"]},"gap":{"type":"integer","nullable":true,"description":"SERP − AI on 0–100 space; positive = SERP dominant. Null when one side unmeasured."},"headline":{"type":"string"},"insight":{"type":"string"}}},"SerpVsAiGoogleAiPresence":{"type":"object","nullable":true,"description":"Google AI Overviews / AI Mode answer presence from the latest stored Google AI answers run. A search-surface read alongside the five-engine table — never part of either composite index. Null when no run is on file.","required":["surfaces","collectedAt"],"properties":{"surfaces":{"type":"array","items":{"type":"object","required":["surface","label","queries","answersPresent","mentioned","ownDomainCited"],"properties":{"surface":{"type":"string","enum":["ai_overview","ai_mode"]},"label":{"type":"string","example":"Google AI Overviews"},"queries":{"type":"integer","minimum":0},"answersPresent":{"type":"integer","minimum":0},"mentioned":{"type":"integer","minimum":0,"description":"Answered queries where the entity was named."},"ownDomainCited":{"type":"integer","minimum":0,"description":"Answered queries citing the entity's own site as a source."}}}},"collectedAt":{"type":"string","format":"date-time"}}},"SerpVsAiAiOverviewCitations":{"type":"object","nullable":true,"description":"AI Overview citations for the entity's OWN domain (the reverse citation index, CANON 1.112): total keywords where the domain is cited as a source inside Google AI Overview answers, with the highest-volume cited keywords. A search-surface read — never part of either composite index. Null when no citation-index run is on file; totalKeywords 0 is a genuine reading (the domain is not an AI Overview source).","required":["domain","totalKeywords","capturedCount","topKeywords","collectedAt"],"properties":{"domain":{"type":"string","example":"tesla.com"},"totalKeywords":{"type":"integer","minimum":0,"description":"Total keywords where the domain is cited as an AI Overview source."},"capturedCount":{"type":"integer","minimum":0,"description":"Captured slice size behind topKeywords (rows are capped at collection)."},"topKeywords":{"type":"array","items":{"type":"object","required":["keyword","searchVolume","mainIntent","citedUrl"],"properties":{"keyword":{"type":"string"},"searchVolume":{"type":"integer","nullable":true,"description":"Monthly search volume estimate."},"mainIntent":{"type":"string","nullable":true,"description":"Dominant search intent (informational | commercial | transactional | navigational)."},"citedUrl":{"type":"string","nullable":true,"description":"The entity page the AI Overview cites for this keyword."}}}},"collectedAt":{"type":"string","format":"date-time"}}},"SerpVsAi":{"type":"object","description":"SERP vs AI presence comparison — traditional-search index vs AI-engine index, with a coded gap verdict + actionable insight. Coded reducer over the SEO/GEO audit + score snapshots + platformSignals + LLM Knowledge Accuracy + the latest Google AI answers + AI Overview citations runs. Zero LLM cost.","required":["entityId","available","computationVersion","serp","ai","verdict","engines","googleAi","aiOverviewCitations","llmKnowledgeAccuracyPct","topKeywords","lastObservedAt","methodology","provenance"],"properties":{"entityId":{"type":"string","description":"Canonical entx_xxxx id."},"available":{"type":"boolean","enum":[true]},"computationVersion":{"type":"string","example":"serp-vs-ai@1"},"serp":{"$ref":"#/components/schemas/SerpVsAiSideRead"},"ai":{"$ref":"#/components/schemas/SerpVsAiSideRead"},"verdict":{"$ref":"#/components/schemas/SerpVsAiVerdict"},"engines":{"type":"array","items":{"$ref":"#/components/schemas/SerpVsAiEngineMention"}},"googleAi":{"$ref":"#/components/schemas/SerpVsAiGoogleAiPresence"},"aiOverviewCitations":{"$ref":"#/components/schemas/SerpVsAiAiOverviewCitations"},"llmKnowledgeAccuracyPct":{"type":"integer","nullable":true,"minimum":0,"maximum":100},"topKeywords":{"type":"array","items":{"$ref":"#/components/schemas/SerpVsAiKeyword"}},"lastObservedAt":{"type":"string","format":"date-time","nullable":true},"methodology":{"type":"string"},"provenance":{"type":"object","required":["issuer","methodologyUrl","note"],"properties":{"issuer":{"type":"string","example":"Entidex"},"methodologyUrl":{"type":"string","format":"uri"},"note":{"type":"string"}}}}},"SerpVsAiUnavailable":{"type":"object","required":["entityId","available","reason"],"properties":{"entityId":{"type":"string"},"available":{"type":"boolean","enum":[false]},"reason":{"type":"string","enum":["no_signal_yet","entity_not_found","disabled"]}}},"GoogleAiCitation":{"type":"object","required":["domain","url","title","source","quotedText"],"properties":{"domain":{"type":"string","nullable":true},"url":{"type":"string","nullable":true},"title":{"type":"string","nullable":true},"source":{"type":"string","nullable":true},"quotedText":{"type":"string","nullable":true,"description":"Website text Google's AI used to generate the answer (when returned)."}}},"GoogleAiRead":{"type":"object","required":["surface","surfaceLabel","queryClass","query","answerPresent","answerText","entityMentioned","mentionOrder","sentimentScore","citations","citedDomains","entityDomainCited","competitorsMentioned","collectedAt"],"properties":{"surface":{"type":"string","enum":["ai_overview","ai_mode"]},"surfaceLabel":{"type":"string","example":"Google AI Mode"},"queryClass":{"type":"string","enum":["brand","evaluation","discovery"]},"query":{"type":"string"},"answerPresent":{"type":"boolean"},"answerText":{"type":"string"},"entityMentioned":{"type":"boolean"},"mentionOrder":{"type":"integer","nullable":true,"description":"1-based order of the entity's first mention among tracked names."},"sentimentScore":{"type":"integer","nullable":true,"minimum":0,"maximum":100,"description":"Sentiment around the entity's mentions (50 = neutral); null when not mentioned."},"citations":{"type":"array","items":{"$ref":"#/components/schemas/GoogleAiCitation"}},"citedDomains":{"type":"array","items":{"type":"string"}},"entityDomainCited":{"type":"boolean"},"competitorsMentioned":{"type":"array","items":{"type":"object","required":["slug","name","mentionOrder"],"properties":{"slug":{"type":"string","nullable":true},"name":{"type":"string"},"mentionOrder":{"type":"integer"}}}},"collectedAt":{"type":"string","format":"date-time"}}},"GoogleAiSurfaceSummary":{"type":"object","required":["queries","answersPresent","mentioned","ownDomainCited","meanSentiment","competitorsSeen"],"properties":{"queries":{"type":"integer"},"answersPresent":{"type":"integer"},"mentioned":{"type":"integer"},"ownDomainCited":{"type":"integer"},"meanSentiment":{"type":"integer","nullable":true,"minimum":0,"maximum":100},"competitorsSeen":{"type":"array","items":{"type":"string"}}}},"GoogleAiAnswers":{"type":"object","description":"What Google AI Overviews + Google AI Mode say about the entity per query class — generated-answer text, every citation (source/domain/URL/quoted text), mention + order, sentiment, competitor mentions, own-domain-cited. Deterministic extraction over stored runs; zero LLM cost. NOT a Score.","required":["entityId","available","computationVersion","collectedAt","runCount","aiOverview","aiMode","reads","methodology","provenance"],"properties":{"entityId":{"type":"string","description":"Canonical entx_xxxx id."},"available":{"type":"boolean","enum":[true]},"computationVersion":{"type":"string","example":"google-ai-answers@1"},"collectedAt":{"type":"string","format":"date-time"},"runCount":{"type":"integer","description":"Stored runs on file for the entity."},"aiOverview":{"$ref":"#/components/schemas/GoogleAiSurfaceSummary"},"aiMode":{"$ref":"#/components/schemas/GoogleAiSurfaceSummary"},"reads":{"type":"array","items":{"$ref":"#/components/schemas/GoogleAiRead"}},"methodology":{"type":"string"},"provenance":{"type":"object","required":["issuer","methodologyUrl","note"],"properties":{"issuer":{"type":"string","example":"Entidex"},"methodologyUrl":{"type":"string","format":"uri"},"note":{"type":"string"}}}}},"GoogleAiAnswersUnavailable":{"type":"object","required":["entityId","available","reason"],"properties":{"entityId":{"type":"string"},"available":{"type":"boolean","enum":[false]},"reason":{"type":"string","enum":["no_signal_yet","disabled"]}}},"GuestIntelligenceCastCommentQuote":{"type":"object","required":["text","likeCount","platformCommentId"],"properties":{"text":{"type":"string"},"authorHandle":{"type":"string","nullable":true},"likeCount":{"type":"integer"},"publishedAt":{"type":"string","format":"date-time","nullable":true},"platformCommentId":{"type":"string"}}},"GuestIntelligenceCastMember":{"type":"object","required":["entityId","entitySlug","entityName","role","sentiment","topPraise","topCriticism","claimVerdicts"],"properties":{"entityId":{"type":"string","example":"entx_jane_example"},"entitySlug":{"type":"string"},"entityName":{"type":"string"},"role":{"type":"string","enum":["owner","host","co_host","guest","panellist","mentioned","sponsor"]},"linkConfidence":{"type":"number","nullable":true},"sentiment":{"type":"object","required":["sampleSize","positivePct","negativePct"],"properties":{"sampleSize":{"type":"integer"},"positivePct":{"type":"integer","nullable":true},"negativePct":{"type":"integer","nullable":true}}},"topPraise":{"type":"array","items":{"$ref":"#/components/schemas/GuestIntelligenceCastCommentQuote"}},"topCriticism":{"type":"array","items":{"$ref":"#/components/schemas/GuestIntelligenceCastCommentQuote"}},"claimVerdicts":{"type":"array","items":{"type":"object","required":["claim","verdict"],"properties":{"claim":{"type":"string"},"verdict":{"type":"string","description":"Claim Truth Engine verdict (contradicted | disputed | died | corroborated | published | propagating | confirmed | surfaced)."},"verifiedPosition":{"type":"string","nullable":true},"evidenceDate":{"type":"string","format":"date-time","nullable":true}}}},"conflation":{"type":"object","nullable":true,"required":["reason","ambiguousComments"],"properties":{"reason":{"type":"string"},"ambiguousComments":{"type":"integer"}}}}},"GuestIntelligenceEpisodeCastRead":{"type":"object","required":["episodeId","platform","platformId","videoSentiment","totalComments","cast"],"properties":{"episodeId":{"type":"string"},"platform":{"type":"string"},"platformId":{"type":"string"},"title":{"type":"string","nullable":true},"publishedAt":{"type":"string","format":"date-time","nullable":true},"videoSentiment":{"type":"object","required":["sampleSize","positivePct","negativePct"],"properties":{"sampleSize":{"type":"integer"},"positivePct":{"type":"integer","nullable":true},"negativePct":{"type":"integer","nullable":true}}},"totalComments":{"type":"integer"},"cast":{"type":"array","items":{"$ref":"#/components/schemas/GuestIntelligenceCastMember"}}}},"GuestIntelligenceImpactRow":{"type":"object","required":["entityId","entitySlug","entityName","appearances"],"properties":{"entityId":{"type":"string"},"entitySlug":{"type":"string"},"entityName":{"type":"string"},"appearances":{"type":"integer"},"meanVisibilityDelta":{"type":"number","nullable":true},"meanSentimentDelta":{"type":"number","nullable":true},"latestAppearanceAt":{"type":"string","format":"date-time","nullable":true}}},"GuestIntelligence":{"type":"object","required":["entityId","available","computationVersion","computedAt","recentEpisodes","guestImpact","methodology","provenance"],"properties":{"entityId":{"type":"string"},"available":{"type":"boolean","enum":[true]},"computationVersion":{"type":"string","example":"guest-intelligence@1"},"computedAt":{"type":"string","format":"date-time"},"latestEpisode":{"$ref":"#/components/schemas/GuestIntelligenceEpisodeCastRead","nullable":true},"recentEpisodes":{"type":"array","items":{"$ref":"#/components/schemas/GuestIntelligenceEpisodeCastRead"}},"guestImpact":{"type":"object","required":["windowDays","totalAppearances","guests","topLifters","topDrags"],"properties":{"windowDays":{"type":"integer"},"totalAppearances":{"type":"integer"},"guests":{"type":"array","items":{"$ref":"#/components/schemas/GuestIntelligenceImpactRow"}},"topLifters":{"type":"array","items":{"$ref":"#/components/schemas/GuestIntelligenceImpactRow"}},"topDrags":{"type":"array","items":{"$ref":"#/components/schemas/GuestIntelligenceImpactRow"}}}},"methodology":{"type":"string"},"provenance":{"type":"object","required":["issuer","methodologyUrl","note"],"properties":{"issuer":{"type":"string","example":"Entidex"},"methodologyUrl":{"type":"string","format":"uri"},"note":{"type":"string"}}}}},"GuestIntelligenceUnavailable":{"type":"object","required":["entityId","available","reason"],"properties":{"entityId":{"type":"string"},"available":{"type":"boolean","enum":[false]},"reason":{"type":"string","enum":["no_episodes","no_signal_yet","entity_out_of_scope","disabled"]}}},"MiloAction":{"type":"object","required":["kind","priority","text","sourceSurfaces"],"properties":{"kind":{"type":"string","enum":["recommend","watch","contrast","brief-point","ask","flag"]},"priority":{"type":"string","enum":["urgent","high","medium","low"]},"text":{"type":"string"},"sourceSurfaces":{"type":"array","items":{"type":"string"}},"drillTo":{"type":"string","nullable":true}}},"MiloTalkingPoint":{"type":"object","required":["text","sourceSurfaces"],"properties":{"text":{"type":"string"},"sourceSurfaces":{"type":"array","items":{"type":"string"}},"note":{"type":"string","nullable":true}}},"MiloWatchSignal":{"type":"object","required":["metric","rationale","sourceSurfaces"],"properties":{"metric":{"type":"string"},"rationale":{"type":"string"},"sourceSurfaces":{"type":"array","items":{"type":"string"}},"triggerHint":{"type":"string","nullable":true}}},"MiloActionCard":{"type":"object","required":["entityId","entitySlug","role","lens","generatedAt","headline_claim","evidence_chain","so_what","confidence_disclosure","actions","metadata"],"properties":{"entityId":{"type":"string"},"entitySlug":{"type":"string"},"role":{"type":"string","enum":["sales","executive","communications","investor","competitor-analyst","journalist","founder","regulator","marketing"]},"lens":{"type":"string","enum":["situation-brief","meeting-prep","doing-business-with","competitor-view","truth-gap","crisis-watch","positioning","cohort-position","reputation-read"]},"generatedAt":{"type":"string","format":"date-time"},"headline_claim":{"type":"string"},"evidence_chain":{"type":"string"},"so_what":{"type":"string"},"confidence_disclosure":{"type":"string"},"actions":{"type":"array","items":{"$ref":"#/components/schemas/MiloAction"}},"talking_points":{"type":"array","items":{"$ref":"#/components/schemas/MiloTalkingPoint"},"nullable":true},"watch_signals":{"type":"array","items":{"$ref":"#/components/schemas/MiloWatchSignal"},"nullable":true},"metadata":{"type":"object","required":["observation_completeness","confidence_envelope","assessment_window_days","canonical_terms_used","validation_passed","persona","prompt_version"],"properties":{"observation_completeness":{"type":"number","minimum":0,"maximum":1},"confidence_envelope":{"type":"number","minimum":0,"maximum":1},"assessment_window_days":{"type":"integer"},"canonical_terms_used":{"type":"array","items":{"type":"string"}},"validation_passed":{"type":"boolean"},"persona":{"type":"object","required":["role","lens","bluntness","mode","energy","detail"],"properties":{"role":{"type":"string"},"lens":{"type":"string"},"bluntness":{"type":"integer","enum":[1,2,3]},"mode":{"type":"string","enum":["professional","personal","creator","executive"]},"energy":{"type":"string","enum":["low","medium","high"]},"detail":{"type":"string","enum":["brief","standard","deep"]}}},"prompt_version":{"type":"integer"}}}}},"MiloActionUnavailable":{"type":"object","required":["entityId","entitySlug","role","lens","available","reason"],"properties":{"entityId":{"type":"string"},"entitySlug":{"type":"string"},"role":{"type":"string"},"lens":{"type":"string"},"available":{"type":"boolean","enum":[false]},"reason":{"type":"string","enum":["disabled","no_signal_yet","lens_gate_not_met","tier","entity_out_of_scope","governor_paused"]},"detail":{"type":"string","nullable":true}}},"EnginePerEpisodeLag":{"type":"object","required":["engine","adoptionLagDays","firstMentionAt","snapshotsInspected"],"properties":{"engine":{"type":"string"},"maker":{"type":"string","nullable":true},"makerHref":{"type":"string","nullable":true},"adoptionLagDays":{"type":"integer","nullable":true},"firstMentionAt":{"type":"string","format":"date-time","nullable":true},"snapshotsInspected":{"type":"integer"}}},"EpisodeAdoptionRead":{"type":"object","required":["episodeId","platform","platformId","perEngine","enginesAdopted","enginesEvaluated"],"properties":{"episodeId":{"type":"string"},"platform":{"type":"string"},"platformId":{"type":"string"},"title":{"type":"string","nullable":true},"publishedAt":{"type":"string","format":"date-time","nullable":true},"perEngine":{"type":"array","items":{"$ref":"#/components/schemas/EnginePerEpisodeLag"}},"meanAdoptionLagDays":{"type":"number","nullable":true},"enginesAdopted":{"type":"integer"},"enginesEvaluated":{"type":"integer"}}},"EngineAdoptionSummary":{"type":"object","required":["engine","episodesAdopted","episodesEvaluated"],"properties":{"engine":{"type":"string"},"maker":{"type":"string","nullable":true},"makerHref":{"type":"string","nullable":true},"episodesAdopted":{"type":"integer"},"episodesEvaluated":{"type":"integer"},"meanAdoptionLagDays":{"type":"number","nullable":true},"medianAdoptionLagDays":{"type":"number","nullable":true}}},"EpisodeAdoptionLag":{"type":"object","required":["entityId","available","computationVersion","computedAt","windowDays","episodes","perEngine","methodology","provenance"],"properties":{"entityId":{"type":"string"},"available":{"type":"boolean","enum":[true]},"computationVersion":{"type":"string","example":"episode-adoption-lag@1"},"computedAt":{"type":"string","format":"date-time"},"windowDays":{"type":"integer"},"episodes":{"type":"array","items":{"$ref":"#/components/schemas/EpisodeAdoptionRead"}},"perEngine":{"type":"array","items":{"$ref":"#/components/schemas/EngineAdoptionSummary"}},"methodology":{"type":"string"},"provenance":{"type":"object","required":["issuer","methodologyUrl","note"],"properties":{"issuer":{"type":"string"},"methodologyUrl":{"type":"string","format":"uri"},"note":{"type":"string"}}}}},"EpisodeAdoptionLagUnavailable":{"type":"object","required":["entityId","available","reason"],"properties":{"entityId":{"type":"string"},"available":{"type":"boolean","enum":[false]},"reason":{"type":"string","enum":["no_episodes","no_signal_yet","entity_out_of_scope","disabled"]}}},"YouTubeIntelligence":{"type":"object","required":["entityId","entitySlug","available","windowDays","channel","sentimentTimeline","anomalyCount","episodes","topQuestions","intentSummary","episodeTopics","guestTopics"],"properties":{"entityId":{"type":"string"},"entitySlug":{"type":"string"},"available":{"type":"boolean","enum":[true]},"windowDays":{"type":"integer","example":30},"channel":{"type":"object","nullable":true,"properties":{"subscriberCount":{"type":"integer","nullable":true},"totalViewCount":{"type":"integer","nullable":true},"videoCount":{"type":"integer","nullable":true},"fetchedAt":{"type":"string","format":"date-time","nullable":true}}},"sentimentTimeline":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date"},"total":{"type":"integer"},"positive":{"type":"integer"},"neutral":{"type":"integer"},"negative":{"type":"integer"},"isAnomaly":{"type":"boolean"}}}},"anomalyCount":{"type":"integer"},"episodes":{"type":"array","items":{"type":"object","properties":{"episodeId":{"type":"string"},"platformId":{"type":"string"},"title":{"type":"string","nullable":true},"publishedAt":{"type":"string","format":"date-time","nullable":true},"totalComments":{"type":"integer"},"positive":{"type":"integer"},"neutral":{"type":"integer"},"negative":{"type":"integer"},"positiveRatio":{"type":"number"},"intentDistribution":{"type":"object","additionalProperties":{"type":"integer"}}}}},"topQuestions":{"type":"array","items":{"type":"object","properties":{"commentText":{"type":"string"},"authorHandle":{"type":"string","nullable":true},"publishedAt":{"type":"string","format":"date-time","nullable":true},"likeCount":{"type":"integer"},"replyCount":{"type":"integer"},"episodeTitle":{"type":"string","nullable":true}}}},"intentSummary":{"type":"object","properties":{"total":{"type":"integer"},"distribution":{"type":"object","additionalProperties":{"type":"integer"}},"distributionPct":{"type":"object","additionalProperties":{"type":"number"}},"topIntent":{"type":"string"}}},"episodeTopics":{"type":"array","items":{"type":"object","properties":{"episodeId":{"type":"string"},"platformId":{"type":"string"},"title":{"type":"string","nullable":true},"topics":{"type":"array","items":{"$ref":"#/components/schemas/YouTubeTopic"}},"entityMentionDensity":{"type":"number"},"wordCount":{"type":"integer"}}}},"guestTopics":{"type":"array","items":{"type":"object","properties":{"guestSlug":{"type":"string"},"guestName":{"type":"string"},"episodeCount":{"type":"integer"},"topics":{"type":"array","items":{"$ref":"#/components/schemas/YouTubeTopic"}},"avgEntityMentionDensity":{"type":"number"}}}}}},"YouTubeTopic":{"type":"object","required":["topic","count","density"],"properties":{"topic":{"type":"string"},"count":{"type":"integer"},"density":{"type":"number"}}},"YouTubeIntelligenceUnavailable":{"type":"object","required":["entityId","available","reason"],"properties":{"entityId":{"type":"string"},"available":{"type":"boolean","enum":[false]},"reason":{"type":"string","enum":["no_footprint","no_signal_yet","disabled"]}}},"KnowledgeStatementProvenance":{"type":"object","required":["issuer","issuerId","statementUrl","methodologyUrl","license","generatedAt","note","proof"],"properties":{"issuer":{"type":"string","example":"Entidex"},"issuerId":{"type":"string","example":"did:web:entidex.com"},"statementUrl":{"type":"string","format":"uri"},"methodologyUrl":{"type":"string","format":"uri"},"license":{"type":"string","format":"uri"},"generatedAt":{"type":"string","format":"date-time"},"note":{"type":"string"},"proof":{"type":"object","nullable":true,"description":"JsonWebSignature2020 proof attached when a signing key is configured.","properties":{"type":{"type":"string","example":"JsonWebSignature2020"},"contentHash":{"type":"string","description":"SHA-256 hash of the canonicalised statement (proof field excluded)."},"jws":{"type":"string","description":"Ed25519 JWS over the content hash."},"verificationMethod":{"type":"string","example":"did:web:entidex.com#key-1"}}}}},"KnowledgeStatementEntity":{"type":"object","required":["id","slug","canonicalName","type","description","sameAs","identifiers"],"properties":{"id":{"type":"string","description":"Canonical entx_xxxx id."},"slug":{"type":"string"},"canonicalName":{"type":"string"},"type":{"type":"string","description":"Entity primary type (Schema.org-aligned)."},"description":{"type":"string","nullable":true},"sameAs":{"type":"array","items":{"type":"string","format":"uri"},"description":"schema.org sameAs — URLs only. v2.0 fix: bare social handles / channel IDs no longer leak in here; they are exposed via `identifiers.altNames` / `identifiers.youtubeChannelId`."},"identifiers":{"type":"object","properties":{"wikidataQid":{"type":"string","nullable":true},"website":{"type":"string","nullable":true},"altNames":{"type":"array","items":{"type":"string"},"description":"v2.0 — non-URL alternate names / handles. Omitted when empty."},"youtubeChannelId":{"type":"string","nullable":true,"description":"v2.0 — YouTube channel id (UCxxx) when the entity has one. Omitted otherwise."}}}}},"Authority":{"type":"string","enum":["high","medium","low"],"description":"Authority band derived from a verified fact's confidence: high ≥85 (Wikidata / platform metadata), medium ≥65 (Entidex pipeline), low <65. Used by knowledgeGap.contradictions[] to distinguish real defects (verified value is high-authority) from monitored divergences (alternate_claim, verified value is lower-authority)."},"VerifiedRecordFact":{"allOf":[{"$ref":"#/components/schemas/VerifiedFact"},{"type":"object","required":["authority"],"properties":{"authority":{"$ref":"#/components/schemas/Authority"}}}]},"VerifiedRecord":{"type":"object","description":"schemaVersion 2.0 — the signed, tamper-evident record of the entity's verified facts. Split out from the mixed v1.x layout so crawlers / RAG can cache it indefinitely (only invalidates when facts change), separate from the fast-ticking `knowledgeGap`.","required":["asOf","contentHash","facts"],"properties":{"asOf":{"type":"string","format":"date-time","description":"Most recent `asOf` across included facts."},"contentHash":{"type":"string","description":"`sha256:<hex>` over canonicalised `{ asOf, facts }`. Recompute locally to detect drift.","example":"sha256:10bd8ef4ab8b6c9001c7c072f2a440f69673b8f1389406e4932aa64585e421a3"},"facts":{"type":"array","items":{"$ref":"#/components/schemas/VerifiedRecordFact"}}}},"KnowledgeGapAccuracy":{"type":"object","description":"Accuracy summary in v2.0 shape — honest excluded counts, percent-space interval, and a configurable authority floor.","required":["decidable","matches","contradictions","pct","excluded","confidenceFloor","interval95Pct","computationVersion"],"properties":{"decidable":{"type":"integer","description":"matches + contradictions — the accuracy denominator."},"matches":{"type":"integer"},"contradictions":{"type":"integer"},"pct":{"type":"integer","nullable":true,"minimum":0,"maximum":100},"excluded":{"type":"object","required":["coverageGaps","duplicates"],"properties":{"coverageGaps":{"type":"integer","description":"Rows excluded — engine made no claim (coverage gap)."},"duplicates":{"type":"integer","description":"Rows excluded — same defect surfaced across snapshots."}}},"confidenceFloor":{"type":"integer","description":"Minimum verified-authority confidence that fed the calculation. 0 = all facts; 65 = medium+; 85 = high only.","minimum":0,"maximum":100},"interval95Pct":{"type":"array","nullable":true,"items":{"type":"number"},"minItems":2,"maxItems":2,"description":"95% Wilson interval on the accuracy proportion, in PERCENTAGE space (0..100)."},"computationVersion":{"type":"string","example":"llm-knowledge-accuracy@1"}}},"KnowledgeGapPerEngine":{"type":"object","description":"Per-engine slice of the accuracy figure — the biggest analytical insight the v1.x flat shape threw away.","required":["engine","maker","makerHref","decidable","matches","pct"],"properties":{"engine":{"type":"string","example":"ChatGPT"},"maker":{"type":"string","example":"OpenAI"},"makerHref":{"type":"string","example":"/entity/openai"},"decidable":{"type":"integer"},"matches":{"type":"integer"},"pct":{"type":"integer","nullable":true,"minimum":0,"maximum":100}}},"SourceExcerpt":{"type":"object","description":"Per-engine audit trail pointer — stable numeric snapshot id + timestamp for one engine's occurrence of a claim. Public-safe: no raw model text (CANON §7 forbids exposing prompt echoes / provider names / probe mechanics); an admin drill-down joins snapshotId to the full response.","required":["engine","snapshotId","observedAt"],"properties":{"engine":{"type":"string","example":"ChatGPT"},"snapshotId":{"type":"integer","description":"entity_knowledge_snapshots.snapshot_id."},"observedAt":{"type":"string","format":"date-time"}}},"KnowledgeGapContradiction":{"type":"object","description":"One deduped contradiction — one row per unique (field, aiClaim) pair, aggregated across engines and probe runs.","required":["field","aiClaim","verifiedValue","relationship","authorityOfVerified","engines","firstSeen","lastSeen","occurrences"],"properties":{"field":{"type":"string"},"aiClaim":{"type":"string"},"verifiedValue":{"type":"string","nullable":true},"relationship":{"type":"string","enum":["contradiction","alternate_claim"],"description":"`contradiction` = engine disagrees with a high-authority verified value (real defect). `alternate_claim` = engine disagrees with a medium/low-authority value (monitored divergence, not necessarily wrong)."},"authorityOfVerified":{"$ref":"#/components/schemas/Authority"},"engines":{"type":"array","items":{"type":"string"},"description":"Canonical engine labels that emit this claim."},"firstSeen":{"type":"string","format":"date-time"},"lastSeen":{"type":"string","format":"date-time"},"occurrences":{"type":"integer","description":"Underlying probe-run rows collapsed into this deduped record."},"sourceExcerpts":{"type":"array","description":"Optional. One audit-trail pointer per engine (latest snapshot for that engine's occurrence). Omitted when the underlying rows carry no snapshot ids.","items":{"$ref":"#/components/schemas/SourceExcerpt"}}}},"KnowledgeGapCoverageGap":{"type":"object","description":"One field the verified record holds but the listed engines have no answer for. Not a defect — an unclosed coverage gap.","required":["field","verifiedValue","engines"],"properties":{"field":{"type":"string"},"verifiedValue":{"type":"string","nullable":true},"engines":{"type":"array","items":{"type":"string"}}}},"KnowledgeGapAlternateNarrative":{"type":"object","description":"A lower-authority observation that diverges from the verified record without contradicting it — surfaced for context.","required":["field","alternateValue","source","confidence","asOf","note"],"properties":{"field":{"type":"string"},"alternateValue":{"type":"string"},"source":{"type":"string"},"confidence":{"type":"integer","minimum":0,"maximum":100},"asOf":{"type":"string","format":"date-time","nullable":true},"note":{"type":"string"}}},"KnowledgeGapTrend":{"type":"object","description":"Direction of accuracy movement vs a prior window.","required":["prior","delta","direction"],"properties":{"prior":{"type":"object","nullable":true,"required":["asOf","pct"],"properties":{"asOf":{"type":"string","format":"date-time"},"pct":{"type":"integer","nullable":true,"minimum":0,"maximum":100}}},"delta":{"type":"integer","nullable":true,"description":"Percentage-point delta vs prior."},"direction":{"type":"string","enum":["improving","declining","stable"],"nullable":true}}},"KnowledgeGap":{"type":"object","description":"schemaVersion 2.0 — the tick-fast knowledge-gap report. Composed from the same probe data as v1.x `corrections[]` but deduped, split into contradictions vs coverage gaps, and enriched with per-engine attribution. Consumers reading this section can bypass `corrections[]` entirely.","required":["asOf","accuracy","perEngine","contradictions","coverageGaps","alternateNarratives"],"properties":{"asOf":{"type":"string","format":"date-time"},"accuracy":{"$ref":"#/components/schemas/KnowledgeGapAccuracy"},"perEngine":{"type":"array","items":{"$ref":"#/components/schemas/KnowledgeGapPerEngine"}},"contradictions":{"type":"array","items":{"$ref":"#/components/schemas/KnowledgeGapContradiction"}},"coverageGaps":{"type":"array","items":{"$ref":"#/components/schemas/KnowledgeGapCoverageGap"}},"alternateNarratives":{"type":"array","items":{"$ref":"#/components/schemas/KnowledgeGapAlternateNarrative"}},"trend":{"$ref":"#/components/schemas/KnowledgeGapTrend"}}},"KnowledgeStatement":{"type":"object","description":"Entity Knowledge Statement — machine-readable declaration of an entity's VERIFIED reality plus explicit CORRECTIONS to what AI engines currently get wrong. Issued by Entidex; intended for AI systems to reconcile against. schemaVersion 2.0 added optional `verifiedRecord` (signed, cache-friendly record + contentHash + authority bands) and `knowledgeGap` (deduped, split into contradictions vs coverage gaps, per-engine attribution). schemaVersion 1.1 added optional `confirmations[]`. ALL v1.x fields (`verifiedFacts`, `corrections`, `narrative`, `accuracy`) remain populated for back-compat.","required":["entity","verifiedFacts","corrections","narrative","accuracy","provenance"],"properties":{"entity":{"$ref":"#/components/schemas/KnowledgeStatementEntity"},"verifiedFacts":{"type":"array","items":{"$ref":"#/components/schemas/VerifiedFact"}},"confirmations":{"type":"array","description":"Optional. Lower-authority observations whose values were superseded by a higher-authority record. Omitted when empty for 1.0 back-compat.","items":{"$ref":"#/components/schemas/Confirmation"}},"corrections":{"type":"array","items":{"$ref":"#/components/schemas/KnowledgeCorrection"}},"narrative":{"type":"array","items":{"$ref":"#/components/schemas/NarrativeCorrection"}},"accuracy":{"$ref":"#/components/schemas/KnowledgeAccuracy"},"verifiedRecord":{"allOf":[{"$ref":"#/components/schemas/VerifiedRecord"}],"description":"schemaVersion 2.0. Omitted when there are no verified facts."},"knowledgeGap":{"allOf":[{"$ref":"#/components/schemas/KnowledgeGap"}],"description":"schemaVersion 2.0. Omitted when the entity has no knowledge-probe history."},"provenance":{"$ref":"#/components/schemas/KnowledgeStatementProvenance"},"schemaVersion":{"type":"string","example":"2.0","description":"Additive semver — each bump extends, never breaks."},"completeness":{"type":"object","nullable":true,"description":"Per-LLM completeness snapshot from the latest self-check sweep.","properties":{"lastComputedAt":{"type":"string","format":"date-time"},"perLlm":{"type":"array","items":{"type":"object","properties":{"engine":{"type":"string"},"completenessPct":{"type":"number","nullable":true},"weightedCompletenessPct":{"type":"number","nullable":true},"truthGapPct":{"type":"number","nullable":true}}}},"topGaps":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"importance":{"type":"number"}}}}}}}},"GroundingPacketFact":{"type":"object","required":["field","value","source","confidence","asOf"],"properties":{"field":{"type":"string"},"value":{"type":"string"},"source":{"type":"string","description":"Provenance label of the verified source (e.g. \"Wikidata\")."},"confidence":{"type":"integer","minimum":0,"maximum":100},"asOf":{"type":"string","format":"date-time","nullable":true}}},"GroundingPacketCorrection":{"type":"object","required":["field","commonAiClaim","verifiedValue","source","status","asOf"],"properties":{"field":{"type":"string"},"commonAiClaim":{"type":"string","nullable":true,"description":"What AI engines commonly claim (null for an ai_unaware gap)."},"verifiedValue":{"type":"string","nullable":true},"source":{"type":"string"},"status":{"type":"string","enum":["contradiction","ai_unaware"]},"asOf":{"type":"string","format":"date-time","nullable":true}}},"GroundingPacket":{"type":"object","description":"Grounding Packet — the named, free-tier developer packaging of the Entity Knowledge Statement: one small, deterministic per-entity grounding payload (verified facts with provenance + corrections to common AI claims + Ed25519-signed provenance) fetched at the top of an agent/RAG workflow. Deterministic: the same underlying record always projects to an identical payload.","required":["packetVersion","entity","facts","corrections","accuracy","provenance","links"],"properties":{"packetVersion":{"type":"string","example":"1.0"},"entity":{"type":"object","required":["id","slug","canonicalName","type","description","identifiers","sameAs"],"properties":{"id":{"type":"string","description":"Canonical entx_xxxx id."},"slug":{"type":"string"},"canonicalName":{"type":"string"},"type":{"type":"string"},"description":{"type":"string","nullable":true},"identifiers":{"type":"object","properties":{"wikidataQid":{"type":"string","nullable":true},"website":{"type":"string","nullable":true}}},"sameAs":{"type":"array","items":{"type":"string"},"description":"Cross-referenced identity URLs, sorted."}}},"facts":{"type":"array","items":{"$ref":"#/components/schemas/GroundingPacketFact"},"description":"Verified facts, one per canonical field, sorted by field."},"corrections":{"type":"array","items":{"$ref":"#/components/schemas/GroundingPacketCorrection"},"description":"Corrections to common AI claims, sorted by field."},"accuracy":{"type":"object","properties":{"pct":{"type":"integer","nullable":true,"minimum":0,"maximum":100},"matches":{"type":"integer"},"mismatches":{"type":"integer"},"evaluated":{"type":"integer"}}},"provenance":{"$ref":"#/components/schemas/KnowledgeStatementProvenance"},"links":{"type":"object","description":"Sibling machine-readable surfaces over the same record.","properties":{"knowledgeMarkdown":{"type":"string"},"knowledgeJsonLd":{"type":"string"},"groundTruthApi":{"type":"string"}}}}},"GroundingMetadataProjection":{"type":"object","description":"GroundingMetadata-shaped projection of the Grounding Packet (?format=grounding-metadata): groundingChunks / groundingSupports over a synthesized fact digest, mirroring Google Vertex grounding field names so Vertex-shaped pipelines consume the packet without adapter code.","required":["packetVersion","entity","text","groundingChunks","groundingSupports","provenance"],"properties":{"packetVersion":{"type":"string","example":"1.0"},"entity":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"canonicalName":{"type":"string"}}},"text":{"type":"string","description":"The grounded fact digest the supports index into (one fact line per support)."},"groundingChunks":{"type":"array","items":{"type":"object","properties":{"web":{"type":"object","properties":{"uri":{"type":"string"},"title":{"type":"string"}}}}}},"groundingSupports":{"type":"array","items":{"type":"object","properties":{"segment":{"type":"object","properties":{"startIndex":{"type":"integer"},"endIndex":{"type":"integer"},"text":{"type":"string"}}},"groundingChunkIndices":{"type":"array","items":{"type":"integer"}},"confidenceScores":{"type":"array","items":{"type":"number","minimum":0,"maximum":1}}}}},"provenance":{"$ref":"#/components/schemas/KnowledgeStatementProvenance"}}},"ErrorEnvelope":{"type":"object","required":["data","meta","errors"],"properties":{"data":{"nullable":true},"meta":{"$ref":"#/components/schemas/ResponseMeta"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/ApiError"}}}}},"responses":{"Unauthenticated":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"RateLimited":{"description":"Per-key rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"NotFound":{"description":"Entity or resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"paths":{"/discovery/search":{"get":{"tags":["Layer 0 — Discovery"],"summary":"Free-text discovery search across all surfaces.","parameters":[{"name":"query","in":"query","required":true,"schema":{"type":"string"}},{"name":"surfaces","in":"query","schema":{"type":"string"},"description":"Comma-separated surface list, or \"all\"."},{"name":"window","in":"query","schema":{"type":"string","enum":["1d","7d","30d","90d","365d","all"]}},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":200}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Observation"}},"meta":{"$ref":"#/components/schemas/ResponseMeta"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/ApiError"}}}}}}}}}},"/discovery/entity/{entityId}/observations":{"get":{"tags":["Layer 0 — Discovery"],"summary":"Observations scoped to a resolved entity.","parameters":[{"name":"entityId","in":"path","required":true,"schema":{"type":"string","example":"entx_8f3a2b1c9d4e"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Observation"}},"meta":{"$ref":"#/components/schemas/ResponseMeta"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/ApiError"}}}}}}}}}},"/discovery/by-url":{"get":{"tags":["Layer 0 — Discovery"],"summary":"Reverse lookup — given a URL, return related observations.","parameters":[{"name":"url","in":"query","required":true,"schema":{"type":"string","format":"uri"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Observation"}},"meta":{"$ref":"#/components/schemas/ResponseMeta"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/ApiError"}}}}}}}}}},"/entities/{entityId}":{"get":{"tags":["Layer 1 — Profile"],"summary":"Full Entity Intelligence View.","description":"Tier gate: free. The response shape widens with tier — `free` keys receive the lite projection (PublicEntityLite: identity + identifiers + cached headline signals), `layer_1_profile`+ receive the full Entity (claims, completeness, neighbourhood).","parameters":[{"name":"entityId","in":"path","required":true,"schema":{"type":"string","example":"entx_8f3a2b1c9d4e"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"oneOf":[{"$ref":"#/components/schemas/Entity"},{"$ref":"#/components/schemas/PublicEntityLite"}]},"meta":{"$ref":"#/components/schemas/ResponseMeta"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/ApiError"}}}}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/entities/resolve":{"get":{"tags":["Layer 1 — Profile"],"summary":"Resolve a free-text query to a single canonical entity.","description":"Tier gate: free. The response shape widens with tier — `free` keys receive the lite projection (PublicEntityLite: identity + identifiers + cached headline signals), `layer_1_profile`+ receive the full Entity (claims, completeness, neighbourhood).","parameters":[{"name":"query","in":"query","required":false,"schema":{"type":"string"},"description":"Free-text query. Either `query` or `q` is required."},{"name":"q","in":"query","required":false,"schema":{"type":"string"},"description":"Alias of `query`."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"oneOf":[{"$ref":"#/components/schemas/Entity"},{"$ref":"#/components/schemas/PublicEntityLite"}]},"meta":{"$ref":"#/components/schemas/ResponseMeta"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/ApiError"}}}}}}},"422":{"$ref":"#/components/responses/NotFound"}}}},"/entities/resolve/batch":{"post":{"tags":["Layer 1 — Profile"],"summary":"Bulk reconciliation — resolve many strings with confidence bands.","description":"Billed per input. Results are positionally aligned with `inputs`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["inputs"],"properties":{"inputs":{"type":"array","items":{"type":"string"},"maxItems":100,"minItems":1}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ReconciliationResult"}},"meta":{"$ref":"#/components/schemas/ResponseMeta"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/ApiError"}}}}}}}}}},"/creators/resolve":{"get":{"tags":["Layer 1 — Profile"],"summary":"Creator Resolution — resolve a name or profile link to one canonical creator + verified handles.","description":"Tier gate: layer_1_profile. A creator/podcast NAME or any one profile LINK in → the single canonical creator: every cross-verified platform handle (with provenance + confidence), the headline signals, and the signed-record link. Three-state `band`: confirmed / ambiguous (incl. Wikidata namesakes) / not_found. The developer twin of the keyless /api/creator-resolution tool.","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"},"description":"A creator/podcast name, or any one social profile URL. `query` is an accepted alias."}],"responses":{"200":{"description":"The resolve-and-show result.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"band":{"type":"string","enum":["confirmed","ambiguous","not_found"]},"query":{"type":"string"},"inputKind":{"type":"string","enum":["name","link"]},"creator":{"type":"object","nullable":true,"description":"Present when band = confirmed: the one canonical creator with every verified handle."},"candidates":{"type":"array","items":{"type":"object"},"description":"Present when band = ambiguous: the disambiguation picker (tracked matches + Wikidata namesakes)."}},"required":["band","query","inputKind"]}}}}}}}}},"/entities/{entityId}/claims":{"get":{"tags":["Layer 1 — Profile"],"summary":"Claims for an entity.","parameters":[{"name":"entityId","in":"path","required":true,"schema":{"type":"string","example":"entx_8f3a2b1c9d4e"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Claim"}},"meta":{"$ref":"#/components/schemas/ResponseMeta"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/ApiError"}}}}}}}}}},"/entities/{entityId}/ground-truth":{"get":{"tags":["Layer 1 — Profile"],"summary":"Entity Knowledge Statement — verified record plus corrections to common AI claims. Public crawlable variants (markdown / JSON-LD) at /entity/{slug}/knowledge.","parameters":[{"name":"entityId","in":"path","required":true,"schema":{"type":"string","example":"entx_8f3a2b1c9d4e"}}],"responses":{"200":{"description":"Entity Knowledge Statement (schemaVersion 1.1).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeStatement"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/entities/{entityId}/grounding-packet":{"get":{"tags":["Layer 0 — Discovery"],"summary":"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.","parameters":[{"name":"entityId","in":"path","required":true,"schema":{"type":"string","example":"entx_8f3a2b1c9d4e"}},{"name":"format","in":"query","required":false,"schema":{"type":"string","enum":["grounding-metadata"]},"description":"Omit for the canonical packet; grounding-metadata for the Vertex-shaped projection."}],"responses":{"200":{"description":"Grounding Packet (default) or the GroundingMetadata-shaped projection.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/GroundingPacket"},{"$ref":"#/components/schemas/GroundingMetadataProjection"}]}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/entities/{entityId}/knowledge-accuracy":{"get":{"tags":["Layer 1 — Profile"],"summary":"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.","parameters":[{"name":"entityId","in":"path","required":true,"schema":{"type":"string","example":"entx_8f3a2b1c9d4e"}}],"responses":{"200":{"description":"LLM Knowledge Accuracy, or { available: false } when the entity has no knowledge probes yet.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/LlmKnowledgeAccuracy"},{"$ref":"#/components/schemas/LlmKnowledgeAccuracyUnavailable"}]}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/entities/{entityId}/grounding-check":{"post":{"tags":["Layer 1 — Profile"],"summary":"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.","parameters":[{"name":"entityId","in":"path","required":true,"schema":{"type":"string","example":"entx_8f3a2b1c9d4e"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GroundingCheckRequest"}}}},"responses":{"200":{"description":"Grounding Check verdicts, or { available: false } when the feature is disabled or the entity has no verified record.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/GroundingCheck"},{"$ref":"#/components/schemas/GroundingCheckUnavailable"}]}}}},"400":{"description":"Missing, empty, or over-length `statement` (max 1000 characters)."},"404":{"$ref":"#/components/responses/NotFound"}}}},"/entities/{entityId}/episode-adoption-lag":{"get":{"tags":["Layer 1 — Profile"],"summary":"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.","parameters":[{"name":"entityId","in":"path","required":true,"schema":{"type":"string","example":"entx_8f3a2b1c9d4e"}}],"responses":{"200":{"description":"Adoption Lag payload, or { available: false } when the entity has no episodes yet or no snapshot on file has named any episode.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/EpisodeAdoptionLag"},{"$ref":"#/components/schemas/EpisodeAdoptionLagUnavailable"}]}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/entities/{entityId}/youtube-intelligence":{"get":{"tags":["Layer 1 — Profile"],"summary":"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.","parameters":[{"name":"entityId","in":"path","required":true,"schema":{"type":"string","example":"entx_8f3a2b1c9d4e"}}],"responses":{"200":{"description":"YouTube Intelligence payload, or { available: false } when the entity has no YouTube footprint yet.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/YouTubeIntelligence"},{"$ref":"#/components/schemas/YouTubeIntelligenceUnavailable"}]}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/entities/{entityId}/recommendation-potential":{"get":{"tags":["Layer 1 — Profile"],"summary":"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.","parameters":[{"name":"entityId","in":"path","required":true,"schema":{"type":"string","example":"entx_8f3a2b1c9d4e"}}],"responses":{"200":{"description":"AI Recommendation Potential, or { available: false } when the entity has no Decision Survival probes yet.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/RecommendationPotential"},{"$ref":"#/components/schemas/RecommendationPotentialUnavailable"}]}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/entities/{entityId}/local-survival":{"get":{"tags":["Layer 1 — Profile"],"summary":"Local Decision Survival — whether a local business survives as Google's AI recommendation across a simulated near-me buyer journey (a broad \"best {category} in {locality}\" search that narrows over follow-ups into a forced pick). Per journey: the verbatim AI reply excerpt at each step, whether the business is named, competitor mentions, cited sources, and — when it drops out — which follow-up dropped it and who took the slot. Plus the survival rate (95% Wilson interval), the stage-survival curve, offramp concentration, and top displacers. Deterministic zero-LLM extraction; below the minimum-evidence floor the rate reads \"Measuring\".","parameters":[{"name":"entityId","in":"path","required":true,"schema":{"type":"string","example":"entx_8f3a2b1c9d4e"}}],"responses":{"200":{"description":"Local Decision Survival, or { available: false } for non-local / unmeasured entities.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/LocalSurvival"},{"$ref":"#/components/schemas/LocalSurvivalUnavailable"}]}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/entities/{entityId}/business-profile":{"get":{"tags":["Layer 1 — Profile"],"summary":"Business Profile — the self-configuring layer for Recommendation Survival: the business's model (local_service / product / online_service / b2b_saas / marketplace / content_creator), category, locality, offerings, and the buyer decision-axes each offering narrows on. Auto-detects once (cached) when none exists — deterministic-first with a one-time governed LLM-assist. Read first to run the right recommendation-survival journey for any business.","parameters":[{"name":"entityId","in":"path","required":true,"schema":{"type":"string","example":"entx_8f3a2b1c9d4e"}}],"responses":{"200":{"description":"The derived/declared business profile, or { available: false }.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/BusinessProfile"},{"$ref":"#/components/schemas/BusinessProfileUnavailable"}]}}}},"404":{"$ref":"#/components/responses/NotFound"}}},"post":{"tags":["Layer 1 — Profile"],"summary":"Declare a business's model and/or offerings so Recommendation Survival adapts to what it actually sells (declared fields win over auto-detection). Operator/owner-authoritative (admin-scoped); a self-serve customer path is gated on the entity-ownership model.","parameters":[{"name":"entityId","in":"path","required":true,"schema":{"type":"string","example":"entx_8f3a2b1c9d4e"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeclareOfferingsRequest"}}}},"responses":{"200":{"description":"The effective profile after the declaration (declared over detected).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessProfile"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/entities/{entityId}/recommendation-survival":{"get":{"tags":["Layer 1 — Profile"],"summary":"Recommendation Survival — the business-adaptive generalization of Local Decision Survival: whether a business survives as the AI recommendation across a simulated buyer journey shaped by its Business Profile (near-me for local, \"best {product} for {job}\" for products, vs-alternatives for online/B2B), decomposed per offering — with the verbatim AI reply at each step, competitor mentions, cited sources, and the drop-out point, plus the survival rate (95% Wilson), stage-survival curve, offramp concentration, and top displacers. Deterministic zero-LLM read.","parameters":[{"name":"entityId","in":"path","required":true,"schema":{"type":"string","example":"entx_8f3a2b1c9d4e"}}],"responses":{"200":{"description":"Recommendation Survival, or { available: false } for unmeasured entities.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/RecommendationSurvival"},{"$ref":"#/components/schemas/RecommendationSurvivalUnavailable"}]}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/entities/{entityId}/serp-vs-ai":{"get":{"tags":["Layer 1 — Profile"],"summary":"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.","parameters":[{"name":"entityId","in":"path","required":true,"schema":{"type":"string","example":"entx_8f3a2b1c9d4e"}}],"responses":{"200":{"description":"SERP vs AI comparison, or { available: false } when the entity has no signals on file yet.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/SerpVsAi"},{"$ref":"#/components/schemas/SerpVsAiUnavailable"}]}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/entities/{entityId}/google-ai-answers":{"get":{"tags":["Layer 1 — Profile"],"summary":"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.","parameters":[{"name":"entityId","in":"path","required":true,"schema":{"type":"string","example":"entx_8f3a2b1c9d4e"}}],"responses":{"200":{"description":"Google AI Answers payload, or { available: false } when no run exists for the entity yet.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/GoogleAiAnswers"},{"$ref":"#/components/schemas/GoogleAiAnswersUnavailable"}]}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/entities/{entityId}/guest-intelligence":{"get":{"tags":["Layer 1 — Profile"],"summary":"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.","parameters":[{"name":"entityId","in":"path","required":true,"schema":{"type":"string","example":"entx_8f3a2b1c9d4e"}}],"responses":{"200":{"description":"Guest Intelligence payload, or { available: false } when the entity has no episodes or no attributed comment signal.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/GuestIntelligence"},{"$ref":"#/components/schemas/GuestIntelligenceUnavailable"}]}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/entities/{entityId}/milo/action":{"post":{"tags":["Layer 1 — Profile"],"summary":"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`.","parameters":[{"name":"entityId","in":"path","required":true,"schema":{"type":"string","example":"entx_8f3a2b1c9d4e"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["role","lens"],"properties":{"role":{"type":"string","enum":["sales","executive","communications","investor","competitor-analyst","journalist","founder","regulator","marketing"]},"lens":{"type":"string","enum":["situation-brief","meeting-prep","doing-business-with","competitor-view","truth-gap","crisis-watch","positioning","cohort-position","reputation-read"]},"bluntness":{"type":"integer","enum":[1,2,3],"description":"1=supportive, 2=direct, 3=blunt but never cruel."},"mode":{"type":"string","enum":["professional","personal","creator","executive"]},"energy":{"type":"string","enum":["low","medium","high"]},"detail":{"type":"string","enum":["brief","standard","deep"]},"refresh":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Milo Action Card, or { available: false } when the lens gate is not met (no dataset surface populated), the flag is off, the governor is paused, or the entity is out of tier scope.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/MiloActionCard"},{"$ref":"#/components/schemas/MiloActionUnavailable"}]}}}},"400":{"description":"Invalid role or lens."},"404":{"$ref":"#/components/responses/NotFound"}}}},"/entity/{slug}/knowledge":{"servers":[{"url":"https://entidex.com","description":"Site root (no /api/v1 prefix)"}],"get":{"tags":["Layer 0 — Discovery"],"summary":"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.","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"format","in":"query","schema":{"type":"string","enum":["md","jsonld","json"],"default":"md"}}],"responses":{"200":{"description":"Knowledge statement (text/markdown, application/ld+json, or application/json). May be sparse for entities awaiting identity resolution."},"404":{"description":"Unknown or hidden entity — no statement is served for these slugs."}}}},"/.well-known/did.json":{"servers":[{"url":"https://entidex.com","description":"Site root (no /api/v1 prefix)"}],"get":{"tags":["Layer 0 — Discovery"],"summary":"did:web DID document — the Ed25519 public key that verifies the JWS proof on signed Knowledge Statements. 404 until a signing key is provisioned.","responses":{"200":{"description":"DID document (application/did+json)."},"404":{"description":"No signing key configured."}}}},"/llms.txt":{"servers":[{"url":"https://entidex.com","description":"Site root (no /api/v1 prefix)"}],"get":{"tags":["Layer 0 — Discovery"],"summary":"Site-level discovery index (llms.txt) listing per-entity Verified Knowledge Statements for AI systems.","responses":{"200":{"description":"Markdown index (text/markdown)."}}}},"/entities/{entityId}/neighbourhood":{"get":{"tags":["Layer 1 — Profile"],"summary":"Resolved related entities.","parameters":[{"name":"entityId","in":"path","required":true,"schema":{"type":"string","example":"entx_8f3a2b1c9d4e"}},{"name":"depth","in":"query","schema":{"type":"integer","default":1,"maximum":3}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/NeighbourhoodEdge"}},"meta":{"$ref":"#/components/schemas/ResponseMeta"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/ApiError"}}}}}}}}}},"/entities/refresh":{"post":{"tags":["Layer 1 — Profile"],"summary":"Force a re-sweep of an entity.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["entityId"],"properties":{"entityId":{"type":"string"},"depth":{"type":"string","enum":["shallow","standard","deep"]}}}}}},"responses":{"202":{"description":"Job queued."}}}},"/entities/{entityId}/insights":{"get":{"tags":["Layer 2 — Insight"],"summary":"All score dimensions.","parameters":[{"name":"entityId","in":"path","required":true,"schema":{"type":"string","example":"entx_8f3a2b1c9d4e"}}],"responses":{"200":{"description":"Map of dimension to Score."}}}},"/entities/{entityId}/insights/{dimension}":{"get":{"tags":["Layer 2 — Insight"],"summary":"Single Score with full breakdown.","parameters":[{"name":"entityId","in":"path","required":true,"schema":{"type":"string","example":"entx_8f3a2b1c9d4e"}},{"name":"dimension","in":"path","required":true,"schema":{"$ref":"#/components/schemas/ScoreDimension"}},{"name":"window","in":"query","schema":{"type":"string","enum":["7d","30d","90d","365d"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Score"},"meta":{"$ref":"#/components/schemas/ResponseMeta"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/ApiError"}}}}}}}}}},"/entities/{entityId}/insights/{dimension}/history":{"get":{"tags":["Layer 2 — Insight"],"summary":"Time-series of past Score computations.","parameters":[{"name":"entityId","in":"path","required":true,"schema":{"type":"string","example":"entx_8f3a2b1c9d4e"}},{"name":"dimension","in":"path","required":true,"schema":{"$ref":"#/components/schemas/ScoreDimension"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Score"}},"meta":{"$ref":"#/components/schemas/ResponseMeta"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/ApiError"}}}}}}}}}},"/entities/{entityId}/drift":{"get":{"tags":["Layer 2 — Insight"],"summary":"Drift events for an entity (Pro+).","parameters":[{"name":"entityId","in":"path","required":true,"schema":{"type":"string","example":"entx_8f3a2b1c9d4e"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DriftEvent"}},"meta":{"$ref":"#/components/schemas/ResponseMeta"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/ApiError"}}}}}}}}}},"/entities/{entityId}/score-history":{"get":{"tags":["Layer 1 — Profile"],"summary":"Historical score snapshots + per-dimension drift (Starter+).","description":"Time-series snapshots for the four headline signals (AI Visibility, Sentiment, Share of Voice, Trust Stack) and the two secondary derived insights (Narrative Coverage, Entity Maturity). Each dimension returns the dated snapshots plus current / previous / delta / trend over the lookback window. Tier gate: layer_1_profile.","parameters":[{"name":"entityId","in":"path","required":true,"schema":{"type":"string","example":"entx_8f3a2b1c9d4e"}},{"name":"dimension","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated list of dimensions, or \"all\". Default \"all\". Valid values: visibility, sentiment, shareOfVoice, trustStack, narrativeCoverage, maturity."},{"name":"days","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":90,"default":30},"description":"Lookback window in days (1–90). Defaults to 30."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ScoreHistoryResponse"},"meta":{"$ref":"#/components/schemas/ResponseMeta"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/ApiError"}}}}}}}}}},"/entities/{entityId}/x-sentiment":{"get":{"tags":["Layer 2 — Insight"],"summary":"Latest real-time X (social) read for an entity (Pro+) — sentiment, key voices, praises / complaints, expansion graph, timeline, early-warning.","parameters":[{"name":"entityId","in":"path","required":true,"schema":{"type":"string","example":"entx_8f3a2b1c9d4e"}},{"name":"history","in":"query","schema":{"type":"boolean","default":false},"description":"When true, return the full stored series instead of just the latest snapshot."}],"responses":{"200":{"description":"Latest X sentiment read (when ?history is absent or false), or the stored series (when ?history=true). When no read has been collected, returns the standard ok envelope wrapping null.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/XSentimentSnapshot"},{"$ref":"#/components/schemas/XSentimentHistoryResponse"},{"type":"null"}]}}}}}}},"/entities/{entityId}/core-intelligence":{"get":{"tags":["Layer 2 — Insight"],"summary":"Entity Core Intelligence Profile (Pro+) — ten authority/readability scores, topic ownership, entity graph, competitors, perception map, strategic actions, and live-web grounding provenance.","description":"Read-only projection of the latest stored Entity Core Intelligence Profile. Returns 404 when no profile has been built for the entity yet. Tier gate: layer_2_insight. The ten Core scores are an internal authority/readability model, not the canonical headline Score dimensions, and carry no Confidence Layer.","parameters":[{"name":"entityId","in":"path","required":true,"schema":{"type":"string","example":"entx_8f3a2b1c9d4e"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CoreIntelligence"},"meta":{"$ref":"#/components/schemas/ResponseMeta"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/ApiError"}}}}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/entities/{entityId}/trajectory":{"get":{"tags":["Layer 3 — Drift"],"summary":"Composite trajectory vector.","parameters":[{"name":"entityId","in":"path","required":true,"schema":{"type":"string","example":"entx_8f3a2b1c9d4e"}}],"responses":{"200":{"description":"Trajectory composite."}}}},"/subscriptions":{"get":{"tags":["Layer 3 — Drift"],"summary":"List subscriptions for the account.","responses":{"200":{"description":"OK"}}},"post":{"tags":["Layer 3 — Drift"],"summary":"Create a subscription.","responses":{"201":{"description":"Created"}}}},"/subscriptions/{subscriptionId}":{"get":{"tags":["Layer 3 — Drift"],"summary":"Get subscription.","parameters":[{"name":"subscriptionId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}},"patch":{"tags":["Layer 3 — Drift"],"summary":"Update subscription.","parameters":[{"name":"subscriptionId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}},"delete":{"tags":["Layer 3 — Drift"],"summary":"Delete subscription.","parameters":[{"name":"subscriptionId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}}},"/alerts":{"get":{"tags":["Layer 3 — Drift"],"summary":"Account alert inbox.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Alert"}},"meta":{"$ref":"#/components/schemas/ResponseMeta"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/ApiError"}}}}}}}}}},"/alerts/{alertId}/acknowledge":{"post":{"tags":["Layer 3 — Drift"],"summary":"Acknowledge an alert.","parameters":[{"name":"alertId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}}},"/alerts/rules":{"get":{"tags":["Layer 3 — Drift"],"summary":"List alert rules for the account.","responses":{"200":{"description":"OK"}}},"post":{"tags":["Layer 3 — Drift"],"summary":"Create an alert rule.","responses":{"201":{"description":"Created"}}}},"/account/api-keys":{"get":{"tags":["Account"],"summary":"List API keys for the account.","responses":{"200":{"description":"OK"}}},"post":{"tags":["Account"],"summary":"Create a new API key.","responses":{"201":{"description":"Created — plaintext key shown once."}}}},"/account/api-keys/{apiKeyId}":{"delete":{"tags":["Account"],"summary":"Revoke an API key.","parameters":[{"name":"apiKeyId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}}},"/account/credits":{"get":{"tags":["Account"],"summary":"Credit balance and usage summary.","responses":{"200":{"description":"OK"}}}},"/account/quota":{"get":{"tags":["Account"],"summary":"Plan, entitlements, and token usage for the current period.","responses":{"200":{"description":"OK"}}}},"/account/watchlist":{"get":{"tags":["Account"],"summary":"List watched entities.","responses":{"200":{"description":"OK"}}},"post":{"tags":["Account"],"summary":"Add entity to watchlist.","responses":{"201":{"description":"Created"}}}},"/cohort":{"get":{"tags":["Layer 4 — Cohort"],"summary":"List cohorts for the account.","responses":{"200":{"description":"OK"}}},"post":{"tags":["Layer 4 — Cohort"],"summary":"Create a new cohort.","responses":{"201":{"description":"Created"}}}},"/cohort/{cohortId}/compare":{"get":{"tags":["Layer 4 — Cohort"],"summary":"Cohort comparison — scores, ranks, deltas.","parameters":[{"name":"cohortId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}}},"/cohort/{cohortId}/rankings":{"get":{"tags":["Layer 4 — Cohort"],"summary":"Ranked entities in a cohort.","parameters":[{"name":"cohortId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}}},"/entities/{entityId}/cohort":{"get":{"tags":["Layer 4 — Cohort"],"summary":"Cohort position for an entity.","parameters":[{"name":"entityId","in":"path","required":true,"schema":{"type":"string","example":"entx_8f3a2b1c9d4e"}}],"responses":{"200":{"description":"OK"}}}},"/entities/{entityId}/decision-survival":{"get":{"tags":["Layer 2 — Insight"],"summary":"Decision Survival Score (per scenario, with displacement chain).","parameters":[{"name":"entityId","in":"path","required":true,"schema":{"type":"string","example":"entx_8f3a2b1c9d4e"}},{"name":"scenario","in":"query","required":false,"schema":{"type":"string"},"description":"Scope to a single scenario_key."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DecisionSurvivalResponse"},"meta":{"$ref":"#/components/schemas/ResponseMeta"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/ApiError"}}}}}}}}}},"/entities/{entityId}/decision-survival/run":{"post":{"tags":["Layer 2 — Insight"],"summary":"Run the Decision Survival probes live and persist a score per scenario.","description":"Replays the multi-turn scenarios against the AI engines. Billed at 10× the standard probe credit cost (Amendment 6).","parameters":[{"name":"entityId","in":"path","required":true,"schema":{"type":"string","example":"entx_8f3a2b1c9d4e"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"scenarioKeys":{"type":"array","items":{"type":"string"},"maxItems":10},"engines":{"type":"array","items":{"type":"string","enum":["claude","gemini","perplexity","grok","chatgpt"]}},"category":{"type":"string"},"audience":{"type":"string"},"objection":{"type":"string"},"constraints":{"type":"string"},"competitorLabels":{"type":"array","items":{"type":"string"},"maxItems":20}}}}}},"responses":{"200":{"description":"OK — per-scenario run outcome."}}}},"/entities/{entityId}/data-completeness":{"get":{"tags":["Layer 2 — Insight"],"summary":"Per-LLM data completeness, truth-gap, and ranked demand gaps.","description":"Returns what each AI engine knows, gets wrong, and says it is missing about an entity. Gaps are ranked by importance (identity-anchoring + cross-engine demand + truth-gap pressure). Optionally includes truth-gap ingestion lag estimates.","parameters":[{"name":"entityId","in":"path","required":true,"schema":{"type":"string","example":"entx_8f3a2b1c9d4e"}},{"name":"lag","in":"query","required":false,"schema":{"type":"string","enum":["1"]},"description":"Set to 1 to include per-engine truth-gap ingestion lag estimate."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DataCompletenessResponse"},"meta":{"$ref":"#/components/schemas/ResponseMeta"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/ApiError"}}}}}}}}}},"/entities/{entityId}/consensus-map":{"get":{"tags":["Layer 2 — Insight"],"summary":"Consensus/Divergence across surfaces, plus over-time trend matrix.","parameters":[{"name":"entityId","in":"path","required":true,"schema":{"type":"string","example":"entx_8f3a2b1c9d4e"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ConsensusMapResponse"},"meta":{"$ref":"#/components/schemas/ResponseMeta"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/ApiError"}}}}}}}}}},"/entities/{entityId}/ecosystem":{"get":{"tags":["Layer 1 — Profile"],"summary":"AI Ecosystem read (Starter+): per-engine fit, grounded mention/recommendation/citation/sentiment with provenance, cross-engine coherence, reinforcement patterns, and strategic narrative.","parameters":[{"name":"entityId","in":"path","required":true,"schema":{"type":"string","example":"entx_8f3a2b1c9d4e"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/EcosystemResponse"},"meta":{"$ref":"#/components/schemas/ResponseMeta"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/ApiError"}}}}}}}}}},"/entities/{entityId}/markets":{"get":{"tags":["Layer 1 — Profile"],"summary":"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.","parameters":[{"name":"entityId","in":"path","required":true,"schema":{"type":"string","example":"entx_8f3a2b1c9d4e"}},{"name":"history","in":"query","schema":{"type":"boolean","default":false},"description":"Return the stored series instead of the latest reading."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PublicMarketData"},"meta":{"$ref":"#/components/schemas/ResponseMeta"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/ApiError"}}}}}}}}}},"/entities/{entityId}/complete":{"get":{"tags":["Layer 1 — Profile"],"summary":"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.","parameters":[{"name":"entityId","in":"path","required":true,"schema":{"type":"string","example":"entx_8f3a2b1c9d4e"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/EntityComplete"},"meta":{"$ref":"#/components/schemas/ResponseMeta"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/ApiError"}}}}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/categories":{"get":{"tags":["Layer 1 — Profile"],"summary":"Browse the categorized entity network — every category with its entity count. minTier free.","responses":{"200":{"description":"OK — array of { slug, name, description, entityCount }."}}}},"/categories/{slug}":{"get":{"tags":["Layer 1 — Profile"],"summary":"A category plus a page of its entities (identity-only summaries). minTier free. Offset-paginated via ?limit (max 100) and ?offset.","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"description":"OK — { category, entities[] }."}}}},"/entities/{entityId}/lifecycle":{"get":{"tags":["Layer 2 — Insight"],"summary":"Lifecycle stage and transition events.","parameters":[{"name":"entityId","in":"path","required":true,"schema":{"type":"string","example":"entx_8f3a2b1c9d4e"}}],"responses":{"200":{"description":"OK"}}}},"/entities/{entityId}/timeline":{"get":{"tags":["Layer 2 — Insight"],"summary":"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.","parameters":[{"name":"entityId","in":"path","required":true,"schema":{"type":"string","example":"entx_8f3a2b1c9d4e"}},{"name":"days","in":"query","schema":{"type":"integer","default":90},"description":"Lookback window in days (1–90)."},{"name":"limit","in":"query","schema":{"type":"integer","default":60},"description":"Max events after the merge (1–200)."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/EntityTimeline"},"meta":{"$ref":"#/components/schemas/ResponseMeta"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/ApiError"}}}}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/entities/{entityId}/authenticity":{"get":{"tags":["Layer 2 — Insight"],"summary":"Authenticity score (creator types only).","parameters":[{"name":"entityId","in":"path","required":true,"schema":{"type":"string","example":"entx_8f3a2b1c9d4e"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Score"},"meta":{"$ref":"#/components/schemas/ResponseMeta"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/ApiError"}}}}}}}}}},"/entities/{entityId}/conflation":{"get":{"tags":["Layer 2 — Insight"],"summary":"Conflation severity (person entities only).","parameters":[{"name":"entityId","in":"path","required":true,"schema":{"type":"string","example":"entx_8f3a2b1c9d4e"}}],"responses":{"200":{"description":"OK"}}}},"/entities/{entityId}/sub-entities":{"get":{"tags":["Layer 1 — Profile"],"summary":"Sub-entities (decomposition nodes).","parameters":[{"name":"entityId","in":"path","required":true,"schema":{"type":"string","example":"entx_8f3a2b1c9d4e"}}],"responses":{"200":{"description":"OK"}}}},"/entities/{entityId}/identity":{"get":{"tags":["Layer 1 — Profile"],"summary":"Identity lock status and decomposition model.","parameters":[{"name":"entityId","in":"path","required":true,"schema":{"type":"string","example":"entx_8f3a2b1c9d4e"}}],"responses":{"200":{"description":"OK"}}}},"/entities/{entityId}/probes":{"get":{"tags":["Layer 1 — Profile"],"summary":"Probe runs for an entity.","parameters":[{"name":"entityId","in":"path","required":true,"schema":{"type":"string","example":"entx_8f3a2b1c9d4e"}}],"responses":{"200":{"description":"OK"}}}},"/billing/providers":{"get":{"tags":["Billing"],"summary":"Available payment providers.","responses":{"200":{"description":"OK"}}}},"/billing/checkout":{"post":{"tags":["Billing"],"summary":"Create a checkout session.","responses":{"200":{"description":"OK — {url}"}}}},"/billing/portal":{"post":{"tags":["Billing"],"summary":"Create a billing portal session.","responses":{"200":{"description":"OK — {url}"}}}},"/billing/credits/purchase":{"post":{"tags":["Billing"],"summary":"Purchase a credit pack.","responses":{"201":{"description":"Created"}}}},"/auth/login":{"post":{"tags":["Auth"],"summary":"Login with email + password.","responses":{"200":{"description":"OK"}}}},"/auth/signup":{"post":{"tags":["Auth"],"summary":"Create a new account.","responses":{"201":{"description":"Created"}}}},"/auth/me":{"get":{"tags":["Auth"],"summary":"Current authenticated user.","responses":{"200":{"description":"OK"}}}},"/auth/cli/device-code":{"post":{"tags":["Auth"],"summary":"Issue a device code for CLI authentication.","responses":{"201":{"description":"Created — device_code, user_code, verification_uri."}}}},"/auth/cli/token":{"get":{"tags":["Auth"],"summary":"Poll for CLI device code approval.","parameters":[{"name":"device_code","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK — status + apiKey on approval."}}}},"/status":{"get":{"tags":["Meta"],"summary":"API reachability + optional auth check.","responses":{"200":{"description":"OK"}}}}}}