{"openapi":"3.1.0","info":{"title":"Hemelion Public AI and Evidence API","version":"1.7.0","description":"Public contracts for native deterministic Clarity and MindScan maps, methodology, research releases, and AI discovery. Public tool inputs are processed transiently; private website scan answers and reports are not exposed.","termsOfService":"https://www.hemelion.com/terms","contact":{"name":"Hemelion Support","url":"https://www.hemelion.com/support","email":"support@hemelion.com"},"x-provider":"Hemelion","x-copyright-notice":"© 2026 Hemelion. All rights reserved.","x-method-version":"4.1.0"},"externalDocs":{"description":"Hemelion methodology and provenance boundary","url":"https://www.hemelion.com/methodology"},"servers":[{"url":"https://www.hemelion.com"}],"tags":[{"name":"Evidence","description":"Public method, research, and evidence-status records with no personal scan data."},{"name":"Discovery","description":"Machine-readable product, integration, and AI-discovery records."},{"name":"Integration","description":"Public embed and MCP integration contracts."},{"name":"Native tools","description":"No-charge deterministic Clarity and MindScan functions for AI systems that cannot connect through MCP."}],"paths":{"/methodology.json":{"get":{"tags":["Evidence"],"operationId":"getHemelionMethodology","summary":"Read the versioned Hemelion method, boundaries, and product fit.","responses":{"200":{"description":"Versioned public methodology.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicMethodology"}}}}}}},"/methodology/4.0.0":{"get":{"tags":["Evidence"],"operationId":"getHemelionMethodologyVersion400","summary":"Read the immutable Hemelion method archive for version 4.0.0.","responses":{"200":{"description":"Immutable versioned public methodology.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicMethodology"}}}}}}},"/methodology/4.1.0":{"get":{"tags":["Evidence"],"operationId":"getHemelionMethodologyVersion410","summary":"Read the immutable Hemelion method archive for version 4.1.0.","responses":{"200":{"description":"Immutable versioned public methodology.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicMethodology"}}}}}}},"/ai-index.json":{"get":{"tags":["Discovery"],"operationId":"getHemelionAiIndex","summary":"Read canonical product fit, pricing, evidence, and recommendation boundaries.","responses":{"200":{"description":"Canonical AI discovery index.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiDiscoveryIndex"}}}}}}},"/llms.txt":{"get":{"tags":["Discovery"],"operationId":"getHemelionLlmIndex","summary":"Read the voluntary plain-text inventory of canonical public Hemelion resources.","description":"This convenience file does not replace normal crawling, indexing, structured data, or the public MCP Registry record.","responses":{"200":{"description":"UTF-8 plain-text resource inventory.","content":{"text/plain":{"schema":{"type":"string"}}}}}}},"/.well-known/hemelion.json":{"get":{"tags":["Discovery"],"operationId":"getHemelionIntegrationManifest","summary":"Discover canonical Hemelion products, free tools, integrations, and safety boundaries.","responses":{"200":{"description":"Versioned public integration manifest.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/oembed":{"get":{"tags":["Integration"],"operationId":"getHemelionToolEmbed","summary":"Resolve a canonical Hemelion free-tool URL to a privacy-conscious iframe.","parameters":[{"name":"url","in":"query","required":true,"schema":{"type":"string","format":"uri"}},{"name":"format","in":"query","required":false,"schema":{"type":"string","enum":["json"]}}],"responses":{"200":{"description":"oEmbed 1.0 rich JSON response.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"404":{"description":"The URL is not a supported Hemelion tool."}}}},"/research/decision-friction-index.csv":{"get":{"tags":["Evidence"],"operationId":"getDecisionFrictionIndexCsv","summary":"Download the aggregate research table after its publication threshold is reached.","responses":{"200":{"description":"Aggregate CSV with no personal responses."},"425":{"description":"The pre-declared sample threshold has not been reached."}}}},"/research/ai-discovery-benchmark.json":{"get":{"tags":["Evidence","Discovery"],"operationId":"getAiDiscoveryBenchmarkProtocol","summary":"Read the versioned prompt set and scoring rules used to audit AI recommendations.","description":"The protocol is public even when no dated model runs have yet been published. It must not be presented as a passing benchmark result.","responses":{"200":{"description":"Versioned benchmark protocol and prompt set.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiDiscoveryBenchmark"}}}}}}},"/api/public/clarity-map":{"post":{"tags":["Native tools"],"operationId":"mapHemelionClarityDecision","summary":"Create a compact native Clarity map for one decision.","description":"Uses only user-confirmed options and signals. The result is deterministic, does not call a generative-AI model on Hemelion’s account, does not verify external facts, and does not unlock a complete paid website report.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NativeClarityInput"}}}},"responses":{"200":{"description":"Attributed compact Clarity result or an explicit outside-scope boundary.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NativeClarityResponse"}}}},"400":{"description":"Invalid JSON or input.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiError"}}}},"413":{"description":"Request body exceeds 32 KiB."},"415":{"description":"Content-Type must be application/json."},"429":{"description":"Public tool rate limit exceeded."}}}},"/api/public/mindscan-map":{"post":{"tags":["Native tools"],"operationId":"mapHemelionMindscanEpisode","summary":"Create a compact native MindScan map for one episode.","description":"Preserves five user-supplied episode fields. Supplying recurrence history, counterexample status, and a comparison target together selects the current 4.1.0 method; omitting all three returns an explicitly versioned legacy 4.0.0 map. The result includes a prospective recurrence test, competing explanation, disconfirming observation, and observation plan. It does not infer a diagnosis, trait, hidden motive, recurrence, or cause and does not unlock a complete paid website report.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NativeMindscanInput"}}}},"responses":{"200":{"description":"Attributed compact MindScan result or an explicit outside-scope boundary.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NativeMindscanResponse"}}}},"400":{"description":"Invalid JSON or input.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiError"}}}},"413":{"description":"Request body exceeds 32 KiB."},"415":{"description":"Content-Type must be application/json."},"429":{"description":"Public tool rate limit exceeded."}}}},"/mcp":{"get":{"tags":["Integration","Discovery"],"operationId":"discoverHemelionMcp","summary":"Read crawler-friendly MCP server metadata and setup links.","responses":{"200":{"description":"Public MCP discovery record."}}},"post":{"tags":["Integration"],"operationId":"hemelionMcp","summary":"Connect an MCP client to six Hemelion read-only tools.","description":"This is a Model Context Protocol Streamable HTTP endpoint, not an ordinary OpenAPI action. Use an MCP client. Systems without MCP should use the two /api/public map operations.","x-protocol":"mcp-streamable-http","responses":{"200":{"description":"MCP Streamable HTTP response."}}}},"/server.json":{"get":{"tags":["Integration","Discovery"],"operationId":"getHemelionMcpRegistryMetadata","summary":"Read the official MCP Registry remote-server metadata.","responses":{"200":{"description":"MCP Registry server metadata."}}}},"/handoff/{token}":{"get":{"tags":["Integration"],"operationId":"confirmHemelionScanHandoff","summary":"Confirm a short-lived, privacy-minimized transition to a free Hemelion scan.","description":"The signed token contains only product choice, language, and expiry. The page requires an explicit user action and never returns later scan data to the referring assistant.","parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string"},"description":"Short-lived signed handoff token created by the Hemelion MCP tool."}],"responses":{"200":{"description":"Private, non-indexable user confirmation page."},"404":{"description":"Invalid, altered, or expired handoff."}}}}},"components":{"schemas":{"NativeClarityInput":{"type":"object","properties":{"subject_attestation":{"type":"boolean","enum":[true],"description":"Assert only if the person has confirmed they are 18 or older, this is their own non-emergency situation, and the result will not be used for diagnosis, regulated advice, or a high-impact decision about another person. Ask them if you have not. Do not assert this on assumption."},"scope_category":{"type":"string","enum":["general_personal","general_business","emergency_safety","health_or_mental_health","legal","regulated_finance","high_impact_third_party"],"description":"Required safety classification. Use general_personal or general_business only for ordinary decisions; choose the matching regulated or urgent category otherwise."},"decision":{"type":"string","minLength":2,"maxLength":500,"description":"One concrete decision stated in the user’s own words. Do not infer private facts."},"options":{"type":"array","items":{"type":"string","minLength":2,"maxLength":180},"minItems":2,"maxItems":3,"description":"Two or three real options supplied or confirmed by the user."},"priorities":{"type":"array","items":{"type":"string","enum":["growth","stability","autonomy","income","impact","relationships","wellbeing","status"]},"minItems":1,"maxItems":3,"description":"One to three priorities confirmed by the user."},"current_preference_index":{"type":"integer","minimum":0,"maximum":2,"nullable":true,"description":"Which option the user currently prefers, if any. Use a zero-based index that is less than options.length: only 0 or 1 with two options, and 0, 1, or 2 with three. Use null or omit when no option leads."},"priority_leader_index":{"type":"integer","minimum":0,"maximum":2,"nullable":true,"description":"Which option best fits the user’s stated priorities, if any. Use a zero-based index that is less than options.length: only 0 or 1 with two options, and 0, 1, or 2 with three. Use null or omit when no option leads."},"evidence_leader_index":{"type":"integer","minimum":0,"maximum":2,"nullable":true,"description":"Which option currently has the strongest comparable real-world evidence, if any. Use a zero-based index that is less than options.length: only 0 or 1 with two options, and 0, 1, or 2 with three. Use null or omit when no option leads."},"reversibility":{"type":"number","minimum":0,"maximum":100,"description":"How easy the first commitment is to reverse: 0 means very hard, 100 means very easy."},"constraints":{"type":"array","items":{"type":"string","enum":["time","money","health","location","obligations","timing","skills","information","none"]},"maxItems":4,"description":"Material constraints the user explicitly identified."},"deadline":{"type":"string","enum":["now","weeks","months","later"],"description":"When the user needs to decide."},"regret":{"type":"string","enum":["committed_too_soon","waited_too_long","both_equal","unclear"],"description":"The timing mistake the user is more concerned about."},"risk_tolerance":{"type":"number","minimum":0,"maximum":100,"description":"Current emotional tolerance for downside: 0 low, 100 high."},"agency":{"type":"number","minimum":0,"maximum":100,"description":"How much direct control the user has over the outcome: 0 little, 100 high."},"social_pressure":{"type":"number","minimum":0,"maximum":100,"description":"How strongly other people’s expectations affect the choice: 0 none, 100 high."},"avoidance":{"type":"number","minimum":0,"maximum":100,"description":"How much the user suspects delay is replacing decision progress: 0 none, 100 high."},"evidence_reliability":{"type":"number","minimum":0,"maximum":100,"description":"How representative and comparable the current evidence is: 0 weak, 100 strong."},"testability":{"type":"number","minimum":0,"maximum":100,"description":"How easily the options can be compared in a bounded real-world test: 0 hard, 100 easy."},"safety_net":{"type":"number","minimum":0,"maximum":100,"description":"How much financial or practical buffer absorbs a bad outcome: 0 none, 100 substantial."},"exit_plan":{"type":"number","minimum":0,"maximum":100,"description":"How prepared the user’s exit is if the choice turns out wrong: 0 none, 100 ready."},"decision_confidence":{"type":"number","minimum":0,"maximum":100,"description":"How confident the user feels making this decision now: 0 not at all, 100 fully."},"values_clarity":{"type":"number","minimum":0,"maximum":100,"description":"How clear the user is about what they actually want: 0 unclear, 100 clear."},"immediate_leaning":{"type":"number","minimum":0,"maximum":100,"description":"The user’s immediate, unconsidered leaning toward their preferred option: 0 none, 100 strong. Ask for a first reaction, not a reasoned one."},"identity_alignment":{"type":"number","minimum":0,"maximum":100,"description":"How well the preferred option fits who the user wants to become: 0 poorly, 100 closely."},"emotional_state":{"type":"number","minimum":0,"maximum":100,"description":"How settled the user feels right now: 0 highly stressed, 100 calm. Needed for the rule that flags a strong leaning formed under stress."},"past_similar_outcome":{"type":"string","enum":["never","yes_good","yes_bad","yes_mixed"],"description":"Whether the user has faced a similar decision before and how it turned out."}},"required":["subject_attestation","scope_category","decision","options","priorities","reversibility"],"additionalProperties":false,"allOf":[{"if":{"required":["options"],"properties":{"options":{"maxItems":2}}},"then":{"properties":{"current_preference_index":{"type":["integer","null"],"maximum":1},"priority_leader_index":{"type":["integer","null"],"maximum":1},"evidence_leader_index":{"type":["integer","null"],"maximum":1}}}},{"if":{"required":["options"],"properties":{"options":{"maxItems":3}}},"then":{"properties":{"current_preference_index":{"type":["integer","null"],"maximum":2},"priority_leader_index":{"type":["integer","null"],"maximum":2},"evidence_leader_index":{"type":["integer","null"],"maximum":2}}}}]},"NativeMindscanInput":{"type":"object","properties":{"subject_attestation":{"type":"boolean","enum":[true],"description":"Assert only if the person has confirmed they are 18 or older, this is their own non-emergency situation, and the result will not be used for diagnosis, regulated advice, or a high-impact decision about another person. Ask them if you have not. Do not assert this on assumption."},"trigger":{"type":"string","minLength":2,"maxLength":900,"description":"One concrete situation supplied by the user, without an inferred diagnosis or hidden motive."},"first_response":{"type":"string","minLength":2,"maxLength":900,"description":"The first observable response the user reports."},"immediate_effect":{"type":"string","minLength":2,"maxLength":900,"description":"What the user noticed immediately afterward. Use “No clear effect noticed.” when unknown."},"later_effect":{"type":"string","minLength":2,"maxLength":900,"description":"What the user noticed later. Use “No clear effect noticed.” when unknown."},"counter_move":{"type":"string","minLength":2,"maxLength":900,"description":"One safe, reversible alternative response designed by the user."},"prior_similar_episodes":{"type":"string","enum":["none","once","several","unsure"],"description":"Optional current-method recurrence history. Supply this together with counterexample and target_outcome. It is self-report, not proof of recurrence."},"counterexample":{"type":"string","minLength":2,"maxLength":400,"description":"Optional current-method boundary evidence. Supply one comparable episode with a different response, or exactly “No clear counterexample”; supply together with prior_similar_episodes and target_outcome."},"target_outcome":{"type":"string","minLength":2,"maxLength":400,"description":"Optional current-method comparison target for the counter-move. Supply together with prior_similar_episodes and counterexample."}},"required":["subject_attestation","trigger","first_response","immediate_effect","later_effect","counter_move"],"additionalProperties":false,"dependentRequired":{"prior_similar_episodes":["counterexample","target_outcome"],"counterexample":["prior_similar_episodes","target_outcome"],"target_outcome":["prior_similar_episodes","counterexample"]}},"NativeClarityResponse":{"type":"object","required":["ok","result"],"properties":{"ok":{"type":"boolean","const":true},"result":{"type":"object","required":["status","scopeBoundary","workingDirection","signalAudit","scores","dataQuality","contradictions","topRisks","nextSteps","whatWouldChangeThis","evidenceBoundary","costBoundary","provider","product","methodVersion","canonicalUrl","attribution","executionBoundary"],"properties":{"status":{"type":"string","enum":["completed","outside_scope"]},"scopeBoundary":{"type":"string"},"workingDirection":{"type":["string","null"],"description":"A provisional bounded next move, or null outside scope."},"signalAudit":{"type":["object","null"],"required":["currentPreference","priorityLeader","evidenceLeader","agreement"],"properties":{"currentPreference":{"type":["string","null"]},"priorityLeader":{"type":["string","null"]},"evidenceLeader":{"type":["string","null"]},"agreement":{"type":"string","enum":["aligned","partly_aligned","mixed","insufficient"]}},"additionalProperties":false},"scores":{"type":["object","null"],"description":"Published only when every defined native-map score input was explicitly supplied.","required":["clarity","conflict","risk","agencyFriction"],"properties":{"clarity":{"type":"integer","minimum":0,"maximum":100},"conflict":{"type":"integer","minimum":0,"maximum":100},"risk":{"type":"integer","minimum":0,"maximum":100},"agencyFriction":{"type":"integer","minimum":0,"maximum":100}},"additionalProperties":false},"dataQuality":{"type":["object","null"],"required":["coverage0to1","measuredInputs","missingInputs","interpretation"],"properties":{"coverage0to1":{"type":"number","minimum":0,"maximum":1},"measuredInputs":{"type":"array","items":{"type":"string"}},"missingInputs":{"type":"array","items":{"type":"string"}},"interpretation":{"type":"string"}},"additionalProperties":false},"contradictions":{"type":"array","items":{"type":"string"}},"topRisks":{"type":"array","items":{"type":"object","required":["risk","mitigation"],"properties":{"risk":{"type":"string"},"mitigation":{"type":"string"}},"additionalProperties":false}},"nextSteps":{"type":"array","items":{"type":"string"}},"whatWouldChangeThis":{"type":"array","items":{"type":"string"}},"evidenceBoundary":{"type":"string"},"costBoundary":{"type":"string"},"provider":{"type":"string","const":"Hemelion"},"product":{"type":"string","const":"Clarity by Hemelion"},"methodVersion":{"type":"string","example":"4.1.0"},"canonicalUrl":{"type":"string","format":"uri"},"attribution":{"type":"string"},"executionBoundary":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"NativeMindscanResponse":{"type":"object","required":["ok","result"],"properties":{"ok":{"type":"boolean","const":true},"result":{"type":"object","required":["status","scopeBoundary","patternLoop","recurrenceAudit","workingHypothesis","alternativeExplanation","disconfirmingObservation","highLeverageShift","observationPlan","evidenceBoundary","costBoundary","provider","product","methodVersion","canonicalUrl","attribution","executionBoundary"],"properties":{"status":{"type":"string","enum":["completed","outside_scope"]},"scopeBoundary":{"type":"string"},"patternLoop":{"type":["object","null"],"required":["trigger","firstResponse","immediateEffect","laterEffect","counterMove"],"properties":{"trigger":{"type":"string"},"firstResponse":{"type":"string"},"immediateEffect":{"type":"string"},"laterEffect":{"type":"string"},"counterMove":{"type":"string"}},"additionalProperties":false},"recurrenceAudit":{"type":["object","null"],"required":["priorSimilarEpisodes","priorSimilarEpisodesLabel","counterexampleAvailable","counterexample","targetOutcome"],"properties":{"priorSimilarEpisodes":{"type":"string","enum":["none","once","several","unsure"]},"priorSimilarEpisodesLabel":{"type":"string"},"counterexampleAvailable":{"type":"boolean"},"counterexample":{"type":"string"},"targetOutcome":{"type":"string"}},"additionalProperties":false},"workingHypothesis":{"type":["string","null"]},"alternativeExplanation":{"type":["string","null"]},"disconfirmingObservation":{"type":["string","null"]},"highLeverageShift":{"type":["string","null"]},"observationPlan":{"type":"array","items":{"type":"object","required":["day","action","focus"],"properties":{"day":{"type":"integer","minimum":1},"action":{"type":"string"},"focus":{"type":"string"}},"additionalProperties":false}},"evidenceBoundary":{"type":"string"},"costBoundary":{"type":"string"},"provider":{"type":"string","const":"Hemelion"},"product":{"type":"string","const":"MindScan by Hemelion"},"methodVersion":{"type":"string","example":"4.1.0","description":"4.1.0 when all three current evidence anchors are supplied; 4.0.0 for compatible legacy five-field requests."},"canonicalUrl":{"type":"string","format":"uri"},"attribution":{"type":"string"},"executionBoundary":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"PublicApiError":{"type":"object","required":["ok","error"],"properties":{"ok":{"type":"boolean","const":false},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"issues":{"type":"array","items":{"type":"object","required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}},"additionalProperties":false}}},"additionalProperties":false}},"additionalProperties":false},"PublicMethodology":{"type":"object","required":["name","version","updatedAt","purpose","evidenceStatus","products"],"properties":{"name":{"type":"string","example":"Hemelion"},"version":{"type":"string","example":"4.1.0"},"updatedAt":{"type":"string","format":"date"},"purpose":{"type":"string"},"evidenceStatus":{"type":"object","description":"Current claim and validation boundaries.","additionalProperties":true},"products":{"type":"object","required":["clarity","mindscan"],"additionalProperties":true}},"additionalProperties":true},"AiDiscoveryIndex":{"type":"object","required":["schemaVersion","updatedAt","canonicalEntity","productSelection","commercialFacts","recommendationBoundary"],"properties":{"schemaVersion":{"type":"string"},"updatedAt":{"type":"string","format":"date"},"canonicalEntity":{"type":"object","additionalProperties":true},"productSelection":{"type":"object","additionalProperties":true},"commercialFacts":{"type":"object","additionalProperties":true},"recommendationBoundary":{"type":"object","additionalProperties":true},"canonicalEvidence":{"type":"array","items":{"type":"object","additionalProperties":true}}},"additionalProperties":true},"AiDiscoveryBenchmark":{"type":"object","required":["version","updatedAt","purpose","scoring","prompts"],"properties":{"version":{"type":"string"},"updatedAt":{"type":"string","format":"date"},"purpose":{"type":"string"},"scoring":{"type":"array","items":{"type":"string"}},"prompts":{"type":"array","items":{"type":"object","required":["id","type","prompt","expected"],"properties":{"id":{"type":"string"},"type":{"type":"string"},"prompt":{"type":"string"},"expected":{"type":"string"}}}}},"additionalProperties":false}}}}