Assessments

Assessments are the core building block of Gradient. Each assessment defines a task, time limits, available data sources, and a scoring rubric.

List Assessments

curl https://app.trygradient.ai/api/assessments \
  -H "Authorization: Bearer gai_your_key"

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

GET /api/assessments

Returns all assessments in your organization.

limit

integer

default:"20"

Results per page (1-100)

offset

integer

default:"0"

Offset for pagination

isActive

boolean

Filter by active status

Response

{
  "assessments": [
    {
      "id": "uuid",
      "orgId": "uuid",
      "name": "Senior PM Assessment",
      "role": "Senior Product Manager",
      "taskPrompt": "Create a product strategy deck...",
      "deliverableType": "pptx",
      "taskTimeMinutes": 45,
      "bonusPhaseEnabled": false,
      "bonusPhaseMinutes": 0,
      "connectorConfig": [],
      "seededData": [],
      "availableSkills": [],
      "scoringRubric": { "..." : "..." },
      "candidatePermissions": {
        "can_browse_connector_documents": true,
        "can_add_custom_connectors": false,
        "can_add_skills": true,
        "can_edit_agents_md": true,
        "can_add_memory": true
      },
      "sendFeedback": false,
      "feedbackDelayHours": 24,
      "dueDate": null,
      "isActive": true,
      "createdAt": "2025-01-15T10:00:00Z",
      "updatedAt": "2025-01-15T10:00:00Z"
    }
  ],
  "total": 5,
  "limit": 20,
  "offset": 0
}

Get Assessment

GET /api/assessments/:id

Returns a single assessment by ID, plus the org’s branding (for candidate-facing display) and whether session-replay capture is enabled for the org.

Response

{
  "assessment": {
    "id": "uuid",
    "name": "Senior PM Assessment",
    "role": "Senior Product Manager",
    "taskPrompt": "Create a product strategy deck...",
    "deliverableType": "pptx",
    "..."
  },
  "orgBranding": {
    "logoUrl": "https://.../logo.png",
    "wordmarkUrl": null,
    "orgName": "Acme Inc"
  },
  "captureReplaysEnabled": false
}

orgBranding is null when the org row can’t be loaded.

Create Assessment

POST /api/assessments/create

Requires admin role (owner or admin).

name

string

required

Display name for the assessment

role

string

required

Target role (e.g. “Senior PM”)

taskPrompt

string

required

The task brief shown to candidates. For multi-phase assessments this is synthesized from the phases and is not required — send phases instead.

deliverableType

string

default:"pptx"

Top-level output format: pptx, docx, xlsx, email, or workflow. For multi-phase assessments this is the spine/default; the per-phase deliverableType inside phases governs each phase’s editor and the AI’s tools.

phases

array

Ordered list of phases for a multi-phase assessment. Each phase has its own label, deliverableType, taskPrompt, timeMinutes, and optional inboxConfig / workflowConfig. When provided, the top-level taskPrompt is optional and taskTimeMinutes should be the sum of phase times.

connectorConfig

array

Connectors (data sources) the candidate’s AI can search. Configured in the wizard’s Connectors & Data step; seed documents are attached on the assessment detail page after creation.

candidatePermissions

object

What candidates may do during the assessment. See Candidate Permissions for the keys and defaults.

adminGuide

object

Reviewer-facing notes: overview, goodAnswers, pitfalls, buriedInfo (array), and optional per-phase guidance.

taskTimeMinutes

integer

default:"45"

Total time limit for the assessment (minutes). For multi-phase assessments, the sum of the phase times.

setupTimeMinutes

integer

Time allotted for the (legacy) setup phase, in minutes. New assessments have no separate setup phase; leave unset.

jdLink

string

URL of the source job description this assessment was built from, if any.

dueDate

string

ISO 8601 deadline for the assessment

sendFeedback

boolean

default:"false"

deprecated

Deprecated. Automated candidate feedback is not currently delivered, and the toggle has been removed from the UI. The field is still accepted (defaults to false) but has no effect. feedbackDelayHours is likewise inert.

feedbackDelayHours

integer

deprecated

Deprecated companion to sendFeedback. Accepted but inert — automated candidate feedback is not currently delivered.

Response - 201 Created

{
  "assessment": {
    "id": "uuid",
    "name": "Senior PM Assessment",
    "..."
  }
}

Update Assessment

PATCH /api/assessments/:id

Send only the fields you want to update. Allowed fields: name, role, roleId, task_prompt, system_prompt, is_active, jd_link, due_date, scoring_rubric, bonus_phase_enabled, bonus_phase_minutes, setup_time_minutes, task_time_minutes, timer_mode, connector_config, candidate_permissions, phases, admin_guide, best_practices

Role

