Sessions

A session represents a single tester’s run of a study. Sessions track state from creation through analysis, allowing you to control flow, retrieve notes, and collect feedback.

Endpoints

POST /api/sessions JWT

Create a new test session for a study

Request body

{
  "jobId": "job_abc123",
  "testerId": "user_xyz789",
  "variant": "A"
}

Field	Type	Required	Description
`jobId`	string	Yes	ID of the study to start a session for
`testerId`	string	Yes	ID of the tester participant
`variant`	string	No	A/B variant assignment (`A` or `B`). Auto-assigned if omitted.

Response

{
  "success": true,
  "data": {
    "sessionId": "sess_001",
    "jobId": "job_abc123",
    "testerId": "user_xyz789",
    "variant": "A",
    "status": "active",
    "createdAt": "2026-03-16T10:00:00Z"
  },
  "error": null,
  "metadata": null
}

GET /api/sessions/:id JWT

Retrieve details of a single test session

Path parameters

Parameter	Description
`id`	Session ID

Response

{
  "success": true,
  "data": {
    "sessionId": "sess_001",
    "jobId": "job_abc123",
    "testerId": "user_xyz789",
    "variant": "A",
    "status": "completed",
    "startedAt": "2026-03-16T10:00:00Z",
    "completedAt": "2026-03-16T10:32:00Z",
    "durationSeconds": 1920
  },
  "error": null,
  "metadata": null
}

Status values: active, paused, completed, analyzed, confirmed

POST /api/sessions/:id/complete JWT

Mark a test session as complete

Path parameters

Parameter	Description
`id`	Session ID

Request body

{
  "completedAt": "2026-03-16T10:32:00Z"
}

completedAt is optional. Defaults to the current server time.

Response

{
  "success": true,
  "data": {
    "sessionId": "sess_001",
    "status": "completed",
    "completedAt": "2026-03-16T10:32:00Z"
  },
  "error": null,
  "metadata": null
}

POST /api/sessions/:id/analyze JWT

Trigger AI analysis of a completed test session

Path parameters

Parameter	Description
`id`	Session ID

The session must be in completed status. Analysis runs asynchronously. Poll GET /api/sessions/:id until status transitions to analyzed.

Request body

None required.

Response

{
  "success": true,
  "data": {
    "sessionId": "sess_001",
    "status": "analyzing",
    "estimatedCompletionSeconds": 45
  },
  "error": null,
  "metadata": null
}

GET /api/sessions/:id/notes JWT

Retrieve all notes attached to a test session

Path parameters

Parameter	Description
`id`	Session ID

Response

{
  "success": true,
  "data": {
    "sessionId": "sess_001",
    "notes": [
      {
        "noteId": "note_001",
        "content": "Tester struggled with the checkout flow.",
        "timestamp": "2026-03-16T10:15:00Z",
        "authorId": "user_admin01"
      }
    ]
  },
  "error": null,
  "metadata": null
}

PATCH /api/sessions/:id/notes JWT

Add or update notes for a test session

Path parameters

Parameter	Description
`id`	Session ID

Provide noteId to update an existing note. Omit noteId to create a new one.

Request body

{
  "notes": [
    {
      "noteId": "note_001",
      "content": "Updated: tester recovered after second attempt."
    },
    {
      "content": "New note added post-session review."
    }
  ]
}

Response

{
  "success": true,
  "data": {
    "sessionId": "sess_001",
    "updatedCount": 1,
    "createdCount": 1
  },
  "error": null,
  "metadata": null
}

POST /api/sessions/:id/confirm JWT

Confirm a session to release payment to the tester

Path parameters

Parameter	Description
`id`	Session ID

Session must be in analyzed status. Confirmation triggers payout processing for the tester.

Request body

{
  "rating": 5,
  "comment": "Thorough and articulate tester."
}

Field	Type	Required	Description
`rating`	integer (1-5)	Yes	Quality rating of the test
`comment`	string	No	Optional internal comment

Response

{
  "success": true,
  "data": {
    "sessionId": "sess_001",
    "status": "confirmed",
    "payoutQueued": true,
    "confirmedAt": "2026-03-16T12:00:00Z"
  },
  "error": null,
  "metadata": null
}

POST /api/sessions/:id/feedback JWT

Submit tester feedback for a completed session

Path parameters

Parameter	Description
`id`	Session ID

Testers call this endpoint to leave structured feedback about the study after completing their test.

Request body

{
  "clarity": 4,
  "difficulty": 3,
  "technicalIssues": false,
  "comment": "Instructions were clear but the prototype had a broken back button."
}

Field	Type	Required	Description
`clarity`	integer (1-5)	Yes	How clear the study instructions were
`difficulty`	integer (1-5)	Yes	Perceived difficulty of the tasks
`technicalIssues`	boolean	Yes	Whether technical problems occurred
`comment`	string	No	Free-text feedback

Response

{
  "success": true,
  "data": {
    "sessionId": "sess_001",
    "feedbackId": "fb_001",
    "submittedAt": "2026-03-16T10:35:00Z"
  },
  "error": null,
  "metadata": null
}