Skip to main content
Nova versions criteria automatically. Every change to a job’s criteria creates a new version, and scoring jobs reference the version they used.

​
What is versioned

These operations create a new criteria version:
  • POST /v1/jobs/{jobId}/criteria/generate
  • POST /v1/jobs/{jobId}/criteria/items
  • PATCH /v1/jobs/{jobId}/criteria/items/{criterionId}
  • DELETE /v1/jobs/{jobId}/criteria/items/{criterionId}
  • DELETE /v1/jobs/{jobId}/criteria (archives the active version)

​
What you get back

Criteria endpoints return a flat array of criterion items: 
{
  "criteria": [
    {
      "id": "crit_a1b2c3d4e5f6",
      "text": "5+ years experience",
      "importance": "MUST_HAVE",
      "order": 0
    }
  ]
}
Version metadata (version number, status, timestamps) is available through dedicated version endpoints:
  • GET /v1/jobs/{jobId}/criteria/versions/current
  • GET /v1/jobs/{jobId}/criteria/versions
  • GET /v1/jobs/{jobId}/criteria/versions/{criteriaVersionId}
Use Get Current Criteria Version when you need active criteria plus metadata in one response.
Criterion IDs are stable across versions. When you add, edit, or remove a criterion, a new criteria version is created internally, but each criterion keeps its original id. You can store a criterion ID and reuse it for subsequent operations.
Example: Edit preserves IDs
// 1. Generate criteria → note the criterion ID
// POST /v1/jobs/job-123/criteria/generate
{
  "criteria": [
    { "id": "crit_a1b2c3d4e5f6", "text": "5+ years experience", "importance": "MUST_HAVE", "order": 0 }
  ]
}

// 2. Edit that criterion → same ID in response
// PATCH /v1/jobs/job-123/criteria/items/crit_a1b2c3d4e5f6
// Body: { "importance": "PREFERRED" }
{
  "criterion": { "id": "crit_a1b2c3d4e5f6", "text": "5+ years experience", "importance": "PREFERRED", "order": 0 },
  "criteria": [
    { "id": "crit_a1b2c3d4e5f6", "text": "5+ years experience", "importance": "PREFERRED", "order": 0 }
  ]
}

​
How this affects scoring

When you submit a scoring request, Nova uses:
  • The job’s active criteria version by default
  • When you re-score (rescore: true), you can pin scoring to a specific version using criteriaVersionId
To re-score an application after updating criteria, set rescore: true. You can optionally set criteriaVersionId to force a specific version.

​
Auditability

This approach ensures:
  • Old scores remain tied to the criteria version used at the time
  • Criteria changes do not retroactively change historical results