Partner API quickstart
From a partner key to a published review of a client, with curl and with Python. The steps run against the sandbox: two client workspaces of synthetic data. Every request works the same way against your real clients with your real key.
1. Request a sandbox key
Ask Kelynto for sandbox access: write to marc@kelynto.com with the subject "Sandbox access", your company, your name and role, and the origin of the page you will embed from if you plan to embed. You receive the base address of the deployment and a sandbox key that starts with kpk_. The key reaches two synthetic client workspaces and the synthetic clients it makes itself, holds every scope, and works for 30 days. Keep it in an environment variable, never in code:
export KELYNTO_URL=https://app.example.com
export KELYNTO_PARTNER_KEY=kpk_...
import os
import requests # pip install requests
BASE = os.environ["KELYNTO_URL"] + "/api/partner/v1"
KELYNTO = requests.Session()
KELYNTO.headers["Authorization"] = "Bearer " + os.environ["KELYNTO_PARTNER_KEY"]
2. See who you are and list your clients
curl -s "$KELYNTO_URL/api/partner/v1" -H "Authorization: Bearer $KELYNTO_PARTNER_KEY"
curl -s "$KELYNTO_URL/api/partner/v1/clients" -H "Authorization: Bearer $KELYNTO_PARTNER_KEY"
me = KELYNTO.get(BASE).json()
print(me["partner"], me["key"]["scopes"])
clients = KELYNTO.get(f"{BASE}/clients").json()["clients"]
for c in clients:
print(c["client"], c["name"], (c["summary"] or {}).get("review_week"))
client = clients[0]["client"] # for example "harlow-and-finch-apparel-synthetic"
Each client carries its summary line: the latest reviewed week, 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.
3. Send a file
A file goes in as it would through the Kelynto inbound API: the same columns (Data contract), the same validation, the same delivery gate with control totals, the same loader. Send an Idempotency-Key so that a retry is safe. Here, the client's stores file:
curl -s -X POST "$KELYNTO_URL/api/partner/v1/clients/$CLIENT/data/stores" \
-H "Authorization: Bearer $KELYNTO_PARTNER_KEY" -H "Idempotency-Key: stores-2026-w43" \
-F "file=@stores.csv"
with open("stores.csv", "rb") as fh:
sent = KELYNTO.post(f"{BASE}/clients/{client}/data/stores", headers={"Idempotency-Key": "stores-2026-w43"},
files={"file": ("stores.csv", fh, "text/csv")})
print(sent.status_code, sent.json()["status"], sent.json()["rows_loaded"])
201 loaded, 202 held for a decision by the client's admin or analyst, 200 the same content was received before, 422 refused by validation with a report and a problem file. GET .../data/submissions/{submission_id} says what became of it later.
Send the open-to-buy plan
The plan goes in as it is written: by month (or fiscal period) and class, by store or for the whole chain, with its open-to-buy working beside the sales plan. Preview it first: nothing is written, and the answer shows each period's weekly split with the holiday weeks marked and the plan's stock identity checked (beginning stock plus receipts, less sales and markdowns, against ending stock).
curl -s -X POST "$KELYNTO_URL/api/partner/v1/clients/$CLIENT/references/preview" \
-H "Authorization: Bearer $KELYNTO_PARTNER_KEY" -H "Content-Type: application/json" \
-d "$(jq -Rs '{csv: .}' otb_plan.csv)"
plan = open("otb_plan.csv").read() # Store,Month,Class,BOM Retail,Planned Sales,Planned Markdowns,Planned Receipts,EOM Retail
seen = KELYNTO.post(f"{BASE}/clients/{client}/references/preview", json={"csv": plan}).json()
print(seen["totals"], [p["ties_out"] for p in seen["working"]])
loaded = KELYNTO.post(f"{BASE}/clients/{client}/references", headers={"Idempotency-Key": "otb-plan-0001"},
json={"kind": "plan", "label": "FY27 OTB plan", "as_of": "2026-12-01", "original": True, "csv": plan})
print(loaded.status_code, loaded.json()["provenance_text"])
The plan is phased to weeks exactly as a plan loaded in the app is, and becomes the client's original plan: a sales file with no plan column then takes each week's plan from it. A class that is not one of the client's categories answers 409 unmapped_classes; send hierarchy_map (class to category) with the request. With stock files (data/stock: stock on hand at retail and markdowns by store, week and class), the review shows the position against the open-to-buy plan.
4. Produce the review
curl -s "$KELYNTO_URL/api/partner/v1/clients/$CLIENT/reviews/latest" -H "Authorization: Bearer $KELYNTO_PARTNER_KEY"
curl -s -X POST "$KELYNTO_URL/api/partner/v1/clients/$CLIENT/runs" \
-H "Authorization: Bearer $KELYNTO_PARTNER_KEY" -H "Idempotency-Key: run-$CLIENT-w43" \
-H "Content-Type: application/json" -d '{"week_start": "2026-10-19", "force": true}'
week = KELYNTO.get(f"{BASE}/clients/{client}/reviews/latest").json()["week_start"]
run = KELYNTO.post(f"{BASE}/clients/{client}/runs", headers={"Idempotency-Key": f"run-{client}-{week}"},
json={"week_start": week, "force": True}).json()
print(run["status"]) # succeeded
review = KELYNTO.get(f"{BASE}/clients/{client}/reviews/{week}").json()
print(review["status"], review["commentary"]["body"][:300])
The answer comes when the review has finished. force runs a week that has a review already; the sandbox clients have one. The review is a draft until it is published. Its fields are described on The review in the API.
5. Publish it, and download it
curl -s -X POST "$KELYNTO_URL/api/partner/v1/clients/$CLIENT/reviews/2026-10-19/publish" \
-H "Authorization: Bearer $KELYNTO_PARTNER_KEY" -H "Idempotency-Key: publish-$CLIENT-w43"
curl -s -o review.docx "$KELYNTO_URL/api/partner/v1/clients/$CLIENT/reviews/2026-10-19/document/docx" \
-H "Authorization: Bearer $KELYNTO_PARTNER_KEY"
published = KELYNTO.post(f"{BASE}/clients/{client}/reviews/{week}/publish",
headers={"Idempotency-Key": f"publish-{client}-{week}"}).json()
print(published["status"]) # published
with open("review.pptx", "wb") as out:
out.write(KELYNTO.get(f"{BASE}/clients/{client}/reviews/{week}/document/pptx").content)
Publishing needs the scope reviews:publish, and producing a review needs runs:write; the sandbox key holds both. A key for real clients holds them only when your admin asked for them. A real client decides for itself whether its partner may publish to its readers: its own admin switches on "Allow the partner to publish" under Admin, Channel. Until then a publish answers 403 client_publish_not_allowed, and one of the client's own people publishes the review; your own people who work in the client's workspace get the same answer when they publish, send or share one. A new client has no admin of its own yet: name the person at the retailer with POST /api/partner/v1/clients/{client}/admins ({"email": "owner@northwind.example"}), and Kelynto mails them an invitation to administer the workspace. The sandbox's synthetic clients allow publishing. The Word, PDF and PowerPoint files are the same documents the Kelynto web app sends and shares. GET .../outlook reads the weeks ahead, and GET .../summary the client's summary line as it stands now.
6. Be told when something happens
hook = KELYNTO.post(f"{BASE}/clients/{client}/webhooks", headers={"Idempotency-Key": f"hook-{client}-1"},
json={"name": "Our sync", "url": "https://hooks.example.com/kelynto",
"events": ["data.accepted", "data.held", "review.produced", "review.published"]}).json()
SECRET = hook["secret"] # shown once: keep it with your receiver
Each delivery is an HTTPS POST with the headers X-Kelynto-Event, X-Kelynto-Delivery (the same on every retry) and X-Kelynto-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<body>">. Your receiver checks it like this:
import hashlib, hmac, time
def verified(secret: str, header: str, body: bytes, tolerance_s: int = 300) -> bool:
parts = dict(p.split("=", 1) for p in header.split(","))
stamp = int(parts["t"])
if abs(time.time() - stamp) > tolerance_s:
return False
expected = hmac.new(secret.encode(), f"{stamp}.".encode() + body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, parts.get("v1", ""))
A delivery that fails is tried again after 1, 5 and 30 minutes, then after 2 and 6 hours: six attempts in all, as the deployment is shipped. GET .../webhooks/{webhook_id}/deliveries is the log; POST .../deliveries/{delivery_id}/replay sends one again with the same body and id; POST .../webhooks/{webhook_id}/test sends a signed test now.
Next
- Make a client of your own:
POST /api/partner/v1/clientswith its name, currency, time zone and the first day of its fiscal week. A sandbox key makes a synthetic client. - Read usage per client and month:
GET /api/partner/v1/usage. - Every route, scope and error code: Partner API reference. The same requests, ready to send: Postman collection.