Plan, expiry and what is left
The organization's subscription and the state of both metered resources. Everything an integration needs to decide what to show: `plan.status` and `plan.expires_at` for the subscription, `features` for what the plan covers, `quota` for search requests in the current period, and `credits` for AI operations (assistants, voice, image and semantic search). Cheap to call and safe to cache for a few minutes — it is not a per-request authorization check, the API enforces the same limits itself.
Full-key operation
The organization's subscription and the state of both metered resources. Everything an integration needs to decide what to show: plan.status and plan.expires_at for the subscription, features for what the plan covers, quota for search requests in the current period, and credits for AI operations (assistants, voice, image and semantic search). Cheap to call and safe to cache for a few minutes — it is not a per-request authorization check, the API enforces the same limits itself.
Authorization
api_key_header Every request carries an organization API key. A key has one of two scopes. A full key reaches every operation in this document and belongs on your server. A search key is the one to ship in a browser widget or a storefront page: it reaches only the operations marked x-nova-key-scope: search — searching, federated search, recommendations, event ingestion, and the visitor-facing AI operations (semantic and image search, voice transcription and voice search, assistant chat, and the visitor's own conversation). It cannot write documents or read or change configuration; any other operation answers 403. AI operations are paid in credits from the organization's wallet whichever key calls them (402 when the balance runs out), and a search key needs X-NOVA-SESSION-ID on them: the session is what a conversation belongs to, and what the per-session allowance (429) is counted against. A key of either scope may additionally carry restrictions set in the console: an allowlist of collections (403 elsewhere), a forced filter_by per collection that is ANDed into every search (document-level access control), an allowlist of fields (include_fields is limited to it and a request naming any other field in query_by, facet_by, sort_by, filter_by or highlight_fields answers 400), an IP/CIDR allowlist and an Origin/Referer allowlist (403), and a per-key rate limit (429 with Retry-After).
In: header
Response Body
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/entitlement"{ "plan": { "id": "string", "name": "string", "status": "none", "expires_at": 0, "trial_ends_at": 0, "cancel_at_period_end": true, "days_left": 0 }, "features": [ "search", "synonyms", "curation", "recommendations", "assistants", "voice", "image_search" ], "quota": { "used": 0, "limit": 0, "remaining": 0, "exhausted": true, "resets_at": 0 }, "credits": { "balance": 0, "reserved": 0, "available": 0, "exhausted": true }, "suspended": true, "suspension_reason": "payment"}Ingest behavioural events POST
Records a batch of behavioural events for the calling organization. Events are validated synchronously and stored asynchronously; the response reports how many were accepted and which entries were rejected. Use `query_id` to tie clicks and purchases back to the search or recommendation response they came from.
List recommendation models GET
Lists the recommendation models configured on a collection.