roleId is the id of an existing roles row to link (Plan 54’s Settings-tab role picker). When provided, the server resolves the role’s title and writes it to the denormalized role string, then reconciles the assessment_roles join table (unlinking whatever was previously linked, linking the new pick) — mirroring the sequence assessment creation already uses (insert with role.title, then a separate link call). role remains independently settable as a raw string for callers that don’t use the picker; sending both role and roleId in the same request lets roleId’s resolved title win. An unknown or soft-deleted roleId returns a not_found error rather than silently no-op-ing.

Best Practices

The best_practices field is a JSON array describing “what great looks like” for this task. It anchors the tactical suggestions candidates receive, and is also mined from top-scoring sessions (see Mine Best Practices). Each item:

Key	Type	Description
`id`	string	Stable identifier (generated if omitted)
`text`	string	The practice, phrased as a transferable habit
`source`	`"authored"` \| `"mined"`	Authored by an admin, or distilled from top sessions
`evidence`	string (optional)	Short generalized note on why high performers do this

Blank entries are dropped and a missing source defaults to "authored" on write.

send_feedback and feedback_delay_hours are still accepted for backward compatibility but are inert — automated candidate feedback is not currently delivered.

Candidate Permissions

The candidate_permissions field is a JSON object controlling what candidates can do during the assessment:

Key	Type	Default	Description
`can_browse_connector_documents`	boolean	`true`	Candidates can see individual documents within connectors
`can_add_custom_connectors`	boolean	`false`	Candidates can connect their own MCP servers
`can_add_skills`	boolean	`true`	Candidates can add/edit/toggle skills
`can_edit_agents_md`	boolean	`true`	Candidates can edit the AI system prompt
`can_add_memory`	boolean	`true`	Candidates can add persistent memory entries

Response

{
  "assessment": { "..." }
}

Mine Best Practices

POST /api/assessments/:id/best-practices/mine

Refresh the assessment’s mined best practices by distilling the recurring moves of its top-scoring candidates. Takes the top quartile by final_score, reads their prompts and strongest cited evidence, and generalizes a deduped list (no verbatim peer quotes). Authored practices are always preserved and take precedence over mined duplicates. Idempotent: re-running replaces the previously mined items. Requires at least 8 scored sessions to generalize reliably; below that it skips.

Response

Cohort large enough and practices distilled:

{
  "status": "ok",
  "cohortSize": 14,
  "topQuartileSize": 4,
  "minedCount": 5,
  "bestPractices": [
    { "id": "uuid", "text": "Quantify the recommendation with a specific figure.", "source": "mined", "evidence": "top performers cited hard numbers" }
  ]
}

Cohort too small (nothing mined):

{
  "status": "skipped_cohort_too_small",
  "cohortSize": 3,
  "minRequired": 8
}

Delete Assessment

DELETE /api/assessments/:id

Permanently deletes the assessment and all associated sessions, scores, events, connector data, and context documents.

This action is irreversible. All candidate data for this assessment will be permanently deleted.

Response

{
  "ok": true
}

Duplicate Assessment

POST /api/assessments/:id/duplicate

Requires admin role (owner or admin).

Clones the assessment into a brand-new, fully editable draft: is_active: false, a new id, and the name suffixed with ” (copy)”. Copies the scoring rubric (with calibrationHistory dropped — that audit trail belongs to the original’s scored sessions), phases, connector config, seeded data, available skills, admin guide, best practices, candidate permissions, and the linked role (if any). Does not copy candidates, sessions, scores, connector data, or context documents — the duplicate starts with zero candidates. Scoring and weights are frozen on an assessment once it’s published (is_active) or already has candidates, even if later un-published — this is the only way to change scoring at that point. The original is left completely untouched.

Response - 201 Created

{
  "assessment": {
    "id": "uuid",
    "name": "PM Case Study (copy)",
    "isActive": false,
    "...": "the rest of the Assessment object, matching GET /api/assessments/:id"
  }
}

Invite Candidate

POST /api/assessments/:id/invite

Creates a candidate (or finds an existing one by email) and generates an assessment session with a unique invite link. Sends an invitation email automatically unless sendEmail is false.

string

required

Candidate’s email address

name

string

required

Candidate’s display name

dueDate

string

ISO 8601 per-candidate deadline (overrides assessment-level deadline)

sendEmail

boolean

default:"true"

When false, Gradient does not send its default invitation email — the caller is expected to deliver a custom email using the returned inviteUrl. Only affects newly-created sessions; idempotent hits on an existing session never re-send (use POST /api/assessments/:id/invite/resend instead).

Response - 201 Created (new session)

{
  "session": {
    "id": "uuid",
    "token": "abc123"
  },
  "inviteUrl": "/assess/abc123"
}

If the candidate already has an active session for this assessment, returns 200 OK:

Response - 200 OK (existing session)

{
  "session": { "id": "uuid", "token": "abc123" },
  "message": "Candidate already has an active session",
  "inviteUrl": "/assess/abc123"
}

Batch Invite Candidates

POST /api/assessments/:id/invite/batch

