SDKs and CLI

Use the TypeScript SDK in application code. Use the CLI to check credentials, create test sessions, scaffold webhook handlers, and work with connector manifests.

Canonical API base URL

Production integrations use https://www.klarefi.com. A workspace-specific Convex HTTP URL shown in Settings → Developer remains valid for direct regional access.

Install

npm install @klarefi/node
npx klarefi --help

For repeated CLI use:

npm install -g klarefi
klarefi --help

The packages are:

Package	Use for
`@klarefi/node`	Server-side TypeScript calls, webhook signature helpers, and the applicant-plane intake client
`klarefi`	Local setup, diagnostics, webhook tests, connector manifests
`@klarefi/mcp`	Local fallback for the hosted stateless MCP endpoint at `https://www.klarefi.com/mcp`

To drive a hosted intake session with an agent, over REST, the SDK, or MCP, see Agent intake.

Configure

Set your API key in the environment:

export KLAREFI_API_KEY="sk_test_..."
export KLAREFI_BASE_URL="https://www.klarefi.com"
export KLAREFI_API_BASE_URL="https://www.klarefi.com"

Then verify the key:

npx klarefi whoami
npx klarefi doctor

The TypeScript SDK reads KLAREFI_BASE_URL; the CLI reads KLAREFI_API_BASE_URL. Set both to the dashboard value. The SDK resolves its URL as constructor baseUrl, then KLAREFI_BASE_URL, then https://www.klarefi.com as the production fallback.

You can also store the key for local CLI use:

npx klarefi login --api-key sk_test_...

Create a hosted intake session

Create the session from your backend and redirect the applicant to signed_url:

import { Klarefi } from "@klarefi/node";

const klarefi = new Klarefi({
  apiKey: process.env.KLAREFI_API_KEY!,
});

const session = await klarefi.sessions.create({
  case_type_id: "motor_claim",
  external_case_id: "claim_12345",
  external_applicant_id: "applicant_789",
  idempotency_key: "session_claim_12345",
  locale: "nl",
});

console.log(session.signed_url);

For a quick local check:

npx klarefi sessions create \
  --case-type motor_claim \
  --external-case-id claim_12345 \
  --url-only

Read the case

const caseFile = await klarefi.cases.retrieve(session.session_id);
const events = await klarefi.cases.events(session.session_id, {
  afterCursor: 0,
  limit: 100,
});
if (events.has_more) {
  // Poll again with afterCursor: events.next_cursor.
}
const pkg = await klarefi.cases.getPackage(session.session_id);

The operator and workflow surface is also available in the SDK:

// cases:read
const workspace = await klarefi.cases.getWorkspace(session.session_id);

// cases:review. The SDK generates an idempotency key when omitted.
// API keys cannot complete or reopen cases.
const command = await klarefi.cases.review(session.session_id, {
  command_type: "approve_fact",
  payload: { fact_id: "incident_date" },
});

// cases:read
const result = await klarefi.cases.getCommand(
  session.session_id,
  command.command_id,
);

// cases:review
const queue = await klarefi.operator.listQueue({ limit: 25 });

// workflows:read and workflows:write
const { workflows } = await klarefi.workflows.list();
const draft = await klarefi.workflows.saveDraft(workflowDeclaration);

// privacy:erase
const receipt = await klarefi.documents.erase("doc_def456");

workflows.saveDraft() validates and saves a draft. It cannot publish or activate a workflow; publishing remains human-controlled.

CLI equivalents:

npx klarefi cases get 550e8400-e29b-41d4-a716-446655440000
npx klarefi cases events 550e8400-e29b-41d4-a716-446655440000
npx klarefi cases package 550e8400-e29b-41d4-a716-446655440000

Webhook verification

Scaffold a receiver:

npx klarefi webhooks init --framework next

Verify signatures in code with the raw request body:

import { constructEvent, KlarefiWebhookSignatureError } from "@klarefi/node";

export async function POST(request: Request) {
  const rawBody = await request.text();

  try {
    const event = constructEvent(
      rawBody,
      request.headers.get("X-Klarefi-Signature"),
      process.env.KLAREFI_WEBHOOK_SECRET!,
    );

    if (event.event_type === "v1.case.completed") {
      // Read the case package and update your system of record.
    }

    return Response.json({ received: true });
  } catch (error) {
    if (error instanceof KlarefiWebhookSignatureError) {
      return new Response("Invalid signature", { status: 401 });
    }
    throw error;
  }
}

