> ## Documentation Index
> Fetch the complete documentation index at: https://docs.keenable.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Every page is listed in https://docs.keenable.ai/llms.txt. To pick a product for a job, read https://docs.keenable.ai/choose.md
> Setup steps for agents, covering the SDKs, the MCP server and the CLI: https://docs.keenable.ai/skill.md
> Keenable search and fetch work without an API key. To add them to code, use the official SDK for the project's language: https://docs.keenable.ai/sdks.md
> Without a key, call POST https://api.keenable.ai/v1/search/public or GET https://api.keenable.ai/v1/fetch/public with an X-Keenable-Title header that names your app.
> With a key, send it in the X-API-Key header and read it from the KEENABLE_API_KEY environment variable. Never ask a user to paste a key into chat. Every access method: https://docs.keenable.ai/auth.md
> To get an API key without the console, use device login: https://docs.keenable.ai/authentication.md#device-login
> MCP server: https://api.keenable.ai/mcp (no key, or X-API-Key; keyless Codex uses https://api.keenable.ai/mcp-public), or https://api.keenable.ai/mcp-oauth for OAuth sign-in. These docs are an MCP server at https://docs.keenable.ai/mcp and the OpenAPI spec is at https://docs.keenable.ai/api-reference/openapi.json
> Keenable searches and fetches public web pages. If a question needs no web information, skip the call.
> On 402 with an API key (code insufficient_credits), stop and ask a human to add credits; don't retry. On 429, wait the number of seconds in Retry-After, then retry. Before you ship, follow https://docs.keenable.ai/production.md
> Every error, with its cause and fix, is in https://docs.keenable.ai/errors.md and moving from another search API is covered in https://docs.keenable.ai/migrate.md
> Before you compare Keenable with another search API, read https://docs.keenable.ai/guides/evaluate-search-apis.md

# TypeScript SDK for web search and fetch

> Install the keenable npm package, run a keyless web search, fetch pages, create Monitors, verify webhooks and handle typed errors from TypeScript.

