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.

​
Scoring

The scoring engine evaluates submitted sessions using an LLM-as-judge approach across multiple categories. Scores include automated ratings, percentile rankings, and suggested follow-up interview questions.

​
Trigger Scoring

POST /api/scoring
Runs the automated scoring pipeline on a submitted session. Can also be used to re-score an already-scored session.
​
sessionId
string
required
The session to score
The session must be in submitted or scored status. Attempting to score a session in another status returns a 409 Conflict error.
curl -X POST https://app.trygradient.ai/api/scoring \
  -H "Authorization: Bearer gai_your_key" \
  -H "Content-Type: application/json" \
  -d '{"sessionId": "SESSION_ID"}'

{
  "score": {
    "id": "uuid",
    "sessionId": "uuid",
    "autoScores": {
      "categories": {
        "deliverable_quality": { "score": 22, "maxPoints": 30, "subCriteria": {} },
        "delegation": { "score": 7, "maxPoints": 10, "subCriteria": {} },
        "description": { "score": 11, "maxPoints": 15, "subCriteria": {} },
        "discernment": { "score": 12, "maxPoints": 15, "subCriteria": {} },
        "diligence": { "score": 8, "maxPoints": 10, "subCriteria": {} }
      },
      "rawTotal": 60,
      "finalTotal": 60
    },
    "finalScore": 60,
    "summaryText": "The candidate demonstrated strong...",
    "feedbackText": "Your deliverable showed...",
    "followUpQuestions": [
      {
        "categoryId": "discernment",
        "question": "I noticed you accepted the AI's revenue figures without cross-checking. Walk me through your verification process.",
        "rationale": "The deliverable contained a revenue figure that didn't match the seeded earnings report.",
        "lookFor": "Strong: acknowledges the gap. Weak: doesn't recognize the error."
      }
    ],
    "percentileThisAssessment": 85,
    "percentileCategory": 72,
    "percentileGlobal": 68,
    "scoredAt": "2025-01-15T12:00:00Z"
  }
}

{
  "error": {
    "code": "conflict",
    "message": "Session is in 'in_progress' status and cannot be scored. Must be 'submitted' or 'scored'."
  }
}

​
Get Score

GET /api/scoring/:sessionId
Retrieves the score record for a session. 
{
  "score": {
    "id": "uuid",
    "sessionId": "uuid",
    "autoScores": { "..." },
    "adminScores": null,
    "finalScore": 78,
    "summaryText": "...",
    "feedbackText": "...",
    "percentileThisAssessment": 85,
    "percentileCategory": 72,
    "percentileGlobal": 68,
    "scoredAt": "2025-01-15T12:00:00Z",
    "reviewedAt": null,
    "reviewedById": null
  }
}

​
Override Score (Admin Review)

PATCH /api/scoring/:sessionId
Applies admin score overrides and marks the session as reviewed. Use this when a human reviewer wants to adjust the automated scores.
​
adminScores
object
required
Admin-assigned scores by category (e.g. {"deliverable_quality": 25, "delegation": 8})
​
notes
string
Review notes
{
  "score": {
    "id": "uuid",
    "sessionId": "uuid",
    "autoScores": { "..." },
    "adminScores": { "deliverable_quality": 25, "delegation": 8 },
    "finalScore": 65,
    "reviewedAt": "2025-01-16T09:00:00Z",
    "reviewedById": "uuid"
  }
}