Sessions

A session represents one candidate’s attempt at one assessment. Sessions progress through a defined lifecycle from invitation to review. Session statuses: invited → setup → in_progress → submitted → scoring → scored → reviewed

List Sessions

GET /api/sessions

limit

integer

default:"20"

Results per page (1-100)

offset

integer

default:"0"

Offset for pagination

assessmentId

string

Filter by assessment

candidateId

string

Filter by candidate

status

string

Filter by status: invited, setup, in_progress, submitted, scoring, scored, reviewed

curl "https://app.trygradient.ai/api/sessions?status=submitted" \
  -H "Authorization: Bearer gai_your_key"

const res = await fetch(
  'https://app.trygradient.ai/api/sessions?status=submitted',
  { headers: { Authorization: `Bearer ${apiKey}` } }
);
const { sessions, total } = await res.json();

Response

{
  "sessions": [
    {
      "id": "uuid",
      "assessmentId": "uuid",
      "candidateId": "uuid",
      "token": "abc123",
      "status": "submitted",
      "setupStartedAt": "2025-01-15T10:00:00Z",
      "taskStartedAt": "2025-01-15T10:15:00Z",
      "submittedAt": "2025-01-15T11:00:00Z",
      "dueDate": null,
      "createdAt": "2025-01-15T09:00:00Z",
      "candidateName": "Jane Smith",
      "candidateEmail": "jane@example.com",
      "assessmentName": "Senior PM Assessment"
    }
  ],
  "total": 8,
  "limit": 20,
  "offset": 0
}

Get Session

GET /api/sessions/:sessionId

Returns a single session with candidate and assessment metadata.

Response

{
  "session": {
    "id": "uuid",
    "assessmentId": "uuid",
    "candidateId": "uuid",
    "token": "abc123",
    "status": "scored",
    "candidateName": "Jane Smith",
    "candidateEmail": "jane@example.com",
    "assessmentName": "Senior PM Assessment",
    "setupStartedAt": "2025-01-15T10:00:00Z",
    "taskStartedAt": "2025-01-15T10:15:00Z",
    "submittedAt": "2025-01-15T11:00:00Z"
  }
}

Delete Session

DELETE /api/sessions/:sessionId

Permanently deletes a session and all associated messages, events, and scores.

This action is irreversible.

Response

{
  "ok": true
}

Send Reminder

POST /api/sessions/:sessionId/remind

Emails the candidate a due-date reminder for an incomplete session (status invited, setup, or in_progress) and stamps reminderSentAt. Uses the session’s due date, falling back to the assessment’s. Fails with 400 when the candidate has already submitted or there is no due date to remind about, and with 429 when a reminder was already sent within the last 24 hours.

Response

{
  "ok": true,
  "reminderSentAt": "2026-07-12T09:30:00Z"
}

Advance Phase

POST /api/sessions/:sessionId/advance-phase

Advances a multi-phase assessment session to the next phase. Saves the current phase’s deliverable state and resets the timer for the next phase. Called by the candidate workspace when the candidate clicks “Next Phase.”

This endpoint is authenticated via the candidate session token, not an API key.

deliverableState

object

The current phase’s deliverable content (email state, document state, etc.)

timeRemainingAtEnd

integer

default:"0"

Seconds remaining on the current phase timer when the candidate advanced

Response

{
  "ok": true,
  "newPhaseIndex": 1
}

Checkpoint Phase

POST /api/sessions/:sessionId/checkpoint

Saves the current phase’s deliverable state to the database without advancing or submitting. Enables interim saves so candidate work survives browser crashes and tab closes. The checkpoint is debounced client-side (3s) and fires after prompt edits and workflow runs.

This endpoint is authenticated via the candidate session token, not an API key.

deliverableState

object

required

The current phase’s deliverable content (workflow state, email state, etc.)

recordSnapshot

boolean

default:"false"

When true, also persist a point-in-time snapshot of the deliverable for the replay/history timeline, not just the latest interim save.

Response

{
  "ok": true
}

Get Session Events

GET /api/sessions/:sessionId/events

Returns the event log for a session - every action the candidate took during the assessment. Useful for audit trails and session replay.

limit

integer

default:"100"

Results per page

offset

integer

default:"0"

Offset for pagination

type

string

Filter by event type (see list below)