The Keenable TypeScript SDK gives your code web search, page fetch and [Monitors](https://docs.keenable.ai/products/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](https://docs.keenable.ai/sdks/python.md), [Go](https://docs.keenable.ai/sdks/go.md) and [Rust](https://docs.keenable.ai/sdks/rust.md). For what all four SDKs share, see [SDKs](https://docs.keenable.ai/sdks.md).

## Install

Install the package. The SDK needs Node 18 or newer:

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
npm install keenable
```

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](https://docs.keenable.ai/api-keys.md) 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:

| Setting | TypeScript | Default |
| - | - | - |
| API key | `apiKey` | `KEENABLE_API_KEY` |
| Base URL | `baseUrl` | `KEENABLE_API_URL`, else `https://api.keenable.ai` |
| Timeout for each attempt | `timeoutMs` | `30000` |
| Retries after a failed request. Needs SDK 0.1.5 or later | `maxRetries` | `2` |
| Headers on every request. Needs SDK 0.1.5 or later | `defaultHeaders` | none |
| Traffic source, sent as `X-Keenable-Title` | `clientSource` | `Keenable SDK` |
| Your own `fetch` function, for a proxy or custom transport | `fetch` | `globalThis.fetch` |

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:

```typescript index.ts theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
import { Keenable } from "keenable";

async function main() {
  const client = new Keenable(); // keyless: no API key needed to try it
  const results = await client.search("fastest inference providers 2026", { maxResults: 3 });
  console.log(results.toContext());
}

main();
```

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.

| What it does | TypeScript |
| - | - |
| Search the web | `search(query, options)` |
| Render results as a citable block | `toContext()` |
| List the results the block cites | `cited()` |

Search options use camelCase: `excludeDomains`, `publishedAfter`, `publishedBefore`, `acquiredAfter`, `acquiredBefore`, `snippetMaxLength`, `maxResults`, `queryTime`, `objective`, `disableCards`, `site` and `mode`. Each one is described under [Search parameters](https://docs.keenable.ai/products/search.md#key-parameters). To change how much text the citable block holds, see [Context size](https://docs.keenable.ai/sdks.md#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:

```typescript index.ts theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
import { Keenable } from "keenable";

async function main() {
  const client = new Keenable(); // keyless: no API key needed to try it
  const page = await client.fetch("https://keenable.ai");
  console.log(page.title);
  console.log(page.content.slice(0, 300));
}

main();
```

| What it does | TypeScript |
| - | - |
| Fetch one page as markdown | `fetch(url, options)` |
| Render the page as a citable block | `toContext()` |

Pass the fetch options as `fetch(url, { maxChars, live, prompt })`. Each one is described under [Fetch parameters](https://docs.keenable.ai/products/fetch.md#key-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](https://docs.keenable.ai/api-reference/monitors/create.md) 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:

```typescript index.ts theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
import { Keenable } from "keenable";

async function main() {
  // reads KEENABLE_API_KEY from the environment
  const client = new Keenable();
  const monitor = await client.monitors.create({
    name: "Open-weights LLM releases",
    search: { query: "new open-weights LLM releases" },
    webhook: {
      url: "https://hooks.example.com/keenable",
      events: ["monitor.result.found", "monitor.disabled"],
    },
  });
  console.log(monitor.id, monitor.status);
  console.log(monitor.webhook?.secret); // shown once: store it
}

main();
```

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.

| What it does | TypeScript |
| - | - |
| Create a monitor | `create({ search, ... })` |
| List monitors | `list(), listAll()` |
| Read, change or delete one monitor | `get, update, delete` |
| Pause or resume | `pause, resume` |
| Start a run, read runs | `trigger, runs, run` |
| Read a monitor's results | `results` |
| Webhook deliveries, counts, bulk actions | `deliveries, stats, bulk` |

`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](https://docs.keenable.ai/products/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](https://docs.keenable.ai/products/monitors#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.

| Item | TypeScript |
| - | - |
| Function | `verifyWebhook(payload, headers, secret, options)` |
| Returns | a promise of a `WebhookEvent` |
| Failed check | `WebhookVerificationError` |
| Clock tolerance, 5 minutes by default | `toleranceSeconds` in the options object |

`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](https://docs.keenable.ai/products/monitors#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](https://docs.keenable.ai/errors.md).

| Error | When | Retryable |
| - | - | - |
| `KeenableError` | Base class of every error below | Depends on the error |
| `KeenableAPIError` | A non-2xx response with no more specific class. Read `statusCode`, `code`, `fix` and `requestId` | Yes for 408 and 5xx, no for other codes |
| `KeenableAuthError` | HTTP 401 or 403, the API key was rejected | No |
| `KeenableInsufficientCreditsError` | HTTP 402, out of funds. Alias `KeenableCreditsError`. Needs SDK 0.1.5 or later | No |
| `KeenableRateLimitError` | HTTP 429, rate limit exceeded. Read `retryAfterSeconds` and `limit` | Yes, unless `Retry-After` is over 60 seconds |
| `KeenableConnectionError` | The API could not be reached | Yes |
| `KeenableTimeoutError` | No answer within `timeoutMs`. A subclass of `KeenableConnectionError`. Needs SDK 0.1.5 or later | Yes |
| `KeenableInvalidRequestError` | Bad arguments. No request was sent | No |
| `WebhookVerificationError` | A webhook delivery failed `verifyWebhook`. Needs SDK 0.2.0 or later | Not a request |

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:

```typescript index.ts theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
import { Keenable, KeenableAPIError } from "keenable";

async function main() {
  const client = new Keenable(); // keyless: no API key needed to try it
  try {
    // A path is not a valid excludeDomains entry, so the API returns 400.
    await client.search("postmortem template", { excludeDomains: ["example.com/blog"] });
  } catch (err) {
    if (!(err instanceof KeenableAPIError)) throw err;
    console.log(err.statusCode, err.code);
    console.log(err.param, err.value);
    console.log("retryable:", err.retryable);
    console.log(err.fix);
  }
}

main();
```

You see the status, the code, the rejected parameter and value, and the fix:

```text Output theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
400 invalid_parameter
exclude_domains example.com/blog
retryable: false
Fix "exclude_domains" and retry: paths are not supported; give only the host, such as example.com.
```

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](https://docs.keenable.ai/tool-calling.md).
* 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](https://github.com/keenableai/keenable-sdk/blob/main/typescript/CHANGELOG.md).
* Source and package: [README](https://github.com/keenableai/keenable-sdk/blob/main/typescript/README.md), [npm](https://www.npmjs.com/package/keenable).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.