Skip to content

    Type a page, a command such as keryn scan, or a rule id.

    Keryn SDK

    Describes Keryn 0.5.2 and keryn-rules 0.8.0. Changelog

    View as Markdown

    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.

    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.

    Terminal window
    npm install @keryn/sdk

    quickstart.mjs:

    import { createClient, KerynApiError } from "@keryn/sdk";
    const keryn = createClient({ apiKey: process.env.KERYN_API_KEY });
    const health = await keryn.getHealth(); // needs no credential
    console.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);
    }
    Terminal window
    node quickstart.mjs
    ok
    401 authentication_required

    With KERYN_API_KEY set to an organization API key, calls that need a credential run as that key. The examples below need one.

    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 canceled
    console.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.json
    for (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.

    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.

    • 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 (KerynResult and the other schema types).
    • @keryn/sdk 0.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 KerynApiError with retryAfterSeconds; pass your own fetch to add retries or a timeout.
    • There are no pagination or polling helpers. To wait for a scan, call getScan until its status is final.
    • An answer that is not JSON resolves to undefined.
    • apiKey and workerToken together 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.

    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