Send a signed test delivery:

npx klarefi webhooks test \
  --endpoint-url https://your-app.example.com/webhooks/klarefi \
  --signing-secret whsec_your_signing_secret

Verify a captured payload locally:

npx klarefi webhooks verify \
  --payload payload.json \
  --signature "t=1704067200,v1=..." \
  --secret whsec_your_signing_secret

Connectors

Connector CLI commands shown below build, validate, and test local manifests; they do not install them. The public connector API and TypeScript SDK can create, import, list, inspect, and delete active remote connectors. Connector create/import calls go live immediately, so review functions and credentials before routing traffic.

npx klarefi connectors init --name "Claims API"
npx klarefi connectors infer --from .
npx klarefi connectors validate klarefi.connector.json
npx klarefi connectors test klarefi.connector.json \
  --function lookup_record \
  --input fixtures/connector-input.json

Use --send with connectors test only when the manifest points at a safe test endpoint.

Errors

Non-2xx API responses throw KlarefiApiError with status, code, type, and requestId. Network failures throw KlarefiConnectionError.

Use with AI

Agents can read the docs as plain text:

export KLAREFI_DOCS_URL="https://www.klarefi.com"

curl "$KLAREFI_DOCS_URL/llms.txt"
curl "$KLAREFI_DOCS_URL/llms-full.txt"
curl "$KLAREFI_DOCS_URL/docs-source/api/quickstart"

Use the TypeScript SDK in application code. Use the CLI to check credentials, create test sessions, scaffold webhook handlers, and work with connector manifests.

Canonical API base URL

Production integrations use https://www.klarefi.com. A workspace-specific Convex HTTP URL shown in Settings → Developer remains valid for direct regional access.

Install

npm install @klarefi/node
npx klarefi --help

For repeated CLI use:

npm install -g klarefi
klarefi --help

The packages are:

Package	Use for
`@klarefi/node`	Server-side TypeScript calls, webhook signature helpers, and the applicant-plane intake client
`klarefi`	Local setup, diagnostics, webhook tests, connector manifests
`@klarefi/mcp`	Local fallback for the hosted stateless MCP endpoint at `https://www.klarefi.com/mcp`

To drive a hosted intake session with an agent, over REST, the SDK, or MCP, see Agent intake.

Configure

Set your API key in the environment:

export KLAREFI_API_KEY="sk_test_..."
export KLAREFI_BASE_URL="https://www.klarefi.com"
export KLAREFI_API_BASE_URL="https://www.klarefi.com"

Then verify the key:

npx klarefi whoami
npx klarefi doctor

You can also store the key for local CLI use:

npx klarefi login --api-key sk_test_...

Create a hosted intake session

Create the session from your backend and redirect the applicant to signed_url:

import { Klarefi } from "@klarefi/node";

const klarefi = new Klarefi({
  apiKey: process.env.KLAREFI_API_KEY!,
});

const session = await klarefi.sessions.create({
  case_type_id: "motor_claim",
  external_case_id: "claim_12345",
  external_applicant_id: "applicant_789",
  idempotency_key: "session_claim_12345",
  locale: "nl",
});

console.log(session.signed_url);

For a quick local check:

npx klarefi sessions create \
  --case-type motor_claim \
  --external-case-id claim_12345 \
  --url-only

Read the case

const caseFile = await klarefi.cases.retrieve(session.session_id);
const events = await klarefi.cases.events(session.session_id, {
  afterCursor: 0,
  limit: 100,
});
if (events.has_more) {
  // Poll again with afterCursor: events.next_cursor.
}
const pkg = await klarefi.cases.getPackage(session.session_id);

The operator and workflow surface is also available in the SDK:

// cases:read
const workspace = await klarefi.cases.getWorkspace(session.session_id);

// cases:review. The SDK generates an idempotency key when omitted.
// API keys cannot complete or reopen cases.
const command = await klarefi.cases.review(session.session_id, {
  command_type: "approve_fact",
  payload: { fact_id: "incident_date" },
});

