Install
Install the package. The SDK needs Node 18 or newer:npm ls keenable.
Authenticate
Search and fetch work without an API key. An API key raises your rate limit, and Monitors needs one. SetKEENABLE_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.
Search
This program runs one keyless search and prints the top 3 results as a citable block:index.ts
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 underclient.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
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. CallverifyWebhook(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 setsretryable, 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
Output
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
TOOLSto your chat completions client and run each call withrunToolCall. 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 honourredirect: "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.