Quickstart
The minimum backend flow for running an assessment and collecting its report.
Base URL
Docs and SDKs use a base URL ending in /api. The examples below call /v1 on that same base URL.
http://localhost:4000/apihttps://api.psyforge.dev/apiMint an access token
Send the tenant API key as Authorization: Bearer to receive a short-lived JWT. Use that JWT for the following calls.
export PSYFORGE_API_BASE="https://api.psyforge.dev/api" curl -X POST "$PSYFORGE_API_BASE/v1/auth/token" \ -H "Authorization: Bearer $PSYFORGE_API_KEY"
Create an assessment session
Pick a framework and locale. Idempotency-Key makes a replay of the same request return the same session.
curl -X POST "$PSYFORGE_API_BASE/v1/sessions" \
-H "Authorization: Bearer $JWT" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"frameworkCode":"big-five","locale":"en","subjectRef":"candidate-001"}'Fetch the next item
Clients do not choose item order. The server returns the next item, or item null when the session has enough data.
curl "$PSYFORGE_API_BASE/v1/sessions/$SID/next-item" \ -H "Authorization: Bearer $JWT"
Submit a response
Send itemId with answerValue or answerText. For Likert items, answerValue is the numeric scale value.
curl -X POST "$PSYFORGE_API_BASE/v1/sessions/$SID/responses" \
-H "Authorization: Bearer $JWT" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"itemId":"$ITEM","answerValue":5}'Submit the session
Submitting closes the session. After this point the client should not submit more responses.
curl -X POST "$PSYFORGE_API_BASE/v1/sessions/$SID/submit" \ -H "Authorization: Bearer $JWT"
Generate and poll the report
To fetch by session, call POST /v1/sessions/SESSION_ID/reports and poll GET /v1/sessions/SESSION_ID/reports/latest until the result is ready and includes a download URL.
curl -s -X POST "$PSYFORGE_API_BASE/v1/sessions/$SID/reports" \
-H "Authorization: Bearer $JWT" \
-H "Content-Type: application/json" \
-d '{"locale":"en"}'
# Poll by session id (public/report lookup)
curl "$PSYFORGE_API_BASE/v1/sessions/$SID/reports/latest" \
-H "Authorization: Bearer $JWT"What's next?
Drill into the full reference or pick an SDK for your stack.