// cases:read
const result = await klarefi.cases.getCommand(
  session.session_id,
  command.command_id,
);

// cases:review
const queue = await klarefi.operator.listQueue({ limit: 25 });

// workflows:read and workflows:write
const { workflows } = await klarefi.workflows.list();
const draft = await klarefi.workflows.saveDraft(workflowDeclaration);

// privacy:erase
const receipt = await klarefi.documents.erase("doc_def456");

workflows.saveDraft() validates and saves a draft. It cannot publish or activate a workflow; publishing remains human-controlled.

CLI equivalents:

npx klarefi cases get 550e8400-e29b-41d4-a716-446655440000
npx klarefi cases events 550e8400-e29b-41d4-a716-446655440000
npx klarefi cases package 550e8400-e29b-41d4-a716-446655440000

Webhook verification

Scaffold a receiver:

npx klarefi webhooks init --framework next

Verify signatures in code with the raw request body:

import { constructEvent, KlarefiWebhookSignatureError } from "@klarefi/node";

export async function POST(request: Request) {
  const rawBody = await request.text();

  try {
    const event = constructEvent(
      rawBody,
      request.headers.get("X-Klarefi-Signature"),
      process.env.KLAREFI_WEBHOOK_SECRET!,
    );

    if (event.event_type === "v1.case.completed") {
      // Read the case package and update your system of record.
    }

    return Response.json({ received: true });
  } catch (error) {
    if (error instanceof KlarefiWebhookSignatureError) {
      return new Response("Invalid signature", { status: 401 });
    }
    throw error;
  }
}

Send a signed test delivery:

npx klarefi webhooks test \
  --endpoint-url https://your-app.example.com/webhooks/klarefi \
  --signing-secret whsec_your_signing_secret

Verify a captured payload locally:

npx klarefi webhooks verify \
  --payload payload.json \
  --signature "t=1704067200,v1=..." \
  --secret whsec_your_signing_secret

Connectors

npx klarefi connectors init --name "Claims API"
npx klarefi connectors infer --from .
npx klarefi connectors validate klarefi.connector.json
npx klarefi connectors test klarefi.connector.json \
  --function lookup_record \
  --input fixtures/connector-input.json

Use --send with connectors test only when the manifest points at a safe test endpoint.

Errors

Non-2xx API responses throw KlarefiApiError with status, code, type, and requestId. Network failures throw KlarefiConnectionError.

Use with AI

Agents can read the docs as plain text:

export KLAREFI_DOCS_URL="https://www.klarefi.com"

curl "$KLAREFI_DOCS_URL/llms.txt"
curl "$KLAREFI_DOCS_URL/llms-full.txt"
curl "$KLAREFI_DOCS_URL/docs-source/api/quickstart"

Use the TypeScript SDK in application code. Use the CLI to check credentials, create test sessions, scaffold webhook handlers, and work with connector manifests.

Canonical API base URL

Production integrations use https://www.klarefi.com. A workspace-specific Convex HTTP URL shown in Settings → Developer remains valid for direct regional access.

Install

npm install @klarefi/node
npx klarefi --help

For repeated CLI use:

npm install -g klarefi
klarefi --help

The packages are:

Package	Use for
`@klarefi/node`	Server-side TypeScript calls, webhook signature helpers, and the applicant-plane intake client
`klarefi`	Local setup, diagnostics, webhook tests, connector manifests
`@klarefi/mcp`	Local fallback for the hosted stateless MCP endpoint at `https://www.klarefi.com/mcp`

To drive a hosted intake session with an agent, over REST, the SDK, or MCP, see Agent intake.

Configure

Set your API key in the environment:

export KLAREFI_API_KEY="sk_test_..."
export KLAREFI_BASE_URL="https://www.klarefi.com"
export KLAREFI_API_BASE_URL="https://www.klarefi.com"

Then verify the key:

npx klarefi whoami
npx klarefi doctor

You can also store the key for local CLI use:

npx klarefi login --api-key sk_test_...

Create a hosted intake session

Create the session from your backend and redirect the applicant to signed_url:

import { Klarefi } from "@klarefi/node";

const klarefi = new Klarefi({
  apiKey: process.env.KLAREFI_API_KEY!,
});

