ClearRun SDK help

Start here

1. How to install the ClearRun SDK

   Run npm install @clearrun/sdk. It works in Node.js 18 or newer. You can start in mock mode with no key, then add a key for real scores. ClearRun help center.

2. How to create a ClearRun client (createKernelClient)

   Call createKernelClient(). It finds your key in hosted.apiKey, then CLEARRUN_API_KEY, then the file saved by clearrun login. From the ClearRun help center.

3. How to score text with the ClearRun SDK (client.score)

   Call client.score({ responseText }). It sends the text to POST /api/score and returns { verdict, receipt }. Use it when you have an answer but not the prompt.

4. How to use ClearRun mock mode for local development (forceMock)

   Create the client with createKernelClient({ forceMock: true }). It returns local test verdicts on your computer with no key and no network. Steps inside.

All SDK articles

• How to install the ClearRun SDK

  Run npm install @clearrun/sdk. It works in Node.js 18 or newer. You can start in mock mode with no key, then add a key for real scores. ClearRun help center.

• How to create a ClearRun client (createKernelClient)

  Call createKernelClient(). It finds your key in hosted.apiKey, then CLEARRUN_API_KEY, then the file saved by clearrun login. From the ClearRun help center.

• How to score text with the ClearRun SDK (client.score)

  Call client.score({ responseText }). It sends the text to POST /api/score and returns { verdict, receipt }. Use it when you have an answer but not the prompt.

• How to score an answer with its prompt (client.evaluate)

  Call client.evaluate({ responseText, prompt }). It sends both to POST /api/evaluate, which scores the answer with the question that produced it. Steps inside.

• How to get an answer and a score in one call (client.chat)

  Call client.chat({ message }). ClearRun writes an answer, scores it, and returns responseText with the verdict. Step-by-step help from the ClearRun help center.

• How to look up a verdict id with the SDK (client.verify)

  Call client.verify({ verdictId }), or use createVerifyClient() if you have no key. It calls GET /api/verify/{verdictId}, sends no key, and uses no credits.

• How to use ClearRun mock mode for local development (forceMock)

  Create the client with createKernelClient({ forceMock: true }). It returns local test verdicts on your computer with no key and no network. Steps inside.

• How to set the mock chat reply in tests (mock.chatResponse)

  Pass mock: { chatResponse: 'Cooked rice should go in the fridge within two hours.' } to createKernelClient. In mock mode, client.chat returns that text as responseText. Read more in the ClearRun help center.

• How to set a request timeout in the ClearRun SDK (timeoutMs)

  Set hosted.timeoutMs when you create the client. The SDK aborts any request that takes longer. There is no timeout unless you set one. ClearRun help center.

• How to change the API base URL in the SDK (baseUrl)

  Set hosted.baseUrl when you create the client. The default is https://api.clearrun.net. Most people never change it. Read more in the ClearRun help center.

• How to handle ClearRun SDK errors (HostedApiError)

  Any non-2xx reply rejects with HostedApiError. Read err.status and err.code. A 429 adds err.retryAfter, a 402 adds err.creditsNeeded and err.currentBalance.

• What is MissingApiKeyError?

  MissingApiKeyError means the SDK found no API key. The first score, evaluate or chat call rejects with it when no key is set and you did not ask for mock mode.

• How to pass your own fetch to the SDK (deps.fetch)

  Pass deps: { fetch: yourFetch } to createKernelClient or createVerifyClient. The SDK uses it for every request. Step-by-step help from the ClearRun help center.

• How to read the signature fields on a ClearRun verdict

  Hosted verdicts carry signature, signatureKeyId and signatureAlg. They show ClearRun signed the verdict. A plain answer from the ClearRun help center.

• How to read the receipt on a ClearRun response

  Hosted ClearRun score and evaluate responses can include a receipt next to the verdict: hashes, signature, chain link and status. How to read it and keep it.

• Where are the ClearRun TypeScript types? (@clearrun/core-types)

  In @clearrun/core-types. The SDK installs it and re-exports the main types, so you can import Verdict, VerdictRisk and the request types from @clearrun/sdk.

• What are @clearrun/scoring, @clearrun/vendors and @clearrun/security?

  They are smaller open packages that sit around the SDK. Most people only need @clearrun/sdk, @clearrun/cli or @clearrun/mcp. From the ClearRun help center.

• Is there a ClearRun Python SDK?

  No. ClearRun's SDK is for Node.js only. From Python, call the HTTP API directly with any HTTP client. It is a few lines. Read more in the ClearRun help center.

• Does the ClearRun SDK run in the browser?

  Use the ClearRun SDK on a server, not in the browser. It targets Node.js 18 or newer, the API blocks calls from web pages, and a browser key is public.

Other topics

• Get started with ClearRun
• What the ClearRun score means
• ClearRun API, CLI, SDK, and MCP
• ClearRun signed receipts
• ClearRun plans and credits
• ClearRun privacy and data
• ClearRun limits and errors
• ClearRun CLI help
• ClearRun MCP help
• ClearRun API help
• ClearRun API key help
• Use ClearRun with other tools
• ClearRun best practices