Authentication

API keys

Your API key determines the environment. Use the same base URL for both:

Key Format	Environment
`sk_test_<random>`	Sandbox
`sk_live_<random>`	Production

Both environments are billed per score at the same rate.

Required headers

Authorization: Bearer <API_KEY>
X-Tenant-Id: <tenantExternalId>
Content-Type: application/json  # for POST and PATCH

X-Tenant-Id is required for tenant-scoped requests. Tenant deletion, deletion status, rate-limit status, and analytics endpoints are scoped by your API key and environment instead.

Example request

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

const nova = new Nova({
  apiKey: process.env.NOVA_API_KEY!,
  tenantId: 'acme-corp',
});

const result = await nova.jobs.criteria.generate.create({
  jobId: 'job-123',
  body: {
    jobContext: {
      jobTitle: 'Senior Engineer',
      companyName: 'Acme Corp',
      jobDescription: 'We are looking for a Senior Engineer with 5+ years experience...',
    },
  },
});

curl -X POST https://embed.nova.dweet.com/v1/jobs/job-123/criteria/generate \
  -H "Authorization: Bearer sk_live_abc123..." \
  -H "X-Tenant-Id: acme-corp" \
  -H "Content-Type: application/json" \
  -d '{
    "jobContext": {
      "jobTitle": "Senior Engineer",
      "companyName": "Acme Corp",
      "jobDescription": "We are looking for a Senior Engineer with 5+ years experience..."
    }
  }'

Tenant header

The X-Tenant-Id header identifies which tenant the request is for. Tenants are created automatically on first tenant-scoped request. Use a stable identifier: your internal customer/account ID, a UUID, or a unique slug.

Key rotation

Create new key

Generate a new key in the Embed Portal. Your old key stays active.

Deploy

Update your systems to use the new key.

Revoke old key

Once all systems are updated, revoke the old key.

Revoking a key returns 401 Unauthorized for new requests but doesn’t affect scoring jobs already accepted.

Error responses

Status	Code	Description
401	`UNAUTHORIZED`	Missing or invalid API key
403	`FORBIDDEN`	Valid key but insufficient permissions

Example 401 Response

{
  "type": "https://docs.nova.dweet.com/embed-api/errors#unauthorized",
  "code": "UNAUTHORIZED",
  "status": 401,
  "message": "Invalid or missing API key",
  "retryable": false,
  "traceId": "5c2f4f5b2c0a4ce0b6a31a1a18f8e9a1"
}

API versioning

Current version: v1. URL-based versioning.

Breaking (requires new version)	Non-breaking (same version)
Removing or renaming fields	Adding new optional fields
Changing field types	Adding new endpoints
Changing error codes	Adding new optional parameters
Changing endpoint behavior	Adding new enum values

No breaking changes to v1. If v2 is ever needed, 12+ months notice before v1 retirement.

Getting started

Core concepts

API endpoints

Integration guides

SDKs

Legal

API keys

Required headers

Example request

Tenant header

Key rotation

Error responses

API versioning

​API keys

​Required headers

​Example request

​Tenant header

​Key rotation

​Error responses

​API versioning

API keys

Required headers

Example request

Tenant header

Key rotation

Error responses

API versioning