> ## Documentation Index
> Fetch the complete documentation index at: https://nova.dweet.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Set Criteria

> Replace the entire criteria set for a job in one call

<Note>
  **Existing scores aren't affected.** A new criteria version is created when you replace criteria. Only future score requests use the updated set.
</Note>

## When to Use

Replace the entire criteria set for a job in a single call. This is useful when:

<CardGroup cols={2}>
  <Card title="Bulk Update" icon="arrows-rotate">
    You have the complete set of criteria and want to replace everything at once, rather than adding or removing one at a time
  </Card>

  <Card title="External Sync" icon="arrow-right-arrow-left">
    Your system manages criteria externally and needs to push the latest state to Nova
  </Card>
</CardGroup>

## Stable IDs

Criteria are matched by text. If a criterion with the same text already exists, its `id` is preserved. This means downstream references (stored IDs, audit logs) remain valid even after a full replacement.

## Clearing All Criteria

Pass an empty array to remove all criteria from a job:

```json theme={null}
{ "criteria": [] }
```

This behaves like a soft reset. You can add new criteria afterwards via this endpoint, [Add Criterion](/embed-api/endpoints/criteria/add), or [Generate Criteria](/embed-api/endpoints/criteria/generate).

<Tip>
  If the job is permanently closed, use [Archive Criteria](/embed-api/endpoints/criteria/archive) instead, which prevents future scoring.
</Tip>

## Response

The response includes the **full criteria list** after the replacement, making it easy to update your UI without a separate GET request.


## OpenAPI

````yaml PUT /v1/jobs/{jobId}/criteria
openapi: 3.1.0
info:
  title: Nova Embed API
  description: >-
    The Nova Embed API enables ATS platforms to generate job-scoped screening
    criteria and score applications asynchronously against those criteria.
  version: 1.0.0
  contact:
    name: Nova Support
    email: nova@dweet.com
servers:
  - url: https://embed.nova.dweet.com
    description: >-
      Environment is determined by API key prefix: sk_test_* for sandbox,
      sk_live_* for production.
security:
  - bearerAuth: []
tags:
  - name: Analytics
    description: View scoring performance, webhook health, and error breakdowns.
  - name: Criteria
    description: Generate and manage job-scoped screening criteria.
  - name: Scoring
    description: Submit applications for scoring and fetch scoring job results.
  - name: Deletion
    description: Request application or tenant deletion and poll for completion.
  - name: Criteria Library
    description: Manage tenant-scoped reusable criteria templates.
  - name: Rate Limits
    description: Check your current rate limit status.
  - name: Webhooks
    description: >-
      Events sent to your registered webhook endpoints. Verify signatures with
      HMAC-SHA256 using your webhook secret.
