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.

integer

default:"20"

Results per page (1-100)

integer

default:"0"

Offset for pagination

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_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).

string

required

Display name for the assessment

string

required

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

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.

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.

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.

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.

object

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

object

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

integer

default:"45"

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

integer

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

string

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

string

ISO 8601 deadline for the assessment

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.

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_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

can_browse_connector_documents is deprecated. Candidates always see connector data files in the workspace Files cabinet, so the key has no effect and the admin UI no longer shows it. The API still accepts and returns it, and stored values are unchanged.

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

Soft-deletes the assessment (sets the deleted_at timestamp). This is the everyday delete, and it is reversible with Restore Assessment. The assessment no longer appears in the admin lists, but all sessions, scores, connector data, and files stay intact. In-flight sessions and scoring keep working, because by-id reads do not filter soft-deleted assessments. Requires owner or admin. To erase the data permanently, use Purge Assessment.

Response

{
  "ok": true
}

Restore Assessment

POST /api/assessments/:id/restore

Restores a soft-deleted assessment from the trash back to the admin lists (clears deleted_at). Requires owner or admin, the same as delete.

Response

{
  "assessment": {
    "id": "...",
    "name": "..."
  }
}

Purge Assessment

POST /api/assessments/:id/purge

Permanently erases the assessment, all its sessions, scores, events, connector data, and context documents, plus every backing Storage object (rrweb recordings, deliverable files, and data-room files). This action is irreversible. Only owners and admins can purge (capability assessments.purge). API-key callers have no role and are refused: a machine credential cannot trigger an irreversible erasure.

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

string

required

Candidate’s display name

string

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

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.

array

required

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

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.

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.

string

required

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

string

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

string

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

boolean

default:"false"

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

boolean

default:"false"

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

string

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

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

Answers a question about an assessment’s task brief, or applies a change to it (used by the build wizard’s “Refine with AI” panel). The response always has a reply. It has a draft only when the brief was changed. A question, or a request the brief is the wrong place for, returns the reply alone, and the caller leaves the brief as it is. draft is also absent when the model is unavailable or answers unusably.

string

required

The current task brief.

string

required

The question or the requested change, e.g. “make the deadline tighter”.

string

The current assessment name (may be updated).

array

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

string

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

Response (the brief changed)

{
  "reply": "I shortened the deadline to end of day Thursday.",
  "draft": {
    "name": "Ops Lead Inbox Triage",
    "taskPrompt": "## Background\nYou are..."
  }
}

Response (a question, no change)

{
  "reply": "Difficulty comes from the data room and the planted traps, so set it on the Answer key and Data steps. The brief can only tighten the word limit or the deadline."
}

Refine the task outline with AI

POST /api/assessments/chat-edit-outline

The same panel as above, for the build wizard’s Outline step. It edits the assessment DESIGN rather than the brief prose, which is the only change that can reshape the whole page at once: the brief, the data room and the answer key are all generated from these fields. As with the brief route, the response always has a reply and has a draft only when the design changed. Three things in the returned design are reconciled against the current one before it is accepted, so a model slip cannot break the assessment:

The priority skills keep their current skillId, skillName and order. They come from the role, and the scorecard is sized for them. Only how each one is observed may change.
Connectors must use a known categoryId, and duplicates are dropped. If nothing usable survives, the current connectors are kept.
deliverableType must be a known type, and a fork must keep at least two options.

Any field the model omits keeps its current value, and editedAt is stamped, so the steps generated from this design report themselves as out of date.

object

required

The current task outline.

string

required

The question or the requested change, e.g. “move this to a pricing decision”.

array

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

string

When present, the exchange is logged as product feedback for that assessment.

Response (the design changed)

{
  "reply": "Moved the decision to pricing and repointed the data sources at it.",
  "draft": {
    "name": "BrightCart pricing call",
    "deliverable": "A one-page decision memo for Maya Patel.",
    "editedAt": "2026-08-01T12:00:00.000Z"
  }
}

Overview

Endpoints

Assessments

Assessments

List Assessments

Get Assessment

Create Assessment

Update Assessment

Role

Best Practices

Candidate Permissions

Mine Best Practices

Delete Assessment

Restore Assessment

Purge Assessment

Duplicate Assessment

Invite Candidate

Batch Invite Candidates

Resend Invite Email

Export Invited Candidates (CSV)

AI Draft (Assessment Wizard)

Refine assessment with AI

Refine the task outline with AI

​Assessments

​List Assessments

​Get Assessment

​Create Assessment

​Update Assessment

​Role

​Best Practices

​Candidate Permissions

​Mine Best Practices

​Delete Assessment

​Restore Assessment

​Purge Assessment

​Duplicate Assessment

​Invite Candidate

​Batch Invite Candidates

​Resend Invite Email

​Export Invited Candidates (CSV)

​AI Draft (Assessment Wizard)

​Refine assessment with AI

​Refine the task outline with AI

Assessments

List Assessments

Get Assessment

Create Assessment

Update Assessment

Role

Best Practices

Candidate Permissions

Mine Best Practices

Delete Assessment

Restore Assessment

Purge Assessment

Duplicate Assessment

Invite Candidate

Batch Invite Candidates

Resend Invite Email

Export Invited Candidates (CSV)

AI Draft (Assessment Wizard)

Refine assessment with AI

Refine the task outline with AI