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.

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

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
{
  "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. 
{
  "assessment": {
    "id": "uuid",
    "name": "Senior PM Assessment",
    "role": "Senior Product Manager",
    "taskPrompt": "Create a product strategy deck...",
    "deliverableType": "pptx",
    "..."
  }
}

​
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
​
deliverableType
string
default:"pptx"
Output format: pptx, docx, xlsx, or email
​
taskTimeMinutes
integer
default:"45"
Total time limit for the assessment (minutes)
​
sendFeedback
boolean
default:"false"
Automatically send candidate feedback after scoring
​
feedbackDelayHours
integer
default:"24"
Hours before feedback is released
​
dueDate
string
ISO 8601 deadline for the assessment
{
  "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, task_prompt, system_prompt, is_active, send_feedback, feedback_delay_hours, due_date, scoring_rubric, bonus_phase_enabled, bonus_phase_minutes, connector_config, candidate_permissions

​
Candidate Permissions

The candidate_permissions field is a JSON object controlling what candidates can do during the assessment:
KeyTypeDefaultDescription
can_browse_connector_documentsbooleantrueCandidates can see individual documents within connectors
can_add_custom_connectorsbooleanfalseCandidates can connect their own MCP servers
can_add_skillsbooleantrueCandidates can add/edit/toggle skills
can_edit_agents_mdbooleantrueCandidates can edit the AI system prompt
can_add_memorybooleantrueCandidates can add persistent memory entries
{
  "assessment": { "..." }
}

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

​
Seed Sample Assessments

POST /api/assessments/seed
Creates pre-built sample assessments in your organization. Idempotent - skips assessments that already exist by name.
​
templateIndex
integer
Optional. If provided, seeds only the template at this index. Otherwise seeds all templates.
{
  "created": ["PM Case Study", "Strategy Analyst"],
  "skipped": 1
}

​
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.
​
email
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).
{
  "session": {
    "id": "uuid",
    "token": "abc123"
  },
  "inviteUrl": "/assess/abc123"
}
If the candidate already has an active session for this assessment, returns 200 OK: 
{
  "session": { "id": "uuid", "token": "abc123" },
  "message": "Candidate already has an active session",
  "inviteUrl": "/assess/abc123"
}

​
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
{
  "success": true
}

​
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, xlsx, email). 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.
{
  "draft": {
    "name": "Ops Lead Inbox Triage",
    "role": "Operations Lead",
    "taskPrompt": "## Background\nYou are...",
    "deliverableType": "email",
    "adminGuide": {
      "overview": "...",
      "goodAnswers": "...",
      "pitfalls": "...",
      "buriedInfo": ["..."]
    }
  }
}