Skip to main content
The Keenable TypeScript SDK gives your code web search, page fetch and Monitors. This page covers version 0.2.0, the version in the SDK repository. The latest release on npm is 0.1.4 (checked 2026-11-19), so the parts marked with a newer “Needs SDK” version aren’t in the package you install yet. For the other languages, see Python, Go and Rust. For what all four SDKs share, see SDKs.

Install

Install the package. The SDK needs Node 18 or newer:
The package has no runtime dependencies. It ships ES module and CommonJS builds. To see which version you have, run npm ls keenable.

Authenticate

Search and fetch work without an API key. An API key raises your rate limit, and Monitors needs one. Set KEENABLE_API_KEY and create the client with new Keenable(), which reads the variable. To pass the key in code, use new Keenable({ apiKey }). If you pass no apiKey and KEENABLE_API_KEY is unset, the client calls the keyless endpoints. The constructor takes these settings: Every call also takes signal, timeoutMs, maxRetries and headers in its options object. They override the client’s settings for that call. Needs SDK 0.1.5 or later: maxRetries and defaultHeaders, and the per-call timeoutMs, maxRetries and headers. Version 0.1.4 takes only signal for each call. This program runs one keyless search and prints the top 3 results as a citable block:
index.ts
Save it as index.ts and run npx tsx index.ts. You see one [n] Title (url) header per result, followed by the page text. Search options use camelCase: excludeDomains, publishedAfter, publishedBefore, acquiredAfter, acquiredBefore, snippetMaxLength, maxResults, queryTime, objective, disableCards, site and mode. Each one is described under Search parameters. To change how much text the citable block holds, see Context size. Needs SDK 0.1.5 or later: excludeDomains, disableCards and mode: "realtime". Needs SDK 0.2.0 or later: objective.

Fetch

This program fetches one page without a key and prints its title and the first 300 characters of its markdown:
index.ts
Pass the fetch options as fetch(url, { maxChars, live, prompt }). Each one is described under Fetch parameters. Needs SDK 0.1.5 or later: the maxChars, live and prompt options. Version 0.1.4 takes only signal.

Monitors

Needs SDK 0.2.0 or later. The latest release on npm is 0.1.4. Until a newer release is out, call the Monitors API over HTTP. A monitor watches the web for a topic and keeps every new page that matches. The Monitors API is under client.monitors. It needs an API key: without one, a call fails with the SDK’s authentication error and sends no request. This program creates a monitor with a webhook, then prints its ID, status and webhook signing secret:
index.ts
Set KEENABLE_API_KEY before you run it. Keep the secret: the API returns it only here and in an update that adds the first webhook, and you need it to verify each delivery. Store it where your webhook handler can read it, and keep it out of logs. listAll() is an async iterator over every monitor. create always sends an Idempotency-Key, so the SDK can retry it without creating a second monitor. For queries, schedules and result fields, see Monitors.

Verify webhooks

Needs SDK 0.2.0 or later. The latest release on npm is 0.1.4. Until a newer release is out, verify the signature without the SDK, as Verify a webhook describes. Check each webhook delivery’s signature before you act on it. Call verifyWebhook(payload, headers, secret, options), imported from "keenable". It needs no client and no API key. verifyWebhook is async because it uses Web Crypto. await it before you read the event. Answer a failed check with 400 and don’t act on the delivery. Drop repeated deliveries by the event’s ID, which stays the same across retries. For a complete handler, see Verify a webhook.

Errors

The TypeScript SDK throws typed errors. Before an error reaches your code, the SDK retries the request, by default up to 2 times, when the Retryable column says yes. If the API’s error body sets retryable, that value decides instead of the status code. The Monitors update, trigger and bulk calls are retried only on a 429, which the API sends before it changes anything, because repeating them after another error could apply the change twice. For what each status code means and how to fix it, see Errors. An API error carries what the API said about the failure: statusCode, code, type, fix, retryable, retryAfterSeconds, requestId, param, value and reason. Branch on the code, not on the message. This program sends a search that the API rejects with 400 and prints what the error carries:
index.ts
You see the status, the code, the rejected parameter and value, and the fix:
Output
Needs SDK 0.1.5 or later: automatic retries, every field this program reads, and retryAfterSeconds and limit on KeenableRateLimitError. In version 0.1.4 an API error carries only statusCode and body, and the SDK doesn’t retry.

Async

The TypeScript client has one interface, and every network call returns a promise: search, fetch, runToolCall, every monitors method and verifyWebhook. To cancel a call, pass an AbortSignal as signal in the call’s options. The SDK also stops waiting between retries when the signal aborts.

Notes

  • To give a model web search as a tool, pass TOOLS to your chat completions client and run each call with runToolCall. See Tool calling.
  • The SDK never follows a redirect, so your API key goes only to the configured host. If you pass your own fetch, it must honour redirect: "manual". Needs SDK 0.1.5 or later.
  • Monitors and webhook verification arrived in version 0.2.0. To see what the version you installed includes, read the TypeScript changelog.
  • Source and package: README, npm.