Bulk version of POST /api/assessments/:id/invite: creates/re-uses a candidate and session for each {name, email} pair in one request, instead of one HTTP round trip per candidate. Each row is processed independently — one row failing (e.g. a bad email) doesn’t stop the rest — and the response reports a per-row outcome in the same order as the request.

candidates

array

required

Array of { name: string, email: string, dueDate?: string }. Max 500 per request; larger pastes should be split client-side.

sendEmail

boolean

default:"false"

Same semantics as the single-invite endpoint, applied to every row.

Response - 200 OK

{
  "results": [
    { "name": "Jane Smith", "email": "jane@example.com", "status": "created", "session": { "id": "uuid", "token": "abc123" }, "inviteUrl": "/assess/abc123" },
    { "name": "Alex Rivera", "email": "alex@example.com", "status": "existing", "session": { "id": "uuid", "token": "def456" }, "inviteUrl": "/assess/def456" },
    { "name": "Bad Row", "email": "not-an-email", "status": "error", "message": "Invalid email address" }
  ]
}

Resend Invite Email

POST /api/assessments/:id/invite/resend

Resends the invitation email for an existing session.

sessionId

string

required

The session ID to resend the invite for

Response

{
  "success": true
}

Export Invited Candidates (CSV)

GET /api/assessments/:id/sessions/export

Downloads the assessment’s invited candidates as a CSV file (Content-Type: text/csv, Content-Disposition: attachment). Columns: name, email, link, status, invited_at, submitted_at, due_date, where link is the candidate’s absolute /assess/:token URL. Org-scoped; admin or API-key auth.

Response - 200 OK (text/csv)

name,email,link,status,invited_at,submitted_at,due_date
Jane Smith,jane@example.com,https://app.trygradient.ai/assess/abc123,invited,2026-07-15T13:00:00Z,,
"Sousa, Alex",alex@example.com,https://app.trygradient.ai/assess/def456,submitted,2026-07-15T13:00:00Z,2026-07-15T14:10:00Z,

AI Draft (Assessment Wizard)

POST /api/assessments/ai-draft

Requires admin role (owner or admin).

Generates a suggested assessment configuration from a free-text description. Used by the “Start with AI” flow in the create-assessment wizard to pre-fill fields. Nothing is persisted — the response is a draft the user edits before calling POST /api/assessments/create.

description

string

required

Free-text description of what the assessment should measure (min 10 chars).

role

string

Optional target role hint; the model biases its draft toward this title.

deliverableType

string

Optional hint (pptx, docx, email, workflow). When omitted, the model picks one.

isMultiPhase

boolean

default:"false"

Hint that the assessment should be multi-phase. Populates adminGuide.phases.

guideOnly

boolean

default:"false"

Draft only the admin guide (used by the “Draft from task prompt” button on the admin-guide wizard step).

existingTaskPrompt

string

When guideOnly is true, the existing task prompt the guide should describe.

existingRole

string

When guideOnly is true, the existing role the guide should describe.

Response

{
  "draft": {
    "name": "Ops Lead Inbox Triage",
    "role": "Operations Lead",
    "taskPrompt": "## Background\nYou are...",
    "deliverableType": "email",
    "adminGuide": {
      "overview": "...",
      "goodAnswers": "...",
      "pitfalls": "...",
      "buriedInfo": ["..."]
    }
  }
}

Refine assessment with AI

POST /api/assessments/chat-edit

Applies a natural-language instruction to an assessment’s task brief (used by the build wizard’s “Refine with AI” panel) and returns the whole updated draft plus a short reply. Echoes the input unchanged when the model is unavailable.

taskPrompt

string

required

The current task brief to refine.

userMessage

string

required

The instruction, e.g. “make the task harder” or “add a contradiction in the data”.

name

string

The current assessment name (may be updated).

messages

array

Prior conversation turns for context ({ role: "user" | "assistant", content }). Only the most recent few are replayed to the model.

assessmentId

string

When present, the refine exchange is logged as product feedback for that assessment. It is never written into the brief itself.

Response

{
  "reply": "I made the task harder by adding a conflicting data point.",
  "draft": {
    "name": "Ops Lead Inbox Triage",
    "taskPrompt": "## Background\nYou are..."
  }
}

​Assessments

​List Assessments

​Get Assessment

​Create Assessment

​Update Assessment

​Role

​Best Practices

​Candidate Permissions

​Mine Best Practices

​Delete Assessment

​Duplicate Assessment

​Invite Candidate

​Batch Invite Candidates

​Resend Invite Email

​Export Invited Candidates (CSV)

​AI Draft (Assessment Wizard)

​Refine assessment with AI

Assessments

List Assessments

Get Assessment

Create Assessment

Update Assessment

Role

Best Practices

Candidate Permissions

Mine Best Practices

Delete Assessment

Duplicate Assessment

Invite Candidate

Batch Invite Candidates

Resend Invite Email

Export Invited Candidates (CSV)

AI Draft (Assessment Wizard)

Refine assessment with AI