Skip to main content

Documentation Index

Fetch the complete documentation index at: https://trygradient.ai/docs/llms.txt

Use this file to discover all available pages before exploring further.

​
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"

{
  "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. 
{
  "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.
{
  "ok": true
}

​
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
{
  "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.)
{
  "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, 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 
{
  "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
}