Skip to main content

​
Base URLs

ServiceURL
APIhttps://embed.nova.dweet.com/v1
Portalhttps://embed.nova.dweet.com

​
API Keys

Your API key determines the environment. Use the same URL for both:
Key FormatEnvironmentBilling
sk_test_<random>SandboxFree, not billed
sk_live_<random>ProductionBilled per score

​
Required Headers

Every API request must include: 
Authorization: Bearer <API_KEY>
X-Tenant-Id: <your_customer_id>
For requests with a JSON body (POST and PATCH), also include: 
Content-Type: application/json

​
Example Request

curl -X POST https://embed.nova.dweet.com/v1/jobs/job-123/criteria-generations \
  -H "Authorization: Bearer sk_live_abc123..." \
  -H "X-Tenant-Id: acme-corp-123" \
  -H "Content-Type: application/json" \
  -d '{
    "jobContext": {
      "jobId": "job-123",
      "jobTitle": "Senior Engineer",
      "companyName": "Acme Corp",
      "jobDescription": "..."
    }
  }'

​
Tenant Header

The X-Tenant-Id header identifies which of your customers the request is for:
Tenants are created automatically on first request. No pre-registration required.
Use a stable identifier that won’t change, such as:
  • Your internal customer/account ID
  • A UUID you generate for each customer
  • Their subdomain or unique slug

​
Key Rotation

Rotate API keys without downtime:
1

Create New Key

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

Deploy

Update your systems to use the new key.
3

Revoke Old Key

Once all systems are updated, revoke the old key.
Revoking a key returns 401 Unauthorized for new requests but does not affect scoring jobs already accepted.

​
Security Best Practices

Never commit API keys to source control. Use environment variables or a secrets manager.
Use sandbox keys for development/staging and production keys only in production.
Even without a suspected compromise, rotate keys every 90 days as a best practice.
Review your own logs and alert on unusual request patterns.

​
Compromised Key Response

If you suspect a key is compromised:
  1. Immediately revoke the compromised key in the Embed Portal
  2. Generate a new key and deploy it to your systems
  3. Review logs for unauthorized access

​
Error Responses

StatusCodeDescription
401UNAUTHORIZEDMissing or invalid API key
403FORBIDDENValid key but insufficient permissions
Example 401 Response
{
  "type": "https://embed.nova.dweet.com/errors/unauthorized",
  "code": "UNAUTHORIZED",
  "status": 401,
  "message": "Invalid or missing API key",
  "retryable": false,
  "traceId": "5c2f4f5b2c0a4ce0b6a31a1a18f8e9a1"
}
Every response includes an X-Trace-Id header. Error responses also include the same value as traceId.

​
API Versioning

The API uses URL-based versioning. The current version is v1.
PrincipleCommitment
Stability firstNo breaking changes to v1
Additive evolutionNew fields and endpoints added without version bump
Deprecation noticeIf v2 is ever needed, 12+ months notice before v1 retirement

​
What’s considered breaking?

Breaking (requires new version)Non-breaking (same version)
Removing or renaming fieldsAdding new optional fields
Changing field typesAdding new endpoints
Changing error codesAdding new optional parameters
Changing endpoint behaviorAdding new enum values
We believe in API stability. We commit to evolving v1 additively and only creating v2 for fundamental architectural changes. We have no plans for this.