NOVA API documentation

Overview

The NOVA API is a JSON-over-HTTPS REST API. Authenticated endpoints expect a JWT in the Authorization header:

Authorization: Bearer <your-jwt>

You get a JWT from POST /auth/register or POST /auth/login. New accounts start a 7-day trial with 10 call minutes included — no card required.

Browser requests are CORS-restricted to novalabs.ae origins; server-to-server requests are unrestricted. All request and response bodies are application/json unless noted otherwise.

Quickstart

Three requests from zero to a live agent conversation. You can do the same flow without code from the wizard at novalabs.ae — “Deploy Your First Agent”.

1. Create an account, get a token

curl -X POST https://api.novalabs.ae/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@example.com",
    "password": "a-strong-password"
  }'

The response includes your JWT and trial status:

{
  "access_token": "eyJhbGciOi...",
  "token_type": "bearer",
  "user": {
    "id": "8f3b2a4c-...",
    "email": "you@example.com",
    "trial_active": true,
    "trial_minutes_remaining": 10.0,
    "created_at": "2026-06-12T08:30:00Z"
  }
}

2. Dispatch your first agent call

curl -X POST https://api.novalabs.ae/calls \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $NOVA_TOKEN" \
  -d '{
    "owner_email": "you@example.com",
    "product": "CloudSync CRM",
    "website_url": "https://your-site.example",
    "context": "Mid-market CRM, AED 99/seat, main objection is migration effort",
    "goal": "qualify_interest",
    "consent": true,
    "leads": [
      { "phone": "+971501234567", "name": "Sarah", "company": "Acme Corp" }
    ]
  }'

NOVA builds a personalised call context per lead (scraping website_url if provided) and dispatches one agent per lead. The response gives you a call_id per lead:

{
  "calls": [
    {
      "call_id": "c1a2...",
      "context_id": "d4e5...",
      "phone": "+971501234567",
      "lead_name": "Sarah",
      "status": "in_progress",
      "expires_in_seconds": 600.0,
      "message": "Call dispatched successfully"
    }
  ],
  "total": 1,
  "dispatched": 1,
  "failed": 0
}

3. Poll call status

curl https://api.novalabs.ae/calls/$CALL_ID

Call jobs are ephemeral — they expire 10 minutes after creation, after which the status endpoint returns 404. Use webhooks for durable lifecycle events.

Authentication

Native JWT auth — register, log in, and pass the returned access_token as a Bearer header. Passwords must be at least 6 characters; emails are normalised to lowercase.

Calls

Browser demo token

curl -X POST https://api.novalabs.ae/token \
  -H "Content-Type: application/json" \
  -d '{ "room_name": "<room from your dispatch>", "participant_name": "Test Caller" }'

Billing & usage

Plans are usage-based on call minutes. Trial accounts get 10 minutes over 7 days. Card payments run through Stripe; UAE customers can pay in AED via Ziina.

Referrals

Every account gets a referral code. Pass it as referral_code on /auth/register and you earn a commission when the referred account converts to a paid plan. All endpoints require a Bearer token.

Call quality scores

Outbound webhooks — call lifecycle

Register an HTTPS URL and NOVA POSTs a signed JSON payload on each subscribed event. All management endpoints require a Bearer token.

Events

• call.started — outbound call dispatched
• call.ended — call hung up (any reason)
• call.transcribed — full transcript persisted
• call.scored — LLM-as-judge quality score persisted

Register a webhook

{
  "url": "https://hooks.example.com/nova",
  "events": ["call.started", "call.ended", "call.transcribed", "call.scored"]
}

{
  "id": "8f3b2a4c-1234-...",
  "url": "https://hooks.example.com/nova",
  "events": ["call.started", "call.ended", "call.transcribed", "call.scored"],
  "secret": "raw-token-shown-once-save-it-now",
  "is_active": true,
  "created_at": "2026-06-12T08:30:00Z"
}

Delivery payload

