{"openapi":"3.1.0","info":{"title":"SummerEyes Investigation API","description":"REST API for the SummerEyes reasoning engine. Submit claims from multiple sources and get scored verdicts, ranked claims, conflict analysis with interpretation trees, temporal decay tracking, corroboration refresh, epistemic status lifecycle, and supersession chain analysis.","version":"0.1.0"},"paths":{"/api/v1/investigations/analyze":{"post":{"tags":["investigations"],"summary":"Submit an investigation for analysis.","description":"Accepts a full investigation payload (actors, subjects, claims, evidence)\nand returns structured results including truth status, confidence scores,\nranked claims, and conflict analysis with interpretation trees.","operationId":"post_investigation","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvestigationInput"}}},"required":true},"responses":{"200":{"description":"Investigation completed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvestigationResult"}}}},"422":{"description":"Invalid investigation input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"api_key":[]},{"bearer":[]}]}}},"components":{"schemas":{"ActorInput":{"type":"object","required":["id","name","source_type"],"properties":{"base_reliability":{"type":["number","null"],"format":"double"},"competence":{"type":["object","null"],"description":"Per-predicate competence scores (0–1). Optional.\nEffective reliability = disposition × competence(predicate) × conflict_penalties.","additionalProperties":{"type":"number","format":"double"},"propertyNames":{"type":"string"}},"default_competence":{"type":["number","null"],"format":"double","description":"Fallback competence when no predicate-specific score exists. Defaults to 1.0."},"id":{"type":"string"},"name":{"type":"string"},"source_type":{"type":"string","description":"Must match a SourceType variant name (case-insensitive)."}}},"ArgumentationSummary":{"type":"object","required":["accepted_claims","alternative_interpretations","dispute_level","causal_chains","is_exact","interpretations"],"properties":{"accepted_claims":{"type":"array","items":{"type":"string"},"description":"Claims that survive all challenges (internal IDs, kept for backwards compat)."},"alternative_interpretations":{"type":"array","items":{"type":"array","items":{"type":"string"}},"description":"Alternative coherent interpretations of the evidence (internal IDs, kept for backwards compat)."},"causal_chains":{"type":"array","items":{"$ref":"#/components/schemas/CausalChainSummary"}},"dispute_level":{"type":"number","format":"double","description":"How contested the narrative is (0 = consensus, higher = more disputed)"},"interpretations":{"type":"array","items":{"$ref":"#/components/schemas/InterpretationTree"},"description":"Rich interpretation trees: one per preferred extension, with full claim\ncontext, attack/support edges, and credibility opinions."},"is_exact":{"type":"boolean","description":"True if all interpretations were computed exhaustively.\nFalse if the analysis was too large and used an approximation."}}},"AttackEdge":{"type":"object","required":["attacker_claim_id","target_claim_id","description"],"properties":{"attacker_claim_id":{"type":"string"},"description":{"type":"string"},"target_claim_id":{"type":"string"}}},"CausalChainSummary":{"type":"object","required":["argument_ids"],"properties":{"argument_ids":{"type":"array","items":{"type":"string"}}}},"ClaimAnalysisSummary":{"type":"object","required":["claim_id","predicate","value","actor_id","truth_status","expected_probability","support","opposition","uncertainty","supporting_count","refuting_count","neutral_count","temporal_decay_factor","effective_half_life_days","epistemic_status","freshness_score"],"properties":{"actor_id":{"type":"string"},"assertion_time":{"type":["string","null"],"description":"When this claim was asserted (RFC 3339), if known."},"below_credibility_floor":{"type":"boolean","description":"True if the actor's reliability fell below the credibility floor.\nThe claim is visible but its evidence counts are zeroed.\n\nRef: Hansson et al. (2001), \"Credibility Limited Revision\""},"claim_id":{"type":"string"},"corroboration_count":{"type":"integer","description":"Number of valid corroboration events for this claim.","minimum":0},"decay_origin":{"type":["string","null"],"description":"The time from which decay was computed (RFC 3339). Equals assertion_time\nif no corroboration; equals the most recent effective corroboration time\notherwise."},"effective_half_life_days":{"type":"number","format":"double","description":"The effective half-life in days used for this specific claim's decay,\nafter applying claim-type and source-authority multipliers."},"epistemic_status":{"type":"string","description":"Epistemic lifecycle status: \"conjecture\", \"hypothesis\", \"theory\", \"law\",\n\"superseded\", \"retracted\"."},"expected_probability":{"type":"number","format":"double"},"freshness_score":{"type":"number","format":"double","description":"Composite freshness score (0.0-1.0). Combines temporal decay (70%),\ncorroboration recency (20%), and epistemic status factor (10%)."},"last_corroborated":{"type":["string","null"],"description":"Most recent corroboration time (RFC 3339), if any."},"neutral_count":{"type":"integer","format":"int64"},"opposition":{"type":"number","format":"double"},"predicate":{"type":"string"},"refuting_count":{"type":"integer","format":"int64"},"suggested_epistemic_status":{"type":["string","null"],"description":"System-suggested epistemic status based on evidence accumulation.\nOnly present when it differs from the current epistemic_status."},"support":{"type":"number","format":"double"},"supporting_count":{"type":"integer","format":"int64"},"temporal_decay_factor":{"type":"number","format":"double","description":"Temporal decay multiplier applied to this claim's evidence weight.\n1.0 = recent claim (full weight); 0.5 = one half-life old.\nComputed using: `base_half_life × claim_type_mult × source_authority_mult`."},"truth_status":{"type":"string","description":"\"True\", \"False\", \"Both\" (contradicted), or \"Neither\" (no information)"},"uncertainty":{"type":"number","format":"double"},"value":{"type":"string"}}},"ClaimInput":{"type":"object","required":["id","actor_id","predicate","value","content"],"properties":{"actor_id":{"type":"string"},"assertion_time":{"type":["string","null"],"description":"ISO 8601 / RFC 3339 timestamp (e.g. \"2024-01-15T09:30:00Z\")."},"claim_type":{"type":["string","null"],"description":"\"Factual\", \"Predictive\", \"Evaluative\", \"Causal\", or \"Procedural\".\nDefaults to \"Factual\" if absent. Predictive/Evaluative/Causal claims\ncarry inherently more uncertainty."},"content":{"type":"string"},"corroboration_events":{"type":"array","items":{"$ref":"#/components/schemas/CorroborationEventInput"},"description":"Corroboration events: independent confirmations of this claim at later times.\nEach resets the temporal decay clock (fully for independent sources, partially\nfor dependent sources controlled by `dependent_refresh_factor`)."},"decay_half_life_days":{"type":["number","null"],"format":"double","description":"Per-claim half-life override in days.  When set, bypasses the computed\n`base_half_life × claim_type_multiplier × source_authority_multiplier`."},"epistemic_status":{"type":["string","null"],"description":"Epistemic lifecycle status. One of: \"conjecture\", \"hypothesis\" (default),\n\"theory\", \"law\", \"superseded\", \"retracted\". Affects temporal decay rate."},"event_end_time":{"type":["string","null"],"description":"ISO 8601 end of the event window; absent means open."},"event_start_time":{"type":["string","null"],"description":"ISO 8601 start of the event window; absent means open."},"id":{"type":"string"},"predicate":{"type":"string"},"relationships":{"type":["array","null"],"items":{"$ref":"#/components/schemas/ClaimRelationshipInput"},"description":"Explicit relationships to other claims (by claim ID).\nEach entry is an object: `{\"type\": \"complements\"|\"refines\"|\"qualifies\"|\n\"supersedes\"|\"challenges_methodology\", \"target_claim_id\": \"...\"}`."},"scope":{"type":["string","null"],"description":"Scope qualifier — disambiguates claims on the same predicate that\nmeasure different things.  Examples: \"global\", \"US\", \"nominal\",\n\"risk-adjusted\", \"top-quartile\".  Claims with different scopes on the\nsame predicate are not treated as contradictions."},"subject_id":{"type":["string","null"],"description":"Set for regular claims; empty / absent for meta-claims."},"supersedes_claim_id":{"type":["string","null"],"description":"ID of the claim this one supersedes. The superseded claim's epistemic status\nis automatically set to \"superseded\" and its effective half-life drops to 25%."},"target_claim_id":{"type":["string","null"],"description":"Set for meta-claims; empty / absent for regular claims."},"valence":{"type":["string","null"],"description":"\"Supports\", \"Refutes\", or \"Neutral\". Defaults to \"Neutral\" if absent."},"value":{"type":"string"}}},"ClaimRelationshipInput":{"type":"object","required":["relationship_type","target_claim_id"],"properties":{"relationship_type":{"type":"string","description":"One of: \"complements\", \"refines\", \"qualifies\", \"supersedes\",\n\"challenges_methodology\"."},"target_claim_id":{"type":"string","description":"The ID of the related claim."}}},"CorroboratedClaim":{"type":"object","required":["claim_id","corroboration_count","last_corroborated","freshness_score"],"properties":{"claim_id":{"type":"string"},"corroboration_count":{"type":"integer","minimum":0},"freshness_score":{"type":"number","format":"double"},"last_corroborated":{"type":"string"}}},"CorroborationEventInput":{"type":"object","required":["time","actor_id"],"properties":{"actor_id":{"type":"string","description":"ID of the actor who corroborated. Must differ from the claim's actor_id."},"description":{"type":"string","description":"Description of the corroborating evidence."},"time":{"type":"string","description":"When the corroboration occurred (ISO 8601 / RFC 3339)."}}},"ErrorResponse":{"type":"object","description":"Error response returned when a request fails.","required":["error"],"properties":{"error":{"type":"string"}}},"EvidenceGap":{"type":"object","description":"A single evidence gap: a subject-predicate pair where additional data would\nmost reduce uncertainty or resolve contestation.","required":["subject_id","predicate","uncertainty","expected_probability","potential_shift","is_contested","suggestion"],"properties":{"discriminating_claims":{"type":"array","items":{"type":"string"},"description":"Claims that appear in some but not all preferred extensions — the locus\nof narrative disagreement.  Evidence targeting these claims would best\ndiscriminate between competing interpretations.\n\nRef: Good (1985) \"Weight of Evidence\"; Schum (1994) \"Evidential Foundations\""},"expected_probability":{"type":"number","format":"double","description":"Current expected probability."},"is_contested":{"type":"boolean","description":"Whether this predicate is contested (multiple conflicting interpretations)."},"potential_shift":{"type":"number","format":"double","description":"Estimated probability shift if one strong confirming evidence were added.\nComputed by simulating +1 evidence count and re-fusing."},"predicate":{"type":"string"},"subject_id":{"type":"string"},"suggestion":{"type":"string","description":"Human-readable suggestion for what evidence would be most valuable."},"uncertainty":{"type":"number","format":"double","description":"Current uncertainty level (0 = certain, 1 = no evidence)."}}},"EvidenceInput":{"type":"object","required":["id","claim_id","content","valence"],"properties":{"claim_id":{"type":"string"},"content":{"type":"string"},"id":{"type":"string"},"valence":{"type":"string","description":"\"Supports\", \"Refutes\", or \"Neutral\" (case-insensitive)."},"weight":{"type":["number","null"],"format":"double"}}},"InterpretationClaim":{"type":"object","required":["claim_id","actor_id","actor_name","predicate","value","content","belief","disbelief","uncertainty","expected_probability","truth_status"],"properties":{"actor_id":{"type":"string","description":"Which actor made this claim."},"actor_name":{"type":"string","description":"The actor's name."},"belief":{"type":"number","format":"double","description":"Credibility opinion for this claim."},"claim_id":{"type":"string","description":"The user-supplied claim ID (not internal)."},"content":{"type":"string","description":"The claim content/description."},"disbelief":{"type":"number","format":"double"},"expected_probability":{"type":"number","format":"double"},"predicate":{"type":"string","description":"What they claimed (predicate = value)."},"truth_status":{"type":"string","description":"Belnap status."},"uncertainty":{"type":"number","format":"double"},"value":{"type":"string"}}},"InterpretationTree":{"type":"object","description":"A coherent interpretation of the evidence — one preferred extension rendered\nwith full claim context, edge info, and credibility opinions.","required":["label","coherence_score","accepted_claims","attacks","supports"],"properties":{"accepted_claims":{"type":"array","items":{"$ref":"#/components/schemas/InterpretationClaim"},"description":"The claims accepted in this interpretation, with full context."},"attacks":{"type":"array","items":{"$ref":"#/components/schemas/AttackEdge"},"description":"Attack edges within this interpretation context."},"coherence_score":{"type":"number","format":"double","description":"Narrative coherence score (0.0-1.0): how well this interpretation\nhangs together as a story.  Combines evidential coverage (25%),\ninternal support density (25%), and mean credibility (50%).\n\nRef: Thagard (2000) \"Coherence in Thought and Action\" (ECHO);\n     Bex (2011) \"Arguments, Stories and Criminal Evidence\""},"label":{"type":"string","description":"Human-readable label: \"Interpretation 1\", \"Interpretation 2\", etc."},"supports":{"type":"array","items":{"$ref":"#/components/schemas/SupportEdge"},"description":"Support edges within this interpretation context."}}},"InvestigationInput":{"type":"object","required":["research_question","actors","subjects","claims"],"properties":{"actors":{"type":"array","items":{"$ref":"#/components/schemas/ActorInput"}},"claims":{"type":"array","items":{"$ref":"#/components/schemas/ClaimInput"}},"decay_half_life_days":{"type":["number","null"],"format":"double","description":"Explicit temporal half-life in days, overriding the domain default.\nA claim this many days old has half its original evidence weight."},"dependent_refresh_factor":{"type":["number","null"],"format":"double","description":"Factor (0.0-1.0) controlling how much dependent-source corroboration\nrefreshes the temporal decay clock. 0.0 = no refresh, 0.5 = halfway\nrefresh (default), 1.0 = full refresh (same as independent)."},"domain":{"type":["string","null"],"description":"Knowledge domain that sets the default temporal half-life for claims.\nOne of: \"Finance\" (180d), \"News\" (90d), \"Technology\" (365d),\n\"Geopolitics\" (2yr), \"Medicine\" (10yr), \"Science\" (25yr),\n\"Legal\" (20yr), \"General\" (180d). Case-insensitive. Defaults to \"General\"."},"evidence":{"type":["array","null"],"items":{"$ref":"#/components/schemas/EvidenceInput"}},"research_question":{"type":"string"},"subjects":{"type":"array","items":{"$ref":"#/components/schemas/SubjectInput"}},"summary_mode":{"type":"boolean","description":"When true, returns a compact output: top findings, top contested claims,\ntop evidence gaps, and a one-paragraph synthesis.  The full output is\nomitted.  Designed for LLM consumers with limited context windows."}}},"InvestigationResult":{"type":"object","required":["research_question","decay_half_life_days","subject_results","conflict_analysis","claim_analyses","ranked_claims","sensitivity_analysis"],"properties":{"claim_analyses":{"type":"array","items":{"$ref":"#/components/schemas/ClaimAnalysisSummary"}},"conflict_analysis":{"type":"array","items":{"$ref":"#/components/schemas/SubjectArgumentation"},"description":"Argumentation analysis for every (subject, predicate) pair."},"decay_half_life_days":{"type":"number","format":"double","description":"The temporal half-life in days used for this investigation."},"ranked_claims":{"type":"array","items":{"$ref":"#/components/schemas/RankedClaim"},"description":"Claims ranked by net evidence strength (belief − disbelief), descending."},"research_question":{"type":"string"},"sensitivity_analysis":{"$ref":"#/components/schemas/SensitivityAnalysis","description":"Sensitivity analysis: which evidence gaps would most shift conclusions.\nEnables abductive reasoning — \"what should I look for next?\""},"subject_results":{"type":"array","items":{"$ref":"#/components/schemas/SubjectResult"}},"temporal_analysis":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/TemporalAnalysis","description":"Temporal analysis: freshness report, supersession chains, and\ncorroboration summary. Present when any claim uses temporal features\n(corroboration, epistemic status, or supersession)."}]},"warnings":{"type":"array","items":{"type":"string"},"description":"Soft warnings about potentially inconsistent inputs (e.g. a Troll with\n0.95 reliability).  Empty when all inputs look reasonable."}}},"OpinionSummary":{"type":"object","required":["support","opposition","uncertainty","base_rate"],"properties":{"base_rate":{"type":"number","format":"double"},"opposition":{"type":"number","format":"double"},"support":{"type":"number","format":"double"},"uncertainty":{"type":"number","format":"double"}}},"RankedClaim":{"type":"object","description":"A claim ranked by net evidence strength.","required":["rank","claim_id","actor_id","predicate","value","category","expected_probability","belief","disbelief","uncertainty"],"properties":{"actor_id":{"type":"string"},"belief":{"type":"number","format":"double"},"category":{"type":"string","description":"\"strong\", \"moderate\", \"contested\", \"weak\", or \"refuted\""},"claim_id":{"type":"string"},"disbelief":{"type":"number","format":"double"},"expected_probability":{"type":"number","format":"double"},"predicate":{"type":"string"},"rank":{"type":"integer","minimum":0},"uncertainty":{"type":"number","format":"double"},"value":{"type":"string"}}},"SensitivityAnalysis":{"type":"object","description":"Identifies the highest-value missing evidence — claims or subject-predicates\nwhere additional data would most shift the conclusions.  This is the\nabductive reasoning layer: \"what would best explain the remaining uncertainty?\"","required":["evidence_gaps"],"properties":{"evidence_gaps":{"type":"array","items":{"$ref":"#/components/schemas/EvidenceGap"},"description":"Per-subject evidence gaps, ordered by potential impact (highest first)."}}},"StaleClaim":{"type":"object","required":["claim_id","age_days","decay_factor","recommendation"],"properties":{"age_days":{"type":"number","format":"double"},"claim_id":{"type":"string"},"decay_factor":{"type":"number","format":"double"},"recommendation":{"type":"string"}}},"SubjectArgumentation":{"allOf":[{"$ref":"#/components/schemas/ArgumentationSummary"},{"type":"object","required":["subject_id","predicate"],"properties":{"predicate":{"type":"string"},"subject_id":{"type":"string"}}}],"description":"Argumentation results for a single (subject, predicate) pair."},"SubjectInput":{"type":"object","required":["id","name","subject_type"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"subject_type":{"type":"string"}}},"SubjectResult":{"type":"object","required":["subject_id","subject_name","predicate","truth_status","confidence","expected_probability"],"properties":{"confidence":{"$ref":"#/components/schemas/OpinionSummary"},"expected_probability":{"type":"number","format":"double"},"predicate":{"type":"string"},"subject_id":{"type":"string"},"subject_name":{"type":"string"},"truth_status":{"type":"string","description":"\"True\", \"False\", \"Both\" (contradicted), or \"Neither\" (no information)"}}},"SupersessionChainSummary":{"type":"object","required":["claim_ids","current_claim_id"],"properties":{"claim_ids":{"type":"array","items":{"type":"string"},"description":"Claim IDs ordered oldest → newest."},"current_claim_id":{"type":"string","description":"The most recent (current) claim in the chain."}}},"SupportEdge":{"type":"object","required":["supporter_claim_id","supported_claim_id"],"properties":{"supported_claim_id":{"type":"string"},"supporter_claim_id":{"type":"string"}}},"TemporalAnalysis":{"type":"object","description":"Aggregate temporal analysis for the entire investigation.","required":["stale_claims","recently_corroborated","supersession_chains","overall_freshness"],"properties":{"overall_freshness":{"type":"number","format":"double","description":"Overall investigation freshness (0.0-1.0): average of all claim freshness scores."},"recently_corroborated":{"type":"array","items":{"$ref":"#/components/schemas/CorroboratedClaim"},"description":"Claims with recent corroboration, sorted most recent first."},"stale_claims":{"type":"array","items":{"$ref":"#/components/schemas/StaleClaim"},"description":"Claims past their effective half-life (decay < 0.25), sorted most stale first."},"supersession_chains":{"type":"array","items":{"$ref":"#/components/schemas/SupersessionChainSummary"},"description":"Chains of superseding claims (oldest → newest)."}}}}},"security":[{"api_key":[]},{"bearer":[]}]}