SoulTrace Personality Assessment

{
  "status": "in_progress",
  "question": {
    "id": 42,
    "text": "I find deep satisfaction in mastering complex systems."
  },
  "currentDistribution": {
    "white": 0.2,
    "blue": 0.2,
    "black": 0.2,
    "red": 0.2,
    "green": 0.2
  },
  "entropy": 2.322,
  "progress": { "answered": 0, "total": 24 }
}

Step 2: Answer questions

The user answers each question on a scale of 1-7:

• 1 = Strongly Disagree
• 4 = Neutral
• 7 = Strongly Agree

Append the answer and send all answers so far:

curl -X POST https://soultrace.app/api/agent \
  -H "Content-Type: application/json" \
  -d '{"answers": [{"questionId": 42, "score": 6}]}'

Keep accumulating answers. Each response gives the next question.

Step 3: Get results

After 24 answers, the response automatically returns the final result:

{
  "status": "complete",
  "resultId": "abc-123-def",
  "resultUrl": "https://soultrace.app/en/results/abc-123-def",
  "distribution": {
    "white": 0.15,
    "blue": 0.35,
    "black": 0.25,
    "red": 0.10,
    "green": 0.15
  },
  "entropy": 1.89,
  "archetype": {
    "key": "blue-black",
    "name": "Strategist",
    "alignmentScore": 87.3,
    "coreDynamic": "...",
    "strengths": ["..."],
    "weaknesses": ["..."]
  },
  "topMatches": [
    { "key": "blue-black", "name": "Strategist", "alignmentScore": 87.3 },
    { "key": "blue", "name": "Rationalist", "alignmentScore": 82.1 },
    { "key": "black-blue", "name": "Operator", "alignmentScore": 78.5 }
  ],
  "shadowColors": [
    { "color": "red", "score": 0.10 },
    { "color": "green", "score": 0.15 }
  ],
  "progress": { "answered": 24, "total": 24 }
}

Agent Interaction Protocol

When a user asks to take the personality test:

1. Start by calling the API with {"answers": []}.
2. Present each question to the user clearly. Tell them to answer 1-7 (1=Strongly Disagree, 4=Neutral, 7=Strongly Agree).
3. Collect the user's numeric answer (1-7). If they give a non-numeric or descriptive answer, map it to the scale:
   • "strongly disagree" / "not at all" → 1
   • "disagree" / "not really" → 2
   • "slightly disagree" → 3
   • "neutral" / "maybe" / "sometimes" → 4
   • "slightly agree" → 5
   • "agree" / "yes" → 6
   • "strongly agree" / "absolutely" → 7
4. Accumulate answers and send ALL previous answers plus the new one each time.
5. After all 24 questions, present the results with:
   • Their archetype name and alignment score
   • Their color distribution (show as percentages)
   • Their top 3 archetype matches
   • The link to their full results page
6. Never skip questions or auto-answer on behalf of the user.

Score Scale

The 5 Colors

Rate Limits

• 100 requests per hour per IP
• Each test requires 25 requests (1 start + 24 answers)
• Maximum ~4 complete tests per hour

Error Handling

API Info

GET https://soultrace.app/api/agent

Returns API metadata (version, question count, score range).