Generate Clarification Questions

@nova-sdk/api

import { Nova } from "@nova-sdk/api";

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

const result = await nova.jobs.questionSets.create({
  jobId: "job_abc123",
  body: {
    jobContext: {
      jobTitle: "Senior Software Engineer",
      companyName: "Acme Corp",
      jobDescription: "We are looking for a senior engineer...",
    },
  },
});

curl -X POST "https://embed.nova.dweet.com/v1/jobs/job_abc123/question-sets" \
  -H "Authorization: Bearer sk_test_..." \
  -H "X-Tenant-Id: acme-corp" \
  -H "Content-Type: application/json" \
  -d '{
  "jobContext": {
    "jobTitle": "Senior Software Engineer",
    "companyName": "Acme Corp",
    "jobDescription": "We are looking for a senior engineer..."
  }
}'

{
  "questionSet": {
    "id": "<string>",
    "jobId": "<string>",
    "questions": [
      {
        "id": "<string>",
        "question": "<string>",
        "selectionType": "single",
        "options": [
          "<string>"
        ],
        "hint": "<string>"
      }
    ],
    "expiresAt": "2023-11-07T05:31:56Z",
    "guidance": "<string>"
  }
}

{
  "type": "<string>",
  "code": "UNAUTHORIZED",
  "status": 123,
  "message": "<string>",
  "retryable": true,
  "traceId": "<string>",
  "details": [
    {
      "field": "<string>",
      "code": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "type": "<string>",
  "code": "UNAUTHORIZED",
  "status": 123,
  "message": "<string>",
  "retryable": true,
  "traceId": "<string>",
  "details": [
    {
      "field": "<string>",
      "code": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "type": "<string>",
  "code": "UNAUTHORIZED",
  "status": 123,
  "message": "<string>",
  "retryable": true,
  "traceId": "<string>",
  "details": [
    {
      "field": "<string>",
      "code": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "type": "<string>",
  "code": "UNAUTHORIZED",
  "status": 123,
  "message": "<string>",
  "retryable": true,
  "traceId": "<string>",
  "details": [
    {
      "field": "<string>",
      "code": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "type": "<string>",
  "code": "UNAUTHORIZED",
  "status": 123,
  "message": "<string>",
  "retryable": true,
  "traceId": "<string>",
  "details": [
    {
      "field": "<string>",
      "code": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "type": "<string>",
  "code": "UNAUTHORIZED",
  "status": 123,
  "message": "<string>",
  "retryable": true,
  "traceId": "<string>",
  "details": [
    {
      "field": "<string>",
      "code": "<string>",
      "message": "<string>"
    }
  ]
}

POST

jobs

{jobId}

question-sets

@nova-sdk/api

import { Nova } from "@nova-sdk/api";

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

const result = await nova.jobs.questionSets.create({
  jobId: "job_abc123",
  body: {
    jobContext: {
      jobTitle: "Senior Software Engineer",
      companyName: "Acme Corp",
      jobDescription: "We are looking for a senior engineer...",
    },
  },
});

curl -X POST "https://embed.nova.dweet.com/v1/jobs/job_abc123/question-sets" \
  -H "Authorization: Bearer sk_test_..." \
  -H "X-Tenant-Id: acme-corp" \
  -H "Content-Type: application/json" \
  -d '{
  "jobContext": {
    "jobTitle": "Senior Software Engineer",
    "companyName": "Acme Corp",
    "jobDescription": "We are looking for a senior engineer..."
  }
}'

{
  "questionSet": {
    "id": "<string>",
    "jobId": "<string>",
    "questions": [
      {
        "id": "<string>",
        "question": "<string>",
        "selectionType": "single",
        "options": [
          "<string>"
        ],
        "hint": "<string>"
      }
    ],
    "expiresAt": "2023-11-07T05:31:56Z",
    "guidance": "<string>"
  }
}

{
  "type": "<string>",
  "code": "UNAUTHORIZED",
  "status": 123,
  "message": "<string>",
  "retryable": true,
  "traceId": "<string>",
  "details": [
    {
      "field": "<string>",
      "code": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "type": "<string>",
  "code": "UNAUTHORIZED",
  "status": 123,
  "message": "<string>",
  "retryable": true,
  "traceId": "<string>",
  "details": [
    {
      "field": "<string>",
      "code": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "type": "<string>",
  "code": "UNAUTHORIZED",
  "status": 123,
  "message": "<string>",
  "retryable": true,
  "traceId": "<string>",
  "details": [
    {
      "field": "<string>",
      "code": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "type": "<string>",
  "code": "UNAUTHORIZED",
  "status": 123,
  "message": "<string>",
  "retryable": true,
  "traceId": "<string>",
  "details": [
    {
      "field": "<string>",
      "code": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "type": "<string>",
  "code": "UNAUTHORIZED",
  "status": 123,
  "message": "<string>",
  "retryable": true,
  "traceId": "<string>",
  "details": [
    {
      "field": "<string>",
      "code": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "type": "<string>",
  "code": "UNAUTHORIZED",
  "status": 123,
  "message": "<string>",
  "retryable": true,
  "traceId": "<string>",
  "details": [
    {
      "field": "<string>",
      "code": "<string>",
      "message": "<string>"
    }
  ]
}

Optional but recommended. Answers to these questions produce better criteria.

Selection Types

Selection Type	Description	Answer Format
`single`	Choose one option (radio buttons)	`string`
`multi`	Choose multiple options (checkboxes)	`string[]`

Example Questions

Single Select
Multi Select

{
  "id": "q1",
  "selectionType": "single",
  "question": "What level of seniority are you targeting?",
  "options": [
    "Junior (0-2 years)",
    "Mid (2-5 years)",
    "Senior (5+ years)",
    "Lead/Staff"
  ],
  "hint": "Helps calibrate experience requirements"
}

{
  "id": "q2",
  "selectionType": "multi",
  "question": "Which skills are absolutely required vs nice-to-have?",
  "options": ["Go", "Rust", "Python", "Kubernetes", "AWS"],
  "hint": "Helps distinguish MUST_HAVE from NICE_TO_HAVE"
}

Stateful Behavior

Store the questionSetId to reference this question set later. If you don’t, fetch the latest via GET /v1/jobs/{jobId}/question-sets/current.

Each call creates a new question set. Multiple sets can exist for the same job.

Question sets expire. Check questionSet.expiresAt for the expiration time. Expired question sets are cleaned up per the Data Retention policy.

Latency

10-20 seconds (synchronous).

Next Step

After collecting answers, pass the questionSetId and answers to Generate Criteria.

Authorizations

Authorization

string

header

required

Use Authorization: Bearer sk_test_* or Authorization: Bearer sk_live_*.

Headers

X-Tenant-Id

string

required

Your customer identifier. Tenants are auto-provisioned on first request.

Idempotency-Key

string

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.

Required string length: 1 - 255

Path Parameters

jobId

string

required

Your job identifier (external ID).

Body

application/json

jobContext

object

required

Show child attributes

Response

Created

questionSet

object

required

Show child attributes

Getting started

Core concepts

API endpoints

Integration guides

SDKs

Legal

Generate Clarification Questions

Selection Types

Example Questions

Stateful Behavior

Latency

Next Step

Authorizations

Headers

Path Parameters

Body

Response

​Selection Types

​Example Questions

​Stateful Behavior

​Latency

​Next Step

Authorizations

Headers

Path Parameters

Body

Response

Selection Types

Example Questions

Stateful Behavior

Latency

Next Step