Skip to main content

​
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

​
integer
default:"20"
Results per page (1-100)
​
integer
default:"0"
Offset for pagination
​
string
Filter by assessment
​
string
Filter by candidate
​
string
Filter by status: invited, setup, in_progress, submitted, scoring, scored, reviewed

​
Get Session

Returns a single session with candidate and assessment metadata.

​
Delete Session

Permanently deletes a session and all associated messages, events, and scores.
This action is irreversible.

​
Send Reminder

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.

​
Dismiss From Action Needed

Clears an overdue session from the dashboard’s “Action needed” list by stamping actionDismissedAt, or restores it with DELETE. Presentation only: this affects one list on the dashboard and changes nothing about the session, the candidate, or the reminder. Dismissal is per session, so a candidate who is overdue on two assessments still appears for the other one.
actionDismissedAt is null in the DELETE response.

​
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.
​
object
The current phase’s deliverable content (email state, document state, etc.)
​
integer
default:"0"
Seconds remaining on the current phase timer when the candidate advanced

​
Checkpoint Phase

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.
​
object
required
The current phase’s deliverable content (workflow state, email state, etc.)
​
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.

​
Reopen Session

Reopens a finished session at a chosen phase and gives the lost time back. Use it when a candidate loses the rest of an assessment to something outside their control, for example a sign-out that let the later phases expire empty. The phase clock does not start here. The chosen phase is put in a paused state, the session goes back to in_progress, and any score is marked superseded so a stale report cannot mail. The clock starts only when the candidate opens their link and resumes. That can be hours later, and no time is spent in between. Phases before fromPhaseIndex keep their work. The chosen phase and every phase after it are cleared, so the candidate does that work again.
Owner or admin only, and a human actor only. An API key has no role, so it gets 403. The action is gated at the sessions.reopen capability, the same tier as a permanent delete, because it discards work and supersedes a score a reviewer may already have read.
​
integer
required
Zero-based index of the phase to reopen at. Must be within the assessment’s phase list.
Send assessUrl to the candidate: The reopened session waits until they open it. Errors: 400 when fromPhaseIndex is not an integer of 0 or more, is out of range, or the assessment has no phases; 400 when the session has not started; 404 when the session is not in your organization.

​
Resume Reopened Phase

Starts the clock on a phase that an admin reopened. Called by the candidate workspace when the candidate clicks Resume.
This endpoint is authenticated via the candidate session token, not an API key. It is the only route that can start a paused clock, so an admin who opens the review render never spends the candidate’s minutes.
Safe to call more than once. If the clock is already running, the call changes nothing and returns the running clock, so a double-click, a reload, or a second tab cannot restart the phase.
timeRemaining is in seconds.

​
Get Session Events

Returns the event log for a session - every action the candidate took during the assessment. Useful for audit trails and session replay.
​
integer
default:"100"
Results per page
​
integer
default:"0"
Offset for pagination
​
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

​
Get Deliverable Versions

Returns every saved version of the session’s deliverable, oldest first. The deliverable holds one document per phase, so a draft the candidate replaces leaves no trace in the submitted state. This endpoint reads the deliverable_snapshot events behind it, which record the full deliverable about every 15 seconds and only when it changed. Without versionId the response lists the versions and their metadata, with no content. Supply versionId to read one version’s full state. Content is split out because one phase can hold hundreds of versions of a whole document. toolCallsSince lists the AI’s deliverable-writing tool calls recorded between the previous version and this one. It is an observation, not a statement about who wrote the version: the candidate can type in the same window, and a tool call can fail.
​
string
Read one version’s full state instead of the list. The id comes from a row of the list.

​
Record Session Chunk

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.
​
array
required
Batch of rrweb events for this chunk
​
integer
required
Client-assigned monotonic chunk sequence number (0-based, incremented once per flush)
​
string
required
ISO timestamp of the first event in the batch
​
string
required
ISO timestamp of the last event in the batch

​
Get Session 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.

​
Preview Feedback Report

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.
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.managerGrades is the reviewer’s own 0-4 grades for this session, keyed by sub-criterion id (scores.scoring_provenance.manager). These label the AI’s score for comparison and never change it — see Record a calibration grade.

​
Edit Feedback Report Content

Admin-only. Edits the prose of a candidate’s feedback report: the intro paragraph, the “What stood out” bullets, and the “Where to focus next” items. Every key is optional; only what you send is written, so one section can be updated without touching the others. Reorder and delete are expressed by sending the whole array in the order you want, minus anything you dropped. Each item is rebuilt against the known shape before it’s stored, so unknown keys are discarded. An item with blank text is dropped, and an empty array is accepted (deleting every item is a legitimate edit). Scores are not editable here by design. To disagree with a number, record a calibration grade instead — that labels the AI’s score without changing the candidate’s result.
Returns the saved content. Errors: 404 when the session has not been scored, 400 when a list is not an array or exceeds 20 items.
The candidate report is live-read, so an edit to an already-released report is visible to the candidate immediately. This route does not gate on feedback_released_at; the admin UI warns before saving in that case.

​
Preview Feedback Email

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.