API Documentation

Base URL

Privacy

Website tests are scored on the user's device; API and MCP calls have different storage behavior. /api/calculate does not save assessment records when save=false (the default). Session APIs persist answers and results. Saving a record does not opt a person into research. Explain storage before collecting answers. Result links disclose the type and scores they contain, and hosting services may process IP addresses and request metadata.

Basic website analytics is on by default with an opt-out; research contribution and optional usage measurement are separate opt-in choices. See Privacy and the data-flow explainer.

POST /api/calculate (Recommended)

Submit all 32 answers at once and get the result immediately. This is the simplest way to use the API.

Request

POST /api/calculate
Content-Type: application/json

{
  "answers": {
    "1": 3, "2": 4, "3": 2, "4": 5, "5": 3, "6": 4, "7": 2, "8": 5,
    "9": 3, "10": 4, "11": 2, "12": 5, "13": 3, "14": 4, "15": 2, "16": 5,
    "17": 3, "18": 4, "19": 2, "20": 5, "21": 3, "22": 4, "23": 2, "24": 5,
    "25": 3, "26": 4, "27": 2, "28": 5, "29": 3, "30": 4, "31": 2, "32": 5
  },
  "locale": "en",
  "save": false
}

Parameters

• answers (required): Object mapping question IDs (1-32) to answers (1-5)
• locale (optional): en, zh, ja, ko, or zh-tw (defaults to en)
• save (optional): Whether to save the result to database (default: false)

Response

The JSON response contains result.type, result.scores, result.percentages, result.typeInfo and result.shareUrl. Use the returned sharing link rather than constructing one. A recordId is present only after a successful save; a calculated result alone does not confirm storage. Type descriptions and legacy compatibility fields are not validated predictions.

POST /api/record

Contribute a completed assessment to research only with explicit consent. Without researchConsent: true, this endpoint returns recorded: false and stores no research record. Persistence through other APIs or MCP is not consent.

A contribution requires answers for exactly the selected questions, mode (quick or full), the current assessmentVersion and researchConsent: true; locale is optional. The server recomputes scores and ignores supplied result fields. Successful storage returns HTTP 201 with recorded: true and a recordId.

Session API

Create a persistent session and submit answers one by one. Sessions store answers server-side until completion. The session locale currently supports en and zh.

Endpoints

• POST /api/session
• GET /api/session/:id
• POST /api/session/:id/answer
• GET /api/session/:id/result

Submit Answer

POST /api/session/{id}/answer
Content-Type: application/json

{
  "questionId": 1,
  "answer": 4
}

GET /api/questions

Get all 32 test questions. Useful for displaying questions to users before collecting answers.

Query Parameters

• locale (optional): en (default) or zh

Response

{
  "totalQuestions": 32,
  "questions": [
    {
      "id": 1,
      "dimension": "JP",
      "leftTrait": "Makes lists",
      "rightTrait": "Relies on memory"
    },
    ...
  ]
}

Scoring System

Fetch the current questions before collecting answers. The full assessment has 32 questions, with 8 per dimension. Answer direction follows each returned trait pair; do not infer it from a dimension label or a copied question list. See the methodology and limitations. Percentages describe positions on a preference scale, not confidence that a type is correct.

Answer Scale

• 1 = Strongly agree with left trait
• 2 = Somewhat agree with left trait
• 3 = Neutral
• 4 = Somewhat agree with right trait
• 5 = Strongly agree with right trait

Quick Example

curl -X POST https://openjung.org/api/calculate \
  -H "Content-Type: application/json" \
  -d '{
    "answers": {
      "1": 3, "2": 4, "3": 2, "4": 5, "5": 3, "6": 4, "7": 2, "8": 5,
      "9": 3, "10": 4, "11": 2, "12": 5, "13": 3, "14": 4, "15": 2, "16": 5,
      "17": 3, "18": 4, "19": 2, "20": 5, "21": 3, "22": 4, "23": 2, "24": 5,
      "25": 3, "26": 4, "27": 2, "28": 5, "29": 3, "30": 4, "31": 2, "32": 5
    },
    "locale": "en"
  }'

Error Responses

{
  "error": "Error message",
  "code": "ERROR_CODE",
  "details": "Optional additional details"
}

• INVALID_PARAMS (400): Invalid question ID or answer value
• INCOMPLETE_ANSWERS (400): Not all 32 questions answered
• INVALID_BODY (400): Invalid JSON body

CORS & Rate Limiting

All endpoints support CORS and can be called from any origin.

Currently no rate limiting is enforced, but please be respectful with API usage.