paths:
  /v1/jobs/{jobId}/criteria:
    put:
      tags:
        - Criteria
      summary: Replace all criteria
      description: >-
        Replace the entire criteria set for a job. Creates a new version,
        archiving any existing active version. Stable IDs are preserved for
        criteria with matching text. To reject stale writes, read
        criteriaRevision from Get current criteria version and pass it as
        X-Expected-Criteria-Revision.
      operationId: setCriteria
      parameters:
        - $ref: '#/components/parameters/TenantId'
        - $ref: '#/components/parameters/JobId'
        - $ref: '#/components/parameters/ExpectedCriteriaRevision'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetCriteriaRequest'
      responses:
        '200':
          description: Criteria replaced
          headers:
            X-RateLimit-Bucket:
              $ref: '#/components/headers/X-RateLimit-Bucket'
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetCriteriaResponse'
        '401':
          $ref: '#/components/responses/ErrorResponse'
        '409':
          $ref: '#/components/responses/ErrorResponse'
        '422':
          $ref: '#/components/responses/ErrorResponse'
        '429':
          $ref: '#/components/responses/RateLimitedResponse'
        '500':
          $ref: '#/components/responses/ErrorResponse'
      x-codeSamples:
        - lang: typescript
          label: '@nova-sdk/api'
          source: >-
            import { Nova } from "@nova-sdk/api";


            const nova = new Nova({
              apiKey: "sk_test_...",
              tenantId: "acme-corp",
            });


            const current = await
            nova.jobs.criteria.versions.getCurrent("job_abc123");


            const result = await nova.jobs.criteria.set("job_abc123", {
              criteria: [
                { text: "5+ years experience in TypeScript", importance: "MUST_HAVE" },
                { text: "Experience with React", importance: "NICE_TO_HAVE" },
              ],
            }, {
              expectedCriteriaRevision: current.criteriaRevision,
            });
        - lang: bash
          label: cURL
          source: >-
            curl -X PUT
            "https://embed.nova.dweet.com/v1/jobs/job_abc123/criteria" \
              -H "Authorization: Bearer sk_test_..." \
              -H "X-Tenant-Id: acme-corp" \
              -H "X-Expected-Criteria-Revision: crit_current_revision" \
              -H "Content-Type: application/json" \
              -d '{
              "criteria": [
                {
                  "text": "5+ years experience in TypeScript",
                  "importance": "MUST_HAVE"
                },
                {
                  "text": "Experience with React",
                  "importance": "NICE_TO_HAVE"
                }
              ]
            }'
