> ## 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.
# Add to Library
> Save a criterion to the library for tenant-wide reuse
This endpoint isn't idempotent by default. If you send the same request twice without an `Idempotency-Key`, you'll create duplicate library entries.
If you're retrying after a timeout or network error, send an `Idempotency-Key` header and reuse it when retrying the exact same request.
## When to Use
Add criteria to the library when you've refined a criterion that works well and want to reuse it:
After testing a criterion produces expected scores, save it for reuse
Capture company-wide requirements like tenure expectations or culture fit
## Response
The response includes the created criterion:
```json theme={null}
{
"criterion": {
"id": "criterion_id",
"text": "Demonstrated job stability with 2+ years average tenure",
"importance": "NICE_TO_HAVE",
"category": "company-standards",
"createdAt": "2025-01-15T10:00:00Z"
}
}
```
## What to Save
Good fits for the library:
| Category | Examples |
| ---------------------- | ----------------------------------------------- |
| **Tenure & Stability** | "2+ years average tenure at previous roles" |
| **Work Style** | "Experience in distributed/remote teams" |
| **Communication** | "Strong written communication skills" |
| **Culture Fit** | "Examples of ownership and continuous learning" |
| **Compliance** | "Authorized to work in specified location" |
Avoid saving highly role-specific criteria to the library. Those should be generated or added per-job.
## OpenAPI
````yaml POST /v1/criteria-library
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/criteria-library:
post:
tags:
- Criteria Library
summary: Add a criterion to the library
operationId: addCriteriaLibraryCriterion
parameters:
- $ref: '#/components/parameters/TenantId'
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AddToLibraryRequest'
responses:
'201':
description: Created
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/AddToLibraryResponse'
'400':
$ref: '#/components/responses/ErrorResponse'
'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 result = await nova.criteriaLibrary.create({
text: "5+ years experience in TypeScript",
importance: "MUST_HAVE",
category: "Technical Skills",
});
- lang: bash
label: cURL
source: |-
curl -X POST "https://embed.nova.dweet.com/v1/criteria-library" \
-H "Authorization: Bearer sk_test_..." \
-H "X-Tenant-Id: acme-corp" \
-H "Content-Type: application/json" \
-d '{
"text": "5+ years experience in TypeScript",
"importance": "MUST_HAVE",
"category": "Technical Skills"
}'
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
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:
AddToLibraryRequest:
type: object
required:
- text
- importance
additionalProperties: false
properties:
text:
type: string
minLength: 1
importance:
$ref: '#/components/schemas/CriterionImportance'
category:
type: string
AddToLibraryResponse:
type: object
required:
- criterion
properties:
criterion:
$ref: '#/components/schemas/LibraryCriterion'
CriterionImportance:
type: string
enum:
- MUST_HAVE
- PREFERRED
- NICE_TO_HAVE
LibraryCriterion:
type: object
required:
- id
- text
- importance
- category
- createdAt
properties:
id:
type: string
text:
type: string
importance:
$ref: '#/components/schemas/CriterionImportance'
category:
type:
- string
- 'null'
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_*.'
````