Developer Resources
API Documentation
Integrate the personality test into your applications and AI workflows
Base URL
https://openjung.org/api 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, orzh-tw(defaults toen) -
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) orzh
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 trait2= Somewhat agree with left trait3= Neutral4= Somewhat agree with right trait5= 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.
MCP Server (for AI Agents)
The personality test is also available as a remote MCP server for AI agents like Claude,
Cursor, and other MCP-compatible clients. Connect using Streamable HTTP. MCP supports
English (en) and Chinese (
zh).
https://mcp.openjung.org/mcp -
Call
get_questionsand retain itsassessmentVersionbefore collecting the person's answers. Never invent answers or fill missing answers with 3. -
quick_testis the historical name for a one-call full 32-question assessment, not the website's 8-question quick mode. It requires the current version and all 32 answers. For interactive quick/full tests, submit the exact question IDs,modeandassessmentVersionreturned bystart_test_interactive. -
Session tools persist data; one-call scoring tools also attempt to save completed
results. Explain this before collecting answers. If
saved=false, there is no persistedrecordId. Saving does not imply research consent. Use the returnedshareUrlrather than reconstructing a result link.
See the MCP contract for tool inputs, persistence, version compatibility and release checks.
Need client configuration snippets? Visit Integrations for Claude Desktop and Claude Code setup commands.