Event types: connector_browsed, connector_connected, connector_disconnected, skill_uploaded, skill_created, skill_activated (legacy), skill_enabled, skill_disabled, agents_md_edited, memory_added, user_message, ai_response, ai_tool_use, slash_command, manual_edit, slide_added, slide_deleted, slide_reordered, section_added, section_deleted, section_reordered, content_edited, deliverable_downloaded, deliverable_reuploaded, file_uploaded, task_submitted, time_expired, security_flag, ai_feedback, phase_advanced, inbox_item_opened, inbox_item_closed, workflow_run, workflow_prompt_edited, session_opened, session_resumed, session_disconnected, timer_warning, doc_viewed, web_search, chat_cleared, deliverable_text_typed, deliverable_paste Integrity event types (recorded for reviewer context only — never an auto-penalty): copy_detected, paste_detected, tab_blur, tab_focus, idle_gap, deliverable_paste

Response

{
  "events": [
    {
      "id": "uuid",
      "sessionId": "uuid",
      "timestampMs": 1705312800000,
      "phase": "task",
      "type": "user_message",
      "data": { "content": "..." },
      "createdAt": "2025-01-15T10:00:00Z"
    }
  ],
  "total": 156,
  "limit": 100,
  "offset": 0
}

Record Session Chunk

POST /api/sessions/:sessionId/recording

Appends one flushed batch of rrweb DOM-recording events (cursor, clicks, scroll, typing) as an ordered chunk, streamed from the candidate workspace every 5s. Fire-and-forget — a dropped chunk never surfaces to the candidate.

This endpoint is authenticated via the candidate session token, not an API key.

events

array

required

Batch of rrweb events for this chunk

seq

integer

required

Client-assigned monotonic chunk sequence number (0-based, incremented once per flush)

startedTs

string

required

ISO timestamp of the first event in the batch

endedTs

string

required

ISO timestamp of the last event in the batch

Response

{
  "ok": true
}

Get Session Recording

GET /api/sessions/:sessionId/recording

Returns the concatenated rrweb screen recording for a session (cursor, clicks, scroll, typing), used by the staff replay player. Recordings are only present for sessions taken after screen recording shipped; hasRecording is false otherwise.

Response

{
  "sessionId": "uuid",
  "hasRecording": true,
  "events": [{ "type": 2, "timestamp": 1705312800000 }],
  "startedMs": 1705312800000,
  "endedMs": 1705313400000,
  "chunkCount": 12
}

Preview Feedback Report

GET /api/sessions/:sessionId/feedback-preview

Admin-only preview of the candidate feedback report — the same data the candidate sees at their /assess/:token/feedback link, rendered on the candidate detail page. Unlike the candidate-facing route, this does not gate on release: it’s available as soon as the session is scored, whether or not feedback has actually been released to the candidate. Read-only; never sends anything or changes release state.

Response

{
  "sessionId": "uuid",
  "hasRecording": true,
  "feedbackText": "...",
  "headline": "...",
  "strengths": [{ "text": "...", "dimensionId": "deliverable" }],
  "weaknesses": [{ "text": "...", "dimensionId": "ai_fluency" }],
  "aiUseSuggestions": [{ "text": "...", "impact": "..." }],
  "assessmentName": "Senior PM Assessment",
  "role": "Senior PM",
  "finalScore": 82,
  "percentileGlobal": 74,
  "axes": [
    {
      "id": "deliverable",
      "name": "Deliverable",
      "score": 3.2,
      "max": 4,
      "subSkills": [
        { "id": "communication", "name": "Communication", "score": 3, "max": 4, "level": "strong", "source": "ai", "why": "Led with a clear recommendation" }
      ]
    }
  ],
  "feedbackReleasedAt": null,
  "release": {
    "releasedAt": null,
    "sendFeedback": false,
    "delayHours": 24,
    "scoredAt": "2025-01-15T10:00:00Z",
    "candidateEmail": "jane@example.com",
    "releaseDueAt": "2025-01-16T10:00:00Z"
  }
}

The release object mirrors the eligibility signals the release cron uses, so the Feedback tab can explain why a scored session’s feedback hasn’t gone out yet.

Preview Feedback Email

GET /api/sessions/:sessionId/email-preview

Admin-only preview of the candidate feedback email — builds the exact subject and HTML sendFeedbackEmail would send (same template, same score-derived content), but returns it as JSON instead of sending. Never calls the email provider.

Response

{
  "subject": "Your Gradient feedback report is ready, Jane.",
  "html": "<!DOCTYPE html>...",
  "to": "jane@example.com"
}

​Sessions

​List Sessions

​Get Session

​Delete Session

​Send Reminder

​Advance Phase

​Checkpoint Phase

​Get Session Events

​Record Session Chunk

​Get Session Recording

​Preview Feedback Report

​Preview Feedback Email

Sessions

List Sessions

Get Session

Delete Session

Send Reminder

Advance Phase

Checkpoint Phase

Get Session Events

Record Session Chunk

Get Session Recording

Preview Feedback Report

Preview Feedback Email