Send a message to the AI assistant (experimental — Soul Document prompt)

Experimental variant of /api/ai/personal/qanda. Identical request / response contract and Socket.IO streaming semantics, but the system prompt is generated by the Soul Document V1 prompt generator (getSoulDocumentPrompt / getSoulDocumentPromptBypassed) instead of the production fragmented-prompt generator. Used for A/B testing prompt architectures against the classic production endpoint.

Behavior parity with /api/ai/personal/qanda:

• Same inputs[] + requestArgs request shape.
• Same Socket.IO streaming (provide requestArgs.socketId for RECEIVE_STREAM chunks; omit for synchronous response).
• Same downstream middleware chain (creditCheck, contentFilterCheck, creditPayment, saveToHistory, sendResponse).

Differences vs. /api/ai/personal/qanda:

• req.locals.experimental = true and req.locals.promptMode = 'soul' are stamped on the history record for downstream comparison.
• Error emails are sent with an EXPERIMENTAL ENDPOINT label so they can be filtered out of production triage.
• The handler re-loads the user via its own User.findOne({_id}) and populates institution + institution.account directly, instead of consuming req.locals.resolvedUser produced upstream. The resolveInstitution middleware still runs (so institutionPublicId is validated and the institution switch is persisted), but the user object the handler operates on is fresh from this re-load — matching the soul-comparison harness’s expectations.

See docs/plans/2026-02-01-soul-document-experiment-design.md and test/soul-comparison/runner.js for the A/B harness that drives this endpoint.

POST /api/ai/experimental/personal/qanda

Send a message to the AI assistant (experimental — Soul Document prompt)

cURL

curl --request POST \
  --url https://pria.praxislxp.com/api/ai/experimental/personal/qanda \
  --header 'Content-Type: application/json' \
  --header 'x-access-token: <api-key>' \
  --data '
{
  "id": 1750660464754,
  "requestArgs": {
    "userISODate": "2025-06-23T06:34:24.754Z",
    "userTimezone": "America/New_York",
    "socketId": "DhXE7OVjCtfUmDFTAAAB",
    "assistantId": "6856fa89cbafcff8d98680f5",
    "selectedCourse": {
      "course_id": 1750532703472,
      "course_name": "Research Discussion",
      "assistant": {
        "_id": "6856fa89cbafcff8d98680f5"
      }
    },
    "ragOnly": false,
    "ragIgnore": false
  },
  "inputs": [
    "What is machine learning?"
  ],
  "outputs": []
}
'

200

{
  "success": true,
  "streamingFailed": false,
  "outputs": [
    "Machine learning is a subset of artificial intelligence..."
  ],
  "usage": 1234,
  "credits": 5,
  "query_duration_ms": 2500,
  "model": "gpt-4o"
}

Authorizations

x-access-token · string · header · required

JWT token passed in x-access-token header

Body

application/json

Request payload for AI Q&A conversation

inputs · string[] · required

User messages to send to the AI

Example:

["What is machine learning?"]

id · number

Client-generated request identifier (epoch timestamp)

Example:

1750660464754

requestArgs · object

Context arguments for AI conversation requests

Show child attributes

outputs · string[]

Previous AI responses (for context continuity)

Example:

[]

Response

200

application/json

AI response generated successfully (Soul Document V1 system prompt)

Response from AI Q&A conversation

success · boolean

Whether the request completed successfully

streamingFailed · boolean

True if Socket.IO streaming failed (response still contains full output)

streamingError · string

Error message if streaming failed

outputs · string[]

AI-generated response messages

usage · number

Total tokens consumed (input + output)

credits · number

Credits consumed for this request

creditsUsed · number

User's total credits consumed

totalCredits · number

User's remaining credit balance

query_duration_ms · number

Total processing time in milliseconds

model · string

AI model identifier used for generation

Example:

"gpt-4o"