# Keryn SDK

Describes Keryn 0.5.2 and keryn-rules 0.8.0.

> The Keryn SDK (@keryn/sdk): a typed TypeScript client for the Keryn Cloud API, generated from its OpenAPI document.

Source: https://keryn.dev/docs/reference/sdk/

For the current npm version and availability, see [Download](https://keryn.dev/download/#sdk).

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

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.

```sh
npm install @keryn/sdk
```

`quickstart.mjs`:

```js
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);
}
```

```sh
node quickstart.mjs
```

```text
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.

## Calls and errors

```ts
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.

## Types

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/`:

```ts
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.

## 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.

```ts
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](https://keryn.dev/docs/reference/api/) 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

- 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](https://keryn.dev/docs/reference/api/#conventions) page.

## Methods

One method per operation of the [Cloud API](https://keryn.dev/docs/reference/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](https://keryn.dev/docs/reference/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` |