POST <your-url>
Content-Type: application/json
X-Nova-Event: call.ended
X-Nova-Signature: sha256=<hex_hmac>
User-Agent: NOVA-Webhooks/1.0

{
  "event": "call.ended",
  "delivered_at": "2026-06-12T08:30:00Z",
  "data": {
    "call_id": "uuid",
    "customer_id": "uuid",
    "started_at": "2026-06-12T08:27:00Z",
    "ended_at": "2026-06-12T08:30:00Z",
    "duration_seconds": 187,
    "outcome": "qualified",
    "goal": "qualify_interest",
    "goal_completed": true,
    "to_phone_e164": "+15555550100"
  }
}

Verifying the signature

X-Nova-Signature is an HMAC-SHA256 over the raw request body. The HMAC key is the SHA-256 hex digest of your raw secret — hash your stored token first, then HMAC. Compare with a constant-time function.

Python

import hashlib
import hmac

def verify(raw_secret: str, body: bytes, header: str) -> bool:
    key = hashlib.sha256(raw_secret.encode()).hexdigest()
    expected = "sha256=" + hmac.new(
        key.encode(), body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, header)

Node

const crypto = require("crypto");

function verify(rawSecret, body, header) {
  const key = crypto.createHash("sha256")
    .update(rawSecret).digest("hex");
  const expected = "sha256=" + crypto
    .createHmac("sha256", key)
    .update(body).digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(expected), Buffer.from(header)
  );
}

Retries

Non-2xx responses and network errors are retried with backoff — waits of 1s, 5s, 30s between attempts, 4 attempts total, 10-second timeout per attempt. After the final failure the delivery is marked failed and not retried.

Management endpoints

Constraints

• HTTPS only — http:// URLs are rejected
• Private / internal addresses are rejected (localhost, RFC1918, link-local)
• Unknown event types are rejected with 400

Inbound portal webhooks — Property Finder & Bayut

NOVA can receive lead webhooks directly from UAE property portals and dispatch a qualification call within seconds of the inquiry. The receiver acknowledges in milliseconds and dispatches the call in the background.

Verification & replay protection

• Signatures are verified with a constant-time comparison; anything that doesn’t match — or doesn’t start with sha256= — is rejected with 401.
• Replay protection: deliveries are deduplicated on the portal event ID. A replayed event ID gets an idempotent 200 acknowledgement without re-dispatching a call.
• Malformed payloads return 400; a valid signed payload returns 200 with { accepted, lead_id | event_id, elapsed_ms }.

Response codes

Gated features — available on request

Two surfaces ship behind per-account feature flags and return 404 until enabled for your user. Check GET /me/features for your account’s flags, and contact ceo@novalabs.ae to request access.

Custom voice cloning — /voice/*

Clone your own voice for outbound agent calls. The flow is consent-first: a signed consent record is required before any audio is accepted, enrolment is limited to one attempt per 24 hours, and audio uploads are capped at 16 MB. Enrolment is not available from the EU/EEA/UK (451) pending data-protection compliance. Revoking a profile deletes the cloned voice at the provider.

Bring-your-own Twilio — /twilio/*

Place calls from your own Twilio numbers. Credentials are stored encrypted (only the last 4 of the Account SID is ever returned), and number ownership must be proven via SMS OTP before a number can go active. OTP sends are rate-limited (3 per 10 minutes, 10 per 24 hours per number).

MCP — drive NOVA from AI agents

NOVA ships a Model Context Protocol server so AI assistants (Claude, Cursor, and any MCP-capable agent) can drive the platform directly — register accounts, dispatch qualification calls, check call status, and read results as tools instead of raw HTTP.

Setup, the tool catalogue, and configuration examples live in the repo: github.com/Kazemkhani/nova-mcp. The MCP server is a thin layer over the same public API documented on this page — everything it can do, you can do with plain HTTPS.

Errors

Errors follow the FastAPI convention — a JSON body with a detail field:

{ "detail": "Rate limit exceeded. Max 5 requests per 60 seconds." }

Operational endpoints