For the current npm version and availability, see Download.
Typed client for the Keryn Cloud API. Types and the operation table are generated from
apps/keryn-cloud/openapi/keryn-cloud.openapi.json; the client is about 80 lines with no dependencies. Node 20 or newer, or any runtime with fetch.
Quickstart
Section titled “Quickstart”This runs with Node.js 20 or newer and nothing else: no account and no key. The first call needs no credential. The second shows the error the client throws when the API refuses a call, here because no key is set.
npm install @keryn/sdkquickstart.mjs:
import { createClient, KerynApiError } from "@keryn/sdk";
const keryn = createClient({ apiKey: process.env.KERYN_API_KEY });
const health = await keryn.getHealth(); // needs no credentialconsole.log(health.status);
try { await keryn.getMe(); // needs a credential console.log("credential accepted");} catch (e) { if (!(e instanceof KerynApiError)) throw e; console.log(e.status, e.code);}node quickstart.mjsok401 authentication_requiredWith KERYN_API_KEY set to an organization API key, calls that need a credential run as that key. The examples below need one.
Calls and errors
Section titled “Calls and errors”import { createClient, KerynApiError } from "@keryn/sdk";
const keryn = createClient({ apiKey: process.env.KERYN_API_KEY });
const scan = await keryn.createScan({ idempotencyKey: crypto.randomUUID(), body: { type: "trust-scan", url: "https://example.com", maxPages: 10 },});const done = await keryn.getScan({ id: scan.id }); // poll until status is completed, failed or canceledconsole.log(done.status, done.result);Every method takes one object: path parameters by name, query, body, and headers in camelCase (idempotencyKey).
Failures throw KerynApiError with status, code (for example insufficient_credits) and retryAfterSeconds on 429.
Credentials: apiKey (Bearer) or workerToken (x-keryn-worker-token), not both. Create keys under Account, Developers.
Administrative calls (keys, workers, billing, security policy, sharing mode) need a signed-in owner or admin and are not available to keys.
Every request and response type of the API is exported, generated from the OpenAPI document (Scan, ScanRequest, Credits, Limits, UsageEvent, …). So are types for Keryn’s published JSON Schemas, generated from the files keryn.dev serves under /schemas/:
import { readFile } from "node:fs/promises";import type { KerynResult, KerynDecisions, KerynLedger } from "@keryn/sdk";
const result: KerynResult = JSON.parse(await readFile("result.json", "utf8")); // keryn scan . --json result.jsonfor (const f of result.findings) console.log(f.severity, f.ruleId, f.path);KerynResult, KerynDecisions, KerynScope, KerynApplication, KerynLedger, KerynConfig, KerynPolicy. The schemas are open on engine detail; unknown fields are typed unknown.
Local CLI native results additionally carry assessment (keryn.dev/assessment/v1) for canonical cases, verdict reasons and accounting. This is a local report projection; cloud SDK request/response contracts remain unchanged. Preserve it when retaining local evidence, and do not reinterpret raw findings counts as case totals.
AI attribution v1
Section titled “AI attribution v1”Use analyseAttribution to submit commit metadata. The report distinguishes
declared assistance from configured tools and low-confidence signals. Treat the
declared share as a lower bound. Developer identities are omitted by default.
Alias and identity views require a signed-in organization administrator and a fresh step-up proof.
For these views and for setAttributionPolicy, supply a session-authenticated
fetch and pass the proof as xKerynStepUp in the operation arguments. The proof
must be issued for the exact method, path, and serialized request body.
import { createClient } from "@keryn/sdk";
const client = createClient({ apiKey: process.env.KERYN_API_KEY! });const { report } = await client.analyseAttribution({ body: { commits: [{ sha: "0000000000000000000000000000000000000001", authoredAt: "2026-11-01T10:00:00Z", authorName: "Example", authorEmail: "developer@example.invalid", message: "feat: example\n\nCo-authored-by: Claude <noreply@anthropic.com>", }], },});console.log(report.schema, report.repo.declared);The OpenAPI reference defines
POST /api/v1/ai-attribution, which requires scans:create.
The hosted MCP tool keryn_cloud_ai_attribution accepts the same body and returns
the same aggregate result. Hosted MCP has a 64 KiB message limit. The REST
endpoint accepts up to 2 MiB and 2,000 commits. Metering stays in shadow mode.
The HTTP operation, keryn.ai-attribution/1 report and
attribution_result webhook are stable v1 contracts. Within v1, clients should
ignore unknown optional fields. Removing or renaming fields or changing their
meaning requires a new major contract. Keryn announces deprecations in the
changelog and documents the replacement and sunset date before retiring a
major version.
Administrators with an operator-approved webhook destination can opt into
attribution_result through notification preferences. The event contains the
report’s surfaceHash and a stable idempotencyKey. It excludes the report,
repository paths, commit messages and identities. An identical surface is
queued once per subscribed destination. The Cloud worker drains the queue. Consumers should deduplicate by the
idempotency key and use commit dates within their organization’s lookback window.
Limits
Section titled “Limits”- It is a client for the Keryn Cloud API only. It contains no scanner and no rules, and it cannot scan code. Local results are only typed (
KerynResultand the other schema types). @keryn/sdk0.1.0, the version on npm, has 92 of the 136 methods in the table below. The 44 marked not in 0.1.0 are on main and not published yet.- One call is one HTTP request. The client does not retry, does not wait on a 429 and sets no timeout. A 429 throws
KerynApiErrorwithretryAfterSeconds; pass your ownfetchto add retries or a timeout. - There are no pagination or polling helpers. To wait for a scan, call
getScanuntil its status is final. - An answer that is not JSON resolves to
undefined. apiKeyandworkerTokentogether are refused when the client is created.- An API key cannot make the administrative calls (keys, workers, billing, security policy, sharing mode). Those need a signed-in owner or admin.
- It is an ES module for Node.js 20 or newer, or any runtime with
fetch. - The rate limits are those of the organization’s plan. They are on the Cloud API page.
Methods
Section titled “Methods”One method per operation of the Cloud API, generated from its OpenAPI document. Each takes one argument object: path parameters by name, query, body, and headers in camel case (idempotencyKey). @keryn/sdk 0.1.0, the version on npm, has 92 of these 136. The methods marked not in 0.1.0 are on main and not published yet. What each one does and needs is on the Cloud API page.
| Method | HTTP |
|---|---|
getHealth |
GET /health |
getEngineHealth |
GET /api/health |
getPublicConfig |
GET /api/public/config |
lookupSsoDomain |
POST /api/public/sso-domain |
openShare |
GET /s/{token} |
startPairing |
POST /api/pair/start |
redeemPairing |
POST /api/pair/token |
inspectPairing |
GET /api/v1/pair |
approvePairing |
POST /api/v1/pair/approve |
getMe |
GET /api/v1/me |
listTeams |
GET /api/v1/teams |
getDirectory |
GET /api/v1/directory |
createDirectoryToken |
POST /api/v1/directory/tokens |
revokeDirectoryToken |
DELETE /api/v1/directory/tokens/{id} |
listProjects |
GET /api/v1/projects |
createProject |
POST /api/v1/projects |
listApiKeys |
GET /api/v1/keys |
createApiKey |
POST /api/v1/keys |
revokeApiKey |
DELETE /api/v1/keys/{id} |
listWorkers |
GET /api/v1/workers |
createWorker |
POST /api/v1/workers |
getEarlierAccount |
GET /api/v1/account/earlier |
bringEarlierAccount |
POST /api/v1/account/earlier |
rotateWorkerToken |
POST /api/v1/workers/rotate |
signOutWorker (not in 0.1.0) |
POST /api/v1/workers/revoke |
revokeWorker |
DELETE /api/v1/workers/{id} |
getCredits |
GET /api/v1/credits |
claimStarterCredit |
POST /api/v1/credits/starter |
redeemPromoCode |
POST /api/v1/credits/redeem |
callMcp |
POST /mcp |
getAttributionPolicy (not in 0.1.0) |
GET /api/v1/ai-attribution/policy |
setAttributionPolicy (not in 0.1.0) |
PUT /api/v1/ai-attribution/policy |
analyseAttribution |
POST /api/v1/ai-attribution |
listDomains |
GET /api/v1/domains |
addDomain |
POST /api/v1/domains |
removeDomain |
DELETE /api/v1/domains |
verifyDomain |
POST /api/v1/domains/verify |
createCloudScan |
POST /api/v1/cloud-scans |
listCloudScans |
GET /api/v1/cloud-scans |
getCloudScan |
GET /api/v1/cloud-scans/{id} |
deleteCloudScan |
DELETE /api/v1/cloud-scans/{id} |
getCloudUsage |
GET /api/v1/cloud-scans/usage |
createScan |
POST /api/v1/scans |
listScanSchedules (not in 0.1.0) |
GET /api/v1/scan-schedules |
createScanSchedule (not in 0.1.0) |
POST /api/v1/scan-schedules |
deleteScanSchedule (not in 0.1.0) |
DELETE /api/v1/scan-schedules/{id} |
getScan |
GET /api/v1/scans/{id} |
cancelScan |
POST /api/v1/scans/{id}/cancel |
getCliUsage (not in 0.1.0) |
GET /api/v1/usage/cli |
reportCliUsage |
POST /api/v1/usage/cli |
getRepoScanQuote (not in 0.1.0) |
GET /api/v1/repo-scans/quote |
getUsageStatement (not in 0.1.0) |
GET /api/v1/usage/statement |
listUsage |
GET /api/v1/usage |
listDownloads (not in 0.1.0) |
GET /api/v1/downloads |
downloadCli (not in 0.1.0) |
GET /api/v1/downloads/{tag}/{file} |
issueEntitlement |
POST /api/v1/entitlement |
admitOemEntitlement (not in 0.1.0) |
POST /api/v1/oem/admission |
getEntitlementKeys (not in 0.1.0) |
GET /api/public/entitlement/keys |
listEntitlements (not in 0.1.0) |
GET /api/v1/entitlements |
revokeEntitlement (not in 0.1.0) |
POST /api/v1/entitlements/{id}/revoke |
releaseEntitlementMachine (not in 0.1.0) |
POST /api/v1/entitlements/devices/{id}/release |
getContract (not in 0.1.0) |
GET /api/v1/contract |
listLicences (not in 0.1.0) |
GET /api/v1/licences |
requestLicence (not in 0.1.0) |
POST /api/v1/licences/requests |
withdrawLicenceRequest (not in 0.1.0) |
POST /api/v1/licences/{id}/withdraw |
reportOwnKeyUsage (not in 0.1.0) |
POST /api/v1/usage/agentic-own-key |
getLimits |
GET /api/v1/limits |
createCheckout |
POST /api/v1/billing/checkout |
getBillingSettings (not in 0.1.0) |
GET /api/v1/billing/settings |
setBillingSettings (not in 0.1.0) |
PATCH /api/v1/billing/settings |
createBillingPortal |
POST /api/v1/billing/portal |
getBillingPlans |
GET /api/v1/billing/plans |
createTeamSubscription |
POST /api/v1/billing/subscribe |
sendTelemetry |
POST /api/public/telemetry |
sendDiagnostic |
POST /api/public/diagnostics |
getSharing |
GET /api/v1/sharing |
setSharing |
POST /api/v1/sharing |
listResults |
GET /api/v1/results |
uploadResult |
POST /api/v1/results |
getResult |
GET /api/v1/results/{id} |
deleteResult |
DELETE /api/v1/results/{id} |
shareResult |
POST /api/v1/results/{id}/share |
revokeResultShares |
DELETE /api/v1/results/{id}/share |
subscribeEmail |
POST /api/public/email/subscribe |
confirmEmail |
POST /api/public/email/confirm |
readEmailPreferences |
POST /api/public/email/preferences |
setEmailPreferences |
PUT /api/public/email/preferences |
openUnsubscribe |
GET /api/public/email/unsubscribe |
unsubscribeEmail |
POST /api/public/email/unsubscribe |
exportEmailData |
POST /api/public/email/export |
deleteEmailData |
POST /api/public/email/delete |
accountEmailPreferences |
GET /api/v1/email/preferences |
setAccountEmailPreferences |
PUT /api/v1/email/preferences |
exportAccountEmailData |
POST /api/v1/email/export |
deleteAccountEmailData |
POST /api/v1/email/delete |
notificationPreferences |
GET /api/v1/notifications/preferences |
setNotificationPreferences |
PUT /api/v1/notifications/preferences |
drainNotifications |
POST /api/v1/notifications/drain |
getTrackerClaim (not in 0.1.0) |
GET /api/v1/tracker-claims/{key} |
acquireTrackerClaim (not in 0.1.0) |
POST /api/v1/tracker-claims/{key} |
updateTrackerClaim (not in 0.1.0) |
PUT /api/v1/tracker-claims/{key} |
listFindingReviews |
GET /api/v1/results/{id}/reviews |
updateFindingReview |
PUT /api/v1/results/{id}/reviews |
listDispositions |
GET /api/v1/results/{id}/dispositions |
setDisposition |
PUT /api/v1/results/{id}/dispositions |
listAudit |
GET /api/v1/audit |
exportAudit |
POST /api/v1/audit/export |
getRetention |
GET /api/v1/data/retention |
setRetention |
POST /api/v1/data/retention |
exportData |
POST /api/v1/data/export |
listDeletions |
GET /api/v1/data/deletions |
deleteEvidence |
POST /api/v1/data/deletions |
getSecurityPolicy |
GET /api/v1/security/policy |
setSecurityPolicy |
POST /api/v1/security/policy |
listDirectoryGroups (not in 0.1.0) |
GET /api/v1/directory/groups |
setTeamProjects (not in 0.1.0) |
PUT /api/v1/teams/{id}/projects |
linkTeamToDirectoryGroup (not in 0.1.0) |
PUT /api/v1/teams/{id}/directory-group |
getSessionPolicy (not in 0.1.0) |
GET /api/v1/security/session-policy |
setSessionPolicy (not in 0.1.0) |
PUT /api/v1/security/session-policy |
listMyDevices (not in 0.1.0) |
GET /api/v1/devices |
revokeMyDevice (not in 0.1.0) |
DELETE /api/v1/devices/{id} |
revokeMemberDevices (not in 0.1.0) |
DELETE /api/v1/members/{id}/devices |
listMySessions (not in 0.1.0) |
GET /api/v1/sessions |
endMySession (not in 0.1.0) |
DELETE /api/v1/sessions/{id} |
endMemberSessions (not in 0.1.0) |
DELETE /api/v1/members/{id}/sessions |
listIdpOrigins (not in 0.1.0) |
GET /api/v1/security/idp-origins |
approveIdpOrigin (not in 0.1.0) |
POST /api/v1/security/idp-origins |
removeIdpOrigin (not in 0.1.0) |
DELETE /api/v1/security/idp-origins |
getSsoRoleMapping (not in 0.1.0) |
GET /api/v1/security/sso-roles |
setSsoRoleMapping (not in 0.1.0) |
PUT /api/v1/security/sso-roles |
removeSsoRoleMapping (not in 0.1.0) |
DELETE /api/v1/security/sso-roles |
setMemberAccess |
POST /api/v1/security/member-access |
proveStepUp |
POST /api/v1/security/step-up |
getAgenticPrice (not in 0.1.0) |
GET /api/v1/agentic/price |
runAgentic |
POST /api/v1/agentic |
createBuild |
POST /api/v1/builds |