Partner API
The partner API lets a planning vendor, a channel partner or an implementer offer Kelynto inside its own software. Each retail client of the partner has a Kelynto workspace of its own. The partner's software sends each client's files, produces and reads each client's review, downloads it as a document, and is told by webhook when something happens. Kelynto stays a standalone application: the same workspace is open to the client's own people in the Kelynto web app.
| You want to | Read |
|---|---|
| Go from a key to a published review in a few minutes | Quickstart |
| See every route, scope and error code | Partner API reference |
| Show a client's review, Outlook and This quarter inside your application | Embedding Kelynto |
| Try the requests in Postman | Postman collection |
| Know what a client's files must hold | Data contract and templates |
| Read a review field by field | The review in the API |
How it works
- A partner record. Whoever operates Kelynto makes a record for the partner: its name, its contacts, the deployment it may use (Kelynto Managed unless agreed otherwise), its branding for an embedded view, and the people at the partner who may sign in to the partner console.
- A partner key. The partner's admins make keys in the partner console. A key starts with
kpk_, is shown once, holds the scopes chosen for it, expires (90 days by default, a year at most), can be rotated with an overlap and is revoked at once. Each request with it is in the client's audit log, with the key as the actor. - Clients. The partner's software makes a workspace for each client (
POST /api/partner/v1/clients), or the operator attaches one that exists, such as a workspace a partner export made. Every call that acts for a client names it in the path:/api/partner/v1/clients/{client}/.... - One workspace per call. Kelynto looks the client up among the partner's own clients and binds the request to that one workspace. What follows is the same code a member of the workspace runs: the same validation and loader for files, the same review, the same documents. Row-level security in the database confines the request to that workspace, and a client that is not the partner's answers 404.
- Webhooks per client. The partner adds webhooks for each client: a file loaded or was held, a review was produced or published, an Outlook was issued, the Monday pack was sent. Each delivery is signed with a secret of its own, retried with backoff, logged, and can be sent again.
- Usage. Rows loaded, reviews produced, review texts the AI writer wrote and documents generated are counted per client and month, and shown to the partner and the operator.
Scopes
A key does what its scopes allow and nothing else. New keys get clients:read, clients:write, data:write, data:read, results:read and webhooks:manage. Two scopes are given only when asked for, because each changes what the client's own people see: runs:write produces a client's weekly review, and reviews:publish publishes it. A key with reviews:publish publishes to a client's readers only when that client's own admin has allowed its partner to publish (Admin, Channel); otherwise the answer is 403 client_publish_not_allowed. The full table is in the reference. A third, embed:create, is given only when asked for too: it mints the embed tokens that show a client's views to a person you name, inside your application (Embedding Kelynto).
Client licences
With a wholesale agreement, the partner holds a pool of client licences. Each client workspace the partner makes takes one, on the agreement's terms and the tier the call asks for (tier on POST /clients, one the agreement allows), and gives it back when the client leaves the partner. GET /licences (scope clients:read) shows the pool's size, how many licences are allocated and available, each client's tier and end date, and the warnings now: the pool is nearly full, full or beyond, or the agreement ends soon. PUT /clients/{client}/licence gives a client another tier the agreement allows. A webhook endpoint the partner adds can subscribe to licence.pool_low and licence.agreement_expiring. Each client's line of GET /clients carries its licence too.
The sandbox
The sandbox is two client workspaces of synthetic data, with a sandbox partner key that reaches those two workspaces and the synthetic client workspaces it makes itself. Ask Kelynto for sandbox access (marc@kelynto.com, with the subject "Sandbox access"): you receive the base address of the deployment and the key, which works for 30 days. Every name in the sandbox is marked synthetic.
The partner console
People at the partner sign in to the Kelynto web app with their work email (an emailed link or code, or a verified Microsoft or Google address). The console shows the partner's own clients side by side, each line what that client's latest review states; the pool of client licences; the partner's keys; each client's webhooks; usage; and the partner's own log. Open makes the person a member of that client's workspace, on the workspace's own sign-in terms, and switches to it; Partner console in the account menu of that workspace leads back.
The Clients tab is built for a long list. Four counts sit above it and are its filters: all clients, those that need attention, those waiting for their first data, and those up to date. A client needs attention when its workspace is switched off, its last run failed, its review's figures could not be read, data is loaded with no review, no data has arrived for ten days, or its latest review is more than a week behind. Each row says which in a few words. A search box finds a client by its name or its reference, every column sorts, and the rows are drawn as the list scrolls. The Runs tab counts each week's scheduled reviews (reviewed, failed, skipped for want of sales, still to run) and lists the clients whose run did not end in a review, with what the run said.
Conventions
- Paths are versioned:
/api/partner/v1/.... A change that would break a caller comes as/api/partner/v2/.... - Send an
Idempotency-Keyheader (8 to 80 letters, digits, dots, colons, hyphens or underscores) with every POST. The same key and the same request return the first answer's resource again, marked"repeated": true; the same key with another request is refused with 409. - A refusal answers
{"error": {"code", "message", "status"}}, with the code in theX-Error-Codeheader too. - Requests are limited per key; a 429 carries
Retry-After.