Partner API reference

Kelynto developer documentation. Sandbox access: marc@kelynto.com.

Every route of the partner API, version 1 of Kelynto 2.28.0: 34 routes. Start with the quickstart. Send Authorization: Bearer <partner key> with every request. A route marked yes under One client names the client in its path, acts in that client's workspace only, and answers 404 client_not_found for any reference that is not one of your clients.

Scopes

ScopeWhat it allowsGiven by default
clients:readList the partner's clients, read each one's summary line and its usage.yes
clients:writeMake a client workspace for the partner.yes
data:writeSend a client's files: the same validation, delivery gate and loader as every upload.yes
data:readRead the status, report and problems of what was sent for a client, and the client's data health.yes
results:readRead a client's review, findings and Outlook, and download the review as a Word, PDF or PowerPoint file.yes
runs:writeProduce a client's weekly review.when asked for
reviews:publishPublish a client's review, which puts it in front of the client's readers.when asked for
webhooks:manageAdd, change, test and remove the client's webhooks this partner made, and read their delivery logs.yes
embed:createMint an embed token that shows one person the client's review, Outlook, findings and This quarter inside the partner's application, and end those embedded sessions.when asked for

Routes

RouteWhat it doesScopeOne clientLicence feature of the client
GET /api/partner/v1Who the key is: the partner, whether it is a sandbox, the key's scopes, and where everything is.any valid key
GET /api/partner/v1/clientsThe partner's clients, each with its summary line: the figures that client's own latest review states, when it has one.clients:read
POST /api/partner/v1/clientsMake a client workspace: its own workspace, its currency and fiscal calendar, the partner's tag. The answer is the client with its reference. A sandbox key makes a workspace of synthetic data. Example:clients:write
GET /api/partner/v1/clients/{client}One client: its names, its workspace, its licence and its summary line, and whether the client has an admin of its own yet (client_admins, and admin_invited: the addresses invited to become one that have not accepted).clients:readyes
POST /api/partner/v1/clients/{client}/adminsInvite the client's first admin: the person at the retailer who decides for its workspace (whether its partner may publish to its readers, whether the partner's people sign in, a move to another channel).clients:writeyesworkspace
GET /api/partner/v1/clients/{client}/data/healthThe client's data health: what arrived, what is late or missing, and what to do.data:readyesoutbound_api
GET /api/partner/v1/clients/{client}/data/submissions/{submission_id}What became of a file sent: its status, counts, problems and what the delivery gate checked.data:readyesinbound_api
POST /api/partner/v1/clients/{client}/data/{kind}Send one file of a dataset for the client: the same as POST /api/v1/inbound/submissions/{kind} in the client's workspace, with its validation, delivery gate, control totals and loader. 201 loaded, 202 held for a decision, 200 the same content was received before, 422 refused, 409 a reused Idempotency-Key. Example:data:writeyesinbound_api
DELETE /api/partner/v1/clients/{client}/embed/sessionsEnd the client's embedded sessions now: one person's (when they sign out of your application) or all of them.embed:createyesworkspace
POST /api/partner/v1/clients/{client}/embed/tokensAn embed token: one person of yours reads the client's review, Outlook, findings and This quarter inside your page. Signed, single use, minutes long, bound to one of your embed origins. Mint one per page load, on your server, and put url in an iframe on that origin. Recorded in the client's audit log. Example:embed:createyesexplain
PUT /api/partner/v1/clients/{client}/licenceGive the client another tier, one the wholesale agreement allows. Recorded in the client's audit log, the partner's log and the licence log.clients:writeyes
GET /api/partner/v1/clients/{client}/outlookThe client's Outlook: the weeks ahead by cause against the client's plan or forecast, each item with its range and basis, the records on file with no amount, and the planners' decisions.results:readyesexplain
GET /api/partner/v1/clients/{client}/period-reviewThe client's period review: sales by category against the plan's own figure for the period and last year, units and average unit retail, the weekly reviews' sized causes added up, events on file and what is still open.results:readyesexplain
GET /api/partner/v1/clients/{client}/period-review/document/{fmt}The client's period review as a file: pptx, docx or pdf.results:readyesact_documents
GET /api/partner/v1/clients/{client}/period-review/periodsThe client's periods (months or fiscal periods of its calendar) that hold sales on file, newest first, each closed or to date. The fields are those of GET /api/v1/period-review/periods.results:readyesexplain
POST /api/partner/v1/clients/{client}/referencesLoad a plan or forecast for the client: the same as POST /api/v1/outlook/references in the client's workspace. Kept as loaded, the original plan and every later forecast apart; a plan by period keeps its open-to-buy working, which the position against the plan reads.data:writeyesexplain
POST /api/partner/v1/clients/{client}/references/previewWhat a plan file would load as for the client, and nothing written: the same answer as POST /api/v1/outlook/references/preview in the client's workspace.data:writeyesexplain
GET /api/partner/v1/clients/{client}/reviews/latestThe client's latest review, published or not: the three-part statement, the commentary as it stands and its status (draft or published). The fields are those of GET /api/v1/outbound/reviews/{week_start}.results:readyesoutbound_api
GET /api/partner/v1/clients/{client}/reviews/{week_start}One week's review of the client, published or not.results:readyesoutbound_api
GET /api/partner/v1/clients/{client}/reviews/{week_start}/document/{fmt}The client's review of a week as a file: docx (Word), pdf or pptx (PowerPoint), rendered on the server from the same document the app sends and shares.results:readyesact_documents
GET /api/partner/v1/clients/{client}/reviews/{week_start}/findingsThe findings of a week's review, each with its evidence, as the outbound API states them.results:readyesoutbound_api
POST /api/partner/v1/clients/{client}/reviews/{week_start}/publishPublish the client's review of a week: the client's readers see it, and review.published is sent. Publishing a review that is published already changes nothing. Recorded in the client's audit log with the partner key as the actor.reviews:publishyesexplain
POST /api/partner/v1/clients/{client}/runsProduce the client's review of a week, from the data on file, and answer when it has finished (201). The review is a draft until it is published. review.produced is sent to the client's webhooks.runs:writeyesexplain
GET /api/partner/v1/clients/{client}/summaryThe client's summary line, worked out now from its latest review: sales against plan, what recorded causes explain, what is not explained, the findings, Outlook decisions due, when data last loaded and how the latest run ended.results:readyesoutbound_api
GET /api/partner/v1/clients/{client}/webhooksThe client's webhooks this partner added, the events there are, and how deliveries are retried.webhooks:manageyesworkspace
POST /api/partner/v1/clients/{client}/webhooksAdd a webhook for the client. The answer carries the signing secret, once: store it. With an Idempotency-Key, a repeat answers the same webhook without its secret.webhooks:manageyeswebhooks
DELETE /api/partner/v1/clients/{client}/webhooks/{webhook_id}Remove webhookwebhooks:manageyeswebhooks
PATCH /api/partner/v1/clients/{client}/webhooks/{webhook_id}Change webhookwebhooks:manageyeswebhooks
GET /api/partner/v1/clients/{client}/webhooks/{webhook_id}/deliveriesThe delivery log: every event queued, its attempts, the last status code and when the next attempt is due.webhooks:manageyeswebhooks
POST /api/partner/v1/clients/{client}/webhooks/{webhook_id}/deliveries/{delivery_id}/replayQueue a delivery that failed or was given up on to be sent again, with the same body and the same delivery id.webhooks:manageyeswebhooks
POST /api/partner/v1/clients/{client}/webhooks/{webhook_id}/secretA new signing secret, shown once. The old one stops signing at once.webhooks:manageyeswebhooks
POST /api/partner/v1/clients/{client}/webhooks/{webhook_id}/testSend one signed test delivery now and say how it went. It appears in the delivery log.webhooks:manageyeswebhooks
GET /api/partner/v1/licencesThe partner's wholesale agreement and its pool: size, allocated, available, beyond the pool; the tiers a client may be given; each client's tier, state and end date; the warnings now (pool nearly full, agreement ending) and the notices sent. Counts and terms only: what the partner pays is in its signed contract.clients:read
GET /api/partner/v1/usageUsage per client and calendar month: rows loaded, reviews produced, review texts the AI writer wrote, documents generated. Counts only.clients:read

