API Documentation

Base URL

Privacy

We don’t store personally identifiable information. The API does not use cookies. If you create a session, record a result, or set save=true, we store anonymized data (session ID, answers, derived scores, locale, timestamps) for aggregate statistics and research. Calls to /api/calculate with save=false are not stored. Cloudflare may process IP addresses in standard request logs for security.

See the data-flow explainer for a system-level overview.

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

{
  "result": {
    "type": "ENFP",
    "scores": { "EI": 18, "SN": 30, "TF": 16, "JP": 32 },
    "percentages": {
      "E": 69, "I": 31, "S": 31, "N": 69,
      "F": 75, "T": 25, "J": 25, "P": 75
    },
    "typeInfo": {
      "name": "Campaigner",
      "nickname": "The Champion",
      "description": "ENFPs are enthusiastic, creative...",
      "strengths": ["Curious", "Observant", "Energetic"],
      "weaknesses": ["Poor practical skills", "Difficult to focus"],
      "compatibleTypes": ["INTJ", "INFJ"],
      "famousExamples": ["Robin Williams", "Robert Downey Jr."]
    },
    "shareUrl": "https://openjung.org/en/result/ENFP-18-30-16-32"
  },
  "recordId": "550e8400-..." // Only when save=true
}

POST /api/record

Record a completed, anonymized test result. This is used by the OpenJung website to power aggregate statistics and research.

Request

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

{
  "answers": { "1": 3, "2": 4, "...": 2 },
  "result": {
    "type": "ENFP",
    "scores": { "EI": 18, "SN": 30, "TF": 16, "JP": 32 },
    "percentages": { "E": 69, "I": 31, "S": 31, "N": 69, "F": 75, "T": 25, "J": 25, "P": 75 }
  },
  "locale": "en"
}

Response

{
  "success": true,
  "recordId": "550e8400-..."
}

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

• Each dimension has 8 questions (32 total)
• Answers range from 1-5
• Raw scores per dimension: 8-40
• Score > 24 determines the dominant trait

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

Dimensions

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.