components:
  parameters:
    TenantId:
      name: X-Tenant-Id
      in: header
      required: true
      description: Your customer identifier. Tenants are auto-provisioned on first request.
      schema:
        type: string
      example: acme-corp
    JobId:
      name: jobId
      in: path
      required: true
      description: Your job identifier (external ID).
      schema:
        type: string
    ExpectedCriteriaRevision:
      name: X-Expected-Criteria-Revision
      in: header
      required: false
      description: >-
        Optional criteria revision precondition for setCriteria. Get the current
        criteriaRevision from GET /v1/jobs/{jobId}/criteria/versions/current and
        pass it here to reject stale replacements.
      schema:
        type: string
      example: crit_1ab2cd
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: >-
        Optional key that makes criteria and library mutation requests safe to
        retry without duplicating side effects. The namespace is shared across
        all API keys for the same partner and environment. Reuse the same key
        when retrying the same request parameters.
      schema:
        type: string
        minLength: 1
        maxLength: 255
      example: 2d6d8d5a-6c4f-4c2f-8c6e-5b6f0d51a1b2
  schemas:
    SetCriteriaRequest:
      type: object
      required:
        - criteria
      additionalProperties: false
      properties:
        criteria:
          type: array
          items:
            type: object
            required:
              - text
              - importance
            additionalProperties: false
            properties:
              text:
                type: string
                minLength: 1
              importance:
                $ref: '#/components/schemas/CriterionImportance'
    GetCriteriaResponse:
      type: object
      required:
        - criteria
      properties:
        criteria:
          type: array
          items:
            $ref: '#/components/schemas/Criterion'
    CriterionImportance:
      type: string
      enum:
        - MUST_HAVE
        - PREFERRED
        - NICE_TO_HAVE
    Criterion:
      type: object
      required:
        - id
        - text
        - importance
        - order
        - createdAt
      properties:
        id:
          type: string
        text:
          type: string
        importance:
          $ref: '#/components/schemas/CriterionImportance'
        order:
          type: integer
        createdAt:
          type: string
          format: date-time
    HttpError:
      type: object
      required:
        - type
        - code
        - status
        - message
        - retryable
        - traceId
      properties:
        type:
          type: string
          description: URI reference that identifies the error type
        code:
          $ref: '#/components/schemas/ErrorCode'
        status:
          type: integer
          description: HTTP status code
        message:
          type: string
          description: Error message
        retryable:
          type: boolean
          description: When true, retrying the request may succeed
        traceId:
          type: string
          description: Trace ID for debugging
        details:
          type:
            - array
            - 'null'
          description: Field-level validation details
          items:
            type: object
            required:
              - field
              - code
              - message
            properties:
              field:
                type: string
              code:
                type: string
              message:
                type: string
    ErrorCode:
      type: string
      description: >-
        Machine-readable error code. Generated from the canonical error
        registry.
      enum:
        - UNAUTHORIZED
        - FORBIDDEN
        - VALIDATION_ERROR
        - ANSWER_MISMATCH
        - CRITERIA_INVALID
        - CRITERIA_REVISION_CONFLICT
        - NOT_FOUND
        - TENANT_NOT_FOUND
        - JOB_NOT_FOUND
        - APPLICATION_NOT_FOUND
        - QUESTION_SET_NOT_FOUND
        - CRITERIA_NOT_FOUND
        - CRITERION_NOT_FOUND
        - CRITERIA_VERSION_NOT_FOUND
        - SCORING_JOB_NOT_FOUND
        - BATCH_NOT_FOUND
        - LIBRARY_CRITERION_NOT_FOUND
        - RATE_LIMITED
        - MONTHLY_TRIAL_QUOTA_EXCEEDED
        - IDEMPOTENCY_KEY_ALREADY_USED
        - IDEMPOTENCY_REQUEST_IN_PROGRESS
        - RESUME_FETCH_FAILED
        - RESUME_CONVERSION_FAILED
        - RESUME_ENCRYPTED
        - RESUME_CORRUPTED
        - RESUME_PARSE_FAILED
        - RESUME_TOO_LARGE
        - RESUME_EMPTY
        - RESUME_URL_BLOCKED
        - AI_PROCESSING_FAILED
        - AI_GENERATION_FAILED
        - AI_SCORING_FAILED
        - MISSING_JOB_DESCRIPTION
        - TIMEOUT
        - MAX_RETRIES_EXCEEDED
        - TASK_STUCK
        - DELETION_REQUEST_NOT_FOUND
        - DELETION_REQUEST_FAILED
        - INTERNAL_ERROR
        - SERVICE_UNAVAILABLE
        - UNKNOWN
  headers:
    X-RateLimit-Bucket:
      description: Which rate limit bucket the request was classified into
      schema:
        type: string
        enum:
          - criteria_ai
          - criteria_current_reads
          - scoring_intake_batch
          - scoring_intake_single
          - read_and_ops
          - rate_limit_status
          - analytics
    X-RateLimit-Limit:
      description: Maximum requests per second for this bucket
      schema:
        type: integer
    X-RateLimit-Remaining:
      description: Requests remaining in the current 1-second window
      schema:
        type: integer
    X-RateLimit-Reset:
      description: Unix timestamp when the current window resets
      schema:
        type: integer
    Idempotent-Replayed:
      description: >-
        Present and set to "true" when the response is replayed from the
        idempotency cache
      schema:
        type: string
        enum:
          - 'true'
    Retry-After:
      description: >-
        Seconds to wait before retrying a short-window RATE_LIMITED or
        service-unavailable response whose body has retryable: true.
      schema:
        type: integer
    X-RateLimit-Degraded:
      description: >-
        Present and set to "true" when rate limiting is operating in degraded
        mode (Redis unavailable). Values in other rate limit headers are
        best-effort estimates.
      schema:
        type: string
        enum:
          - 'true'
  responses:
    ErrorResponse:
      description: Error response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/HttpError'
    RateLimitedResponse:
      description: >-
        Too many requests. Short-window RATE_LIMITED responses include retry
        timing and rate limit headers. Monthly trial quota responses use
        MONTHLY_TRIAL_QUOTA_EXCEEDED with retryable: false.
      headers:
        Retry-After:
          $ref: '#/components/headers/Retry-After'
        X-RateLimit-Bucket:
          $ref: '#/components/headers/X-RateLimit-Bucket'
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
        X-RateLimit-Degraded:
          $ref: '#/components/headers/X-RateLimit-Degraded'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/HttpError'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: 'Use Authorization: Bearer sk_test_* or Authorization: Bearer sk_live_*.'

````