const session = await klarefi.sessions.create({
  case_type_id: "motor_claim",
  external_case_id: "claim_12345",
  external_applicant_id: "applicant_789",
  idempotency_key: "session_claim_12345",
  locale: "nl",
});

console.log(session.signed_url);

For a quick local check:

npx klarefi sessions create \
  --case-type motor_claim \
  --external-case-id claim_12345 \
  --url-only

Read the case

const caseFile = await klarefi.cases.retrieve(session.session_id);
const events = await klarefi.cases.events(session.session_id, {
  afterCursor: 0,
  limit: 100,
});
if (events.has_more) {
  // Poll again with afterCursor: events.next_cursor.
}
const pkg = await klarefi.cases.getPackage(session.session_id);

The operator and workflow surface is also available in the SDK:

// cases:read
const workspace = await klarefi.cases.getWorkspace(session.session_id);

// cases:review. The SDK generates an idempotency key when omitted.
// API keys cannot complete or reopen cases.
const command = await klarefi.cases.review(session.session_id, {
  command_type: "approve_fact",
  payload: { fact_id: "incident_date" },
});

// cases:read
const result = await klarefi.cases.getCommand(
  session.session_id,
  command.command_id,
);

// cases:review
const queue = await klarefi.operator.listQueue({ limit: 25 });

// workflows:read and workflows:write
const { workflows } = await klarefi.workflows.list();
const draft = await klarefi.workflows.saveDraft(workflowDeclaration);

// privacy:erase
const receipt = await klarefi.documents.erase("doc_def456");

workflows.saveDraft() validates and saves a draft. It cannot publish or activate a workflow; publishing remains human-controlled.

CLI equivalents:

npx klarefi cases get 550e8400-e29b-41d4-a716-446655440000
npx klarefi cases events 550e8400-e29b-41d4-a716-446655440000
npx klarefi cases package 550e8400-e29b-41d4-a716-446655440000

Webhook verification

Scaffold a receiver:

npx klarefi webhooks init --framework next

Verify signatures in code with the raw request body:

import { constructEvent, KlarefiWebhookSignatureError } from "@klarefi/node";

export async function POST(request: Request) {
  const rawBody = await request.text();

  try {
    const event = constructEvent(
      rawBody,
      request.headers.get("X-Klarefi-Signature"),
      process.env.KLAREFI_WEBHOOK_SECRET!,
    );

    if (event.event_type === "v1.case.completed") {
      // Read the case package and update your system of record.
    }

    return Response.json({ received: true });
  } catch (error) {
    if (error instanceof KlarefiWebhookSignatureError) {
      return new Response("Invalid signature", { status: 401 });
    }
    throw error;
  }
}

Send a signed test delivery:

npx klarefi webhooks test \
  --endpoint-url https://your-app.example.com/webhooks/klarefi \
  --signing-secret whsec_your_signing_secret

Verify a captured payload locally:

npx klarefi webhooks verify \
  --payload payload.json \
  --signature "t=1704067200,v1=..." \
  --secret whsec_your_signing_secret

Connectors

npx klarefi connectors init --name "Claims API"
npx klarefi connectors infer --from .
npx klarefi connectors validate klarefi.connector.json
npx klarefi connectors test klarefi.connector.json \
  --function lookup_record \
  --input fixtures/connector-input.json

Use --send with connectors test only when the manifest points at a safe test endpoint.

Errors

Non-2xx API responses throw KlarefiApiError with status, code, type, and requestId. Network failures throw KlarefiConnectionError.

Use with AI

Agents can read the docs as plain text:

export KLAREFI_DOCS_URL="https://www.klarefi.com"

curl "$KLAREFI_DOCS_URL/llms.txt"
curl "$KLAREFI_DOCS_URL/llms-full.txt"
curl "$KLAREFI_DOCS_URL/docs-source/api/quickstart"

Install

Configure

Create a hosted intake session

Read the case

Webhook verification

Connectors

Errors

Use with AI

On this page

SDKs and CLI

Install

Configure

Create a hosted intake session

Read the case

Webhook verification

Connectors

Errors

Use with AI

On this page

SDKs and CLI

Install

Configure

Create a hosted intake session

Read the case

Webhook verification

Connectors

Errors

Use with AI

On this page