> ## 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

# Rust SDK for web search and fetch

> Add the keenable crate, run a keyless web search on Tokio, fetch pages, create Monitors, verify webhooks and match on keenable::Error variants.

The Keenable Rust 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 crates.io is 0.1.0 (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 [TypeScript](https://docs.keenable.ai/sdks/typescript.md), [Python](https://docs.keenable.ai/sdks/python.md) and [Go](https://docs.keenable.ai/sdks/go.md). For what all four SDKs share, see [SDKs](https://docs.keenable.ai/sdks.md).

## Install

Install the package. The SDK needs Rust 1.80 or newer:

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

The SDK is async: the samples also need `cargo add tokio --features macros,rt-multi-thread`. TLS goes through rustls by default, so no system library is needed. To use the platform's TLS library, turn off default features and turn on `native-tls`.

To see which version you have, run `cargo tree -p keenable --depth 0`.

## 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 `Client::new()`, which reads the variable. To pass the key in code, use `Client::with_options(Options { api_key: Some(key), ..Default::default() })`. `api_key: None` reads `KEENABLE_API_KEY`. `Some(String::new())` forces the keyless endpoints even when the variable is set.

The constructor takes these settings:

| Setting | Rust | Default |
| - | - | - |
| API key | `api_key` | `KEENABLE_API_KEY` |
| Base URL | `base_url` | `KEENABLE_API_URL`, else `https://api.keenable.ai` |
| Timeout for each attempt, a `Duration` | `timeout` | 30 seconds |
| Retries after a failed request | `max_retries` | `2` |
| Headers on every request | `headers` | none |
| Traffic source, sent as `X-Keenable-Title` | `client_source` | `Keenable SDK` |
| Your own `reqwest::ClientBuilder`, for a proxy or custom TLS | `http_client` | one the SDK creates |

`SearchOptions` and `FetchOptions` carry a `request: RequestOptions` field that sets `timeout`, `max_retries` and `headers` for one call. For Monitors, `client.monitors().with_request(RequestOptions { .. })` does the same.

Needs SDK 0.2.0 or later: `client.monitors().with_request`.

## Search

This program runs one keyless search and prints the top 3 results as a citable block:

```rust main.rs theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
use keenable::{Client, SearchOptions};

#[tokio::main]
async fn main() -> Result<(), keenable::Error> {
    let client = Client::new()?; // keyless: no API key needed to try it
    let results = client
        .search_with(
            "fastest inference providers 2026",
            &SearchOptions {
                max_results: Some(3),
                ..Default::default()
            },
        )
        .await?;
    println!("{}", results.to_context());
    Ok(())
}
```

Save it as `src/main.rs` and run `cargo run`. You see one `[n] Title (url)` header per result, followed by the page text.

| What it does | Rust |
| - | - |
| Search the web | `search(query), search_with(query, &SearchOptions)` |
| Render results as a citable block | `to_context(), to_context_with(&ContextOptions)` |
| List the results the block cites | `cited(), cited_with(&ContextOptions)` |

Search options are fields on `keenable::SearchOptions`: `exclude_domains`, `published_after`, `published_before`, `acquired_after`, `acquired_before`, `snippet_max_length`, `max_results`, `query_time`, `objective`, `disable_cards`, `site` and `mode`. Fill the ones you need and end with `..Default::default()`. 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).

## Fetch

This program fetches one page without a key and prints its title and the first 300 characters of its markdown:

```rust main.rs theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
use keenable::Client;

#[tokio::main]
async fn main() -> Result<(), keenable::Error> {
    let client = Client::new()?; // keyless: no API key needed to try it
    let page = client.fetch("https://keenable.ai").await?;
    println!("{}", page.title);

    let content: String = page.content.chars().take(300).collect();
    println!("{}", content);
    Ok(())
}
```

| What it does | Rust |
| - | - |
| Fetch one page as markdown | `fetch(url)` |
| Fetch with options | `fetch_with(url, &FetchOptions)` |
| Render the page as a citable block | `to_context()` |

Pass the fetch options through `fetch_with` and the `max_chars`, `live` and `prompt` fields of `keenable::FetchOptions`. Each one is described under [Fetch parameters](https://docs.keenable.ai/products/fetch.md#key-parameters).

## Monitors

Needs SDK 0.2.0 or later. The latest release on crates.io is 0.1.0. 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:

```rust main.rs theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
use keenable::{Client, MonitorCreateParams, MonitorSearchParams, MonitorWebhookParams};

#[tokio::main]
async fn main() -> Result<(), keenable::Error> {
    // reads KEENABLE_API_KEY from the environment
    let client = Client::new()?;
    let monitor = client
        .monitors()
        .create(&MonitorCreateParams {
            name: Some("Open-weights LLM releases".into()),
            search: MonitorSearchParams::new("new open-weights LLM releases"),
            webhook: Some(MonitorWebhookParams {
                url: Some("https://hooks.example.com/keenable".into()),
                events: Some(vec!["monitor.result.found".into(), "monitor.disabled".into()]),
            }),
            ..Default::default()
        })
        .await?;
    println!("{} {}", monitor.id, monitor.status);
    if let Some(webhook) = monitor.webhook {
        println!("{}", webhook.secret.unwrap_or_default()); // shown once: store it
    }
    Ok(())
}
```

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 | Rust |
| - | - |
| Create a monitor | `create(&MonitorCreateParams)` |
| List monitors | `list, list_all` |
| 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` |

`list_all` returns a `MonitorPager`. In `MonitorUpdateParams`, `Some(None)` removes the name, schedule, webhook, output schema or metadata. `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 crates.io is 0.1.0. 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 `keenable::verify_webhook(payload, &headers, secret)`, in crate `keenable`. It needs no client and no API key.

| Item | Rust |
| - | - |
| Function | `keenable::verify_webhook(payload, &headers, secret)` |
| Returns | `Result<WebhookEvent>` |
| Failed check | `Error::WebhookVerification` |
| Clock tolerance, 5 minutes by default | `verify_webhook_with` and `WebhookOptions` |

Pass the raw body as `&[u8]` and the headers as a `keenable::reqwest::header::HeaderMap`. 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 Rust SDK returns 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 |
| - | - | - |
| `keenable::Error` | The enum every call returns. Match on the variant | Depends on the error |
| `Error::Api` | A non-2xx response with no more specific variant. Read `err.api_error()` | Yes for 408 and 5xx, no for other codes |
| `Error::Auth` | HTTP 401 or 403, the API key was rejected | No |
| `Error::InsufficientCredits` | HTTP 402, out of funds | No |
| `Error::RateLimit` | HTTP 429, rate limit exceeded. Read `retry_after` and `limit` on `err.api_error()` | Yes, unless `Retry-After` is over 60 seconds |
| `Error::Connection` | The API could not be reached. `err.is_timeout()` reports a deadline | Yes |
| `Error::InvalidRequest` | Bad arguments. No request was sent | No |
| `Error::WebhookVerification` | A webhook delivery failed `verify_webhook`. Needs SDK 0.2.0 or later | Not a request |

`err.api_error()` returns the `ApiError` behind `Auth`, `RateLimit`, `InsufficientCredits` and `Api`, so one branch reads every non-2xx response.

An API error carries what the API said about the failure: `status_code`, `code`, `error_type`, `fix`, `retryable`, `retry_after`, `request_id`, `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:

```rust main.rs theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
use keenable::{Client, SearchOptions};

#[tokio::main]
async fn main() -> Result<(), keenable::Error> {
    let client = Client::new()?; // keyless: no API key needed to try it
    let opts = SearchOptions {
        // A path is not a valid exclude_domains entry, so the API returns 400.
        exclude_domains: Some(vec!["example.com/blog".into()]),
        ..Default::default()
    };

    let err = match client.search_with("postmortem template", &opts).await {
        Ok(_) => return Ok(()),
        Err(err) => err,
    };
    let Some(api) = err.api_error() else {
        return Err(err);
    };
    println!("{} {}", api.status_code, api.code.as_deref().unwrap_or_default());
    println!("{} {}", api.param.as_deref().unwrap_or_default(), api.value.as_deref().unwrap_or_default());
    if let Some(retryable) = api.retryable {
        println!("retryable: {retryable}");
    }
    println!("{}", api.fix.as_deref().unwrap_or_default());
    Ok(())
}
```

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.
```

## Async

The Rust client is async only. `search`, `fetch`, `run_tool_call` and every Monitors method are `async fn`s, so you `.await` them inside a Tokio runtime, such as a `#[tokio::main]` function.

Add Tokio with the `macros` and `rt-multi-thread` features, as in [Install](#install). `verify_webhook` is a plain function and needs no runtime.

## Notes

* To give a model web search as a tool, pass `keenable::tools()` to your chat completions client and run each call with `client.run_tool_call(name, arguments).await`. See [Tool calling](https://docs.keenable.ai/tool-calling.md).
* The crate re-exports `reqwest`, so you can build a `HeaderMap` or a `ClientBuilder` without adding it yourself.
* Monitors and webhook verification arrived in version 0.2.0. To see what the version you installed includes, read the [Rust changelog](https://github.com/keenableai/keenable-sdk/blob/main/rust/CHANGELOG.md).
* Source and package: [README](https://github.com/keenableai/keenable-sdk/blob/main/rust/README.md), [crates.io](https://crates.io/crates/keenable).


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