API reference
Kova's API lets you push customer activity in from your own systems and read back each account's health. It's a small REST API that takes and returns JSON. Everything here works against your sandbox, so you can try each request as you read.
Getting started
Create a sandbox to get a key. Each sandbox holds one customer, Brightline Logistics, with 30 days of history, and lasts 7 days. Keep the Kova page open while you send requests and you'll see each one arrive.
Authentication
Send your sandbox key as a bearer token on every request.
Sandbox keys start with kova_test_. A production API would add live keys, key rotation and scoped permissions; the sandbox keeps it to one key per account.
GET/api/v1/account
Returns the account, its current health score broken down by component, the suggested next step, recent events, alerts and the integration log.
POST/api/v1/events
Records something that happened at the customer. Kova replays the account's full history, rescores it, and returns the new score. If the account drops into a worse band, Kova writes an alert and sends it.
Event types
| type | data | What it changes |
|---|---|---|
usage.weekly | active_users, logins | Usage score |
feature.used | feature: dashboards, alerts, reports, integrations, playbooks, api, segments or surveys | Feature adoption |
ticket.opened | severity: low, medium or high; subject | Support |
ticket.resolved | ticket_id (optional, oldest if left out) | Support |
contact.added | role: champion or sponsor; name | Relationship |
contact.left | role: champion or sponsor | Relationship |
nps.submitted | score: 0 to 10 | Relationship |
seats.changed | seats | Commercial and usage |
invoice.overdue | none | Commercial |
invoice.paid | none | Commercial |
GET/api/v1/events
Returns the last 100 events, newest first, each with a plain-English description.
POST/api/v1/qbr
Drafts a quarterly business review outline from the account's data. If an AI model is connected it writes the draft; otherwise Kova uses its own template. The response says which.
POST/api/v1/reset
Puts the sandbox back to its starting point: the original 30 days of history, no alerts and an empty integration log. The key and alert email stay the same.
Errors and limits
Errors come back with an HTTP status and a JSON body you can show to a user or act on in code.
| Status | code | When |
|---|---|---|
| 400 | invalid_json | The body isn't valid JSON |
| 401 | missing_api_key, invalid_api_key | No key, or a key Kova doesn't recognise |
| 410 | sandbox_expired | The sandbox is more than 7 days old |
| 413 | payload_too_large | data is over 2KB |
| 422 | unknown_event_type | The event type isn't on the list above |
| 429 | rate_limited | More than 30 events, 120 reads, 4 QBR drafts or 6 resets a minute |
How scoring works
Kova doesn't store a score. It stores events, and rebuilds the account's state by replaying them in order every time something changes. That means every score can be traced back to what caused it, and changing the model rescores history too.
| Component | Weight | Based on |
|---|---|---|
| Usage | 35 | Share of seats active this week, and logins per active user |
| Feature adoption | 20 | How many of the eight features are in use (six or more scores full marks) |
| Support | 15 | Open tickets, weighted by severity |
| Relationship | 20 | Champion in place, exec sponsor engaged, latest NPS |
| Commercial | 10 | Seats kept against the contract, invoices paid on time |
70 and above is healthy, 50 to 69 is at risk, below 50 is critical. An alert fires only when an account moves into a worse band, at most once a minute per sandbox. Each sandbox emails at most 3 alerts in its lifetime, and a reset doesn't clear that count.