A stateless, production-ready API for Big Five personality assessments. Choose between local development or AWS serverless deployment.
Run locally for development and testing
npm run dev → http://localhost:3000Production-ready with auto-scaling
./deploy.sh --stage prod💡 Getting a Live API: Deploy to AWS Lambda using the serverless branch, or run locally with npm run dev to test the API.
💡 Quick Test: Click the "Test API" button at the top of this page to test the API immediately!
cd web && npm run devServer runs on http://localhost:3000
curl -X POST http://localhost:3000/api/assessment/questions \
-H "Content-Type: application/json" \
-d '{"userId": "test-user"}'Or use the "Test API" button
🚀 Get a Live API: Deploy to AWS Lambda for a production-ready API endpoint.
git checkout aws-serverless./deploy.sh --stage prodAfter deployment, you'll get an API Gateway URL like:
https://abc123.execute-api.us-east-1.amazonaws.com/prod/assessment/questionsUse this URL in your applications for production API calls.
# Calculate personality results
curl -X POST YOUR_API_URL/assessment/results \
-H "Content-Type: application/json" \
-d '{
"assessmentId": "assessment_test-user_1234567890",
"answers": [
{"questionId": "43c98ce8-a07a-4dc2-80f6-c1b2a2485f06", "score": 4},
{"questionId": "d50a597f-632b-4f7b-89e6-6d85b50fd1c9", "score": 3}
],
"language": "en"
}'Replace YOUR_API_URL with your local URL or AWS API Gateway URL
GET/POST /assessment/questionsPOST /assessment/answersPOST /assessment/resultsGET /assessment/statusGET /assessment/historyAll endpoints work with both local development and AWS serverless deployment
/api/assessment/questionsFetch 120 personality assessment questions for a user. Supports both POST and GET methods.
{
"userId": "user123",
"language": "en"
}/api/assessment/questions?userId=user123&language=en{
"assessmentId": "assessment_user123_1643723456789",
"userId": "user123",
"questions": [
{
"id": "43c98ce8-a07a-4dc2-80f6-c1b2a2485f06",
"text": "Worry about things",
"keyed": "plus",
"domain": "N",
"facet": 1,
"choices": [
{"text": "Very Inaccurate", "score": 1, "color": 1},
{"text": "Moderately Inaccurate", "score": 2, "color": 2},
{"text": "Neither Accurate Nor Inaccurate", "score": 3, "color": 3},
{"text": "Moderately Accurate", "score": 4, "color": 4},
{"text": "Very Accurate", "score": 5, "color": 5}
]
}
],
"assessmentInfo": {
"name": "Johnson's IPIP NEO-PI-R",
"shortId": "b5-120",
"time": 10,
"questionsCount": 120,
"language": "en"
},
"status": "success"
}/api/assessment/answersValidate user answers before processing
{
"assessmentId": "assessment_user123_1643723456789",
"answers": [
{
"questionId": "43c98ce8-a07a-4dc2-80f6-c1b2a2485f06",
"score": 4
},
{
"questionId": "d50a597f-632b-4f7b-89e6-6d85b50fd1c9",
"score": 3
}
]
}{
"success": true,
"message": "Answers validated successfully. Store them on your side and use /api/assessment/results to calculate personality results.",
"assessmentId": "assessment_user123_1643723456789",
"answersCount": 1,
"status": "validated"
}/api/assessment/resultsCalculate personality assessment results from answers
{
"assessmentId": "assessment_user123_1643723456789",
"answers": [
{
"questionId": "43c98ce8-a07a-4dc2-80f6-c1b2a2485f06",
"score": 4
},
{
"questionId": "d50a597f-632b-4f7b-89e6-6d85b50fd1c9",
"score": 3
}
],
"language": "en"
}{
"assessmentId": "assessment_user123_1643723456789",
"results": {
"overall": {
"O": {"score": 45, "count": 10, "result": "high"},
"C": {"score": 32, "count": 10, "result": "neutral"},
"E": {"score": 50, "count": 10, "result": "high"},
"A": {"score": 28, "count": 10, "result": "low"},
"N": {"score": 25, "count": 10, "result": "low"}
},
"facets": {
"O": {
"1": {"score": 8, "count": 2, "result": "high"}
}
},
"generatedAt": "2024-01-01T00:00:00.000Z",
"rawScores": {
"O": {"score": 45, "count": 10},
"C": {"score": 32, "count": 10},
"E": {"score": 50, "count": 10},
"A": {"score": 28, "count": 10},
"N": {"score": 25, "count": 10}
}
},
"status": "completed",
"language": "en",
"answersProcessed": 1
}/api/assessment/statusGet basic information about an assessment. Useful for tracking assessment state.
/api/assessment/status?assessmentId=assessment_user123_1643723456789{
"assessmentId": "assessment_user123_1643723456789",
"userId": "user123",
"status": "info_only",
"message": "This is a stateless API. Track assessment status on your side.",
"apiType": "stateless"
}/api/assessment/historyGet user's assessment history. Returns empty array since this is a stateless API.
/api/assessment/history?userId=user123{
"userId": "user123",
"message": "This is a stateless API. Track assessment history on your side.",
"apiType": "stateless",
"history": [],
"note": "Use your own database to store and retrieve assessment history."
}Imagination, curiosity, creativity
Organization, responsibility, dependability
Sociability, energy, assertiveness
Cooperation, compassion, trust
Emotional stability, anxiety, mood
Built with ❤️ using Next.js, TypeScript, and Tailwind CSS
Supports both local development and AWS serverless deployment with 43 comprehensive tests