---
title: "Create a compact native Clarity map for one decision."
method: POST
path: "/api/public/clarity-map"
tags: ["Native tools"]
---

# Create a compact native Clarity map for one decision.

`POST /api/public/clarity-map`

## Request

- Base URL: `https://www.hemelion.com`
- URL: `https://www.hemelion.com/api/public/clarity-map`
- Auth: none required

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.

## Request body

- NativeClarityInput
  - `subject_attestation` true, required: 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` 'general_personal' | 'general_business' | 'emergency_safety' | 'health_or_mental_health' | 'legal' | 'regulated_finance' | 'high_impact_third_party', required: Required safety classification. Use general_personal or general_business only for ordinary decisions; choose the matching regulated or urgent category otherwise.
  - `decision` string, required: One concrete decision stated in the user’s own words. Do not infer private facts.
  - `options` string[], required: Two or three real options supplied or confirmed by the user.
  - `priorities` string[], required: One to three priorities confirmed by the user.
  - `current_preference_index` integer, nullable: 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` integer, nullable: 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` integer, nullable: 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` number, required: How easy the first commitment is to reverse: 0 means very hard, 100 means very easy.
  - `constraints` string[]: Material constraints the user explicitly identified.
  - `deadline` 'now' | 'weeks' | 'months' | 'later': When the user needs to decide.
  - `regret` 'committed_too_soon' | 'waited_too_long' | 'both_equal' | 'unclear': The timing mistake the user is more concerned about.
  - `risk_tolerance` number: Current emotional tolerance for downside: 0 low, 100 high.
  - `agency` number: How much direct control the user has over the outcome: 0 little, 100 high.
  - `social_pressure` number: How strongly other people’s expectations affect the choice: 0 none, 100 high.
  - `avoidance` number: How much the user suspects delay is replacing decision progress: 0 none, 100 high.
  - `evidence_reliability` number: How representative and comparable the current evidence is: 0 weak, 100 strong.
  - `testability` number: How easily the options can be compared in a bounded real-world test: 0 hard, 100 easy.
  - `safety_net` number: How much financial or practical buffer absorbs a bad outcome: 0 none, 100 substantial.
  - `exit_plan` number: How prepared the user’s exit is if the choice turns out wrong: 0 none, 100 ready.
  - `decision_confidence` number: How confident the user feels making this decision now: 0 not at all, 100 fully.
  - `values_clarity` number: How clear the user is about what they actually want: 0 unclear, 100 clear.
  - `immediate_leaning` number: 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` number: How well the preferred option fits who the user wants to become: 0 poorly, 100 closely.
  - `emotional_state` number: 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` 'never' | 'yes_good' | 'yes_bad' | 'yes_mixed': Whether the user has faced a similar decision before and how it turned out.

## Response `200`

Attributed compact Clarity result or an explicit outside-scope boundary.

- NativeClarityResponse
  - `ok` true, required
  - `result` object, required
    - `status` 'completed' | 'outside_scope', required
    - `scopeBoundary` string, required
    - `workingDirection` string, nullable, required: A provisional bounded next move, or null outside scope.
    - `signalAudit` object, nullable, required
      - `currentPreference` string, nullable, required
      - `priorityLeader` string, nullable, required
      - `evidenceLeader` string, nullable, required
      - `agreement` 'aligned' | 'partly_aligned' | 'mixed' | 'insufficient', required
    - `scores` object, nullable, required: Published only when every defined native-map score input was explicitly supplied.
      - `clarity` integer, required
      - `conflict` integer, required
      - `risk` integer, required
      - `agencyFriction` integer, required
    - `dataQuality` object, nullable, required
      - `coverage0to1` number, required
      - `measuredInputs` string[], required
      - `missingInputs` string[], required
      - `interpretation` string, required
    - `contradictions` string[], required
    - `topRisks` object[], required
      - `risk` string, required
      - `mitigation` string, required
    - `nextSteps` string[], required
    - `whatWouldChangeThis` string[], required
    - `evidenceBoundary` string, required
    - `costBoundary` string, required
    - `provider` 'Hemelion', required
    - `product` 'Clarity by Hemelion', required
    - `methodVersion` string, required
    - `canonicalUrl` string, uri, required
    - `attribution` string, required
    - `executionBoundary` string, required

## Other responses

- `400`: Invalid JSON or input.
- `413`: Request body exceeds 32 KiB.
- `415`: Content-Type must be application/json.
- `429`: Public tool rate limit exceeded.

---

[API](https://skmtc.dev/hemelion/apis/hemelion-public-ai-and-evidence-api.md) · [All operations](https://skmtc.dev/hemelion/apis/hemelion-public-ai-and-evidence-api/llms.txt) · [OpenAPI document](https://skmtc.dev/hemelion/apis/hemelion-public-ai-and-evidence-api/revisions/663270ed83e2?raw)