Error codes

A refusal answers with the HTTP status and {"error": {"code", "message", "status"}}; the code is in the X-Error-Code header as well. The message is written for a person to read; a program decides on the code.

StatusCodeWhen
401invalid_keyNo partner key, a key that is wrong, revoked or expired, or another kind of credential.
403scope_missingThe key does not hold the scope the route needs.
403partner_inactiveThe partner is suspended or closed, or not set up for this kind of deployment.
403ip_not_allowedThe client's workspace accepts requests from its allowed network addresses only.
403licence_featureThe client's licence does not include what the route does.
403licence_read_onlyThe client's licence is expired, suspended or revoked: reading works, writing does not.
404client_not_foundNo client of this partner has that reference. The same answer whether the workspace exists or not.
404not_foundNo such week, submission, webhook or delivery in that client's workspace.
404no_reviewThe client has no review of that week yet.
409idempotency_key_reusedThe Idempotency-Key was used for another request.
409key_reusedOn a file sent: the Idempotency-Key was used for another file or dataset.
409client_existsThe partner has a client with that reference, or a workspace for that name exists.
409data_changedThe client's data changed after the review was produced: produce it again before publishing.
409run_in_progressA review of that week is being produced.
409week_not_endedThe week has not ended yet.
422invalid_requestThe body or a parameter is not valid; the message names the field.
422rejectedThe file was refused by validation; its report and problem file say why.
429rate_limitedToo many requests from this key; wait for the Retry-After seconds.