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

# Keenable glossary

> Definitions of the terms you meet when you build on Keenable, from snippet, card and acquired_at to x402, MCP, monitor runs and webhook signatures.

Look up a term from the Keenable API, the MCP server or Monitors, then follow its link to the page with the detail.

## Fields in a search response

This request runs one search with your API key and asks for a single short result:

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
curl -X POST "https://api.keenable.ai/v1/search" \
  -H "X-API-Key: $KEENABLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "open-weights LLM release", "max_results": 1, "snippet_max_length": 180 }'
```

You get a response in this shape. The comments name the glossary term for each field, and the values are examples:

```jsonc theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
{
  "query": "open-weights LLM release",   // the query you sent, unchanged
  "mode": "pro",                          // mode: the mode that served the call
  "results": [
    {
      "title": "Example Labs releases a 70B open-weights model",
      "url": "https://example.com/news/example-70b",   // a card URL starts with https://cards.keenable.ai/w/
      "description": "",                               // deprecated, always empty: read snippet
      "snippet": "Example Labs published the weights of its 70B model under an open license on Monday...",  // snippet
      "published_at": "2026-11-16T00:00:00Z",          // published_at: when the page was published
      "acquired_at": "2026-11-16T09:12:44Z"            // acquired_at: when Keenable indexed the page
    }
  ],
  "usage": {                  // usage: only on successful calls made with an API key
    "sku": "search.pro",      // SKU: what the call was billed as
    "amount": 1,
    "credits": 1,             // credit: one credit is $0.004
    "paid": false,            // false: the call came from the monthly allowance
    "credits_remaining": 99999
  }
}
```

The response headers carry `X-Request-Id`. A keyless call to `/v1/search/public` returns the same shape without `usage`. See the [Search response](https://docs.keenable.ai/api-reference/search.md#response) for every field.

## Search and fetch

| Term | Meaning | Detail |
| - | - | - |
| Search | `POST /v1/search` returns ranked web pages for a query, best match first, from 1 to 50 results. | [Search](https://docs.keenable.ai/products/search.md) |
| Result | One ranked page in `results`, with `title`, `url` and, when Keenable knows them, `snippet`, `published_at` and `acquired_at`. | [Search response](https://docs.keenable.ai/api-reference/search.md#response) |
| `snippet` | Text from the page, chosen for the query, in markdown. It can start or end mid-sentence, and `snippet_max_length` caps it at 180 to 10,000 characters. | [Search response](https://docs.keenable.ai/api-reference/search.md#response) |
| Card | A result that Keenable writes itself for queries such as prices, exchange rates or facts about a company. Its URL starts with `https://cards.keenable.ai/w/` and works for one day. Send `disable_cards: true` to get web pages in its place. | [Search request](https://docs.keenable.ai/api-reference/search.md#request) |
| `published_at` | When the page was published, as an ISO 8601 timestamp in UTC. The field is left out when the publish date is unknown. | [Search response](https://docs.keenable.ai/api-reference/search.md#response) |
| `acquired_at` | When Keenable indexed the page. Use it to judge how fresh the `snippet` is. | [Search response](https://docs.keenable.ai/api-reference/search.md#response) |
| `published_after`, `published_before` | Filters that keep pages published inside a window. `published_after` is the filter for recent results, and it leaves out pages with no known publish date. | [Date and time filters](https://docs.keenable.ai/api-reference/search.md#date-and-time-filters) |
| `acquired_after`, `acquired_before` | Filters on the time Keenable indexed a page, whatever its publish date. Use `acquired_after` to find pages that are new to the index. | [Search request](https://docs.keenable.ai/api-reference/search.md#request) |
| `query_time` | Searches the index as it stood at that moment, so pages acquired later are left out. It sets no lower bound and isn't a recency filter. | [Point-in-time search](https://docs.keenable.ai/mcp-server.md#point-in-time-search) |
| Mode | How hard a search works: `pro`, the default, does deeper retrieval, and `realtime` returns the fastest response. Each mode is billed as its own SKU. | [Search request](https://docs.keenable.ai/api-reference/search.md#request) |
| Search operators | A quoted phrase for exact wording, `site:` for one or more sites, and `-` to leave out a word, a phrase or a site, written inside `query`. | [Search operators](https://docs.keenable.ai/api-reference/search.md#search-operators) |
| `exclude_domains` | Hosts that never appear in the results, with their subdomains. A leading dot, such as `.gov`, excludes a whole public suffix. | [Exclude domains](https://docs.keenable.ai/api-reference/search.md#exclude-domains) |
| Fetch | `GET /v1/fetch` returns one page as markdown in `content`, with navigation and boilerplate stripped. | [Fetch](https://docs.keenable.ai/products/fetch.md) |
| Live fetch | A fetch made from the source page instead of Keenable's indexed copy, billed as `fetch.live`. Send `live=true` to ask for one. Keenable also fetches live when it has no indexed copy. | [Fetch gotchas](https://docs.keenable.ai/products/fetch.md#gotchas) |
| Fetch `prompt` | An instruction of at most 2,000 characters. A model reads the page, and `content` holds only its answer. | [Fetch request](https://docs.keenable.ai/api-reference/fetch.md) |
| `max_chars` | The cap on the characters of fetched `content`, 50,000 by default. Cut content sets `truncated` to `true`, and `total_chars` gives the full length. | [Fetch request](https://docs.keenable.ai/api-reference/fetch.md) |
| `session_id` | Your own ID, up to 128 characters, that groups the requests of one agent session. Send the same value on every call, or send the `X-Keenable-Session-Id` header. | [Search request](https://docs.keenable.ai/api-reference/search.md#request) |

## Access and billing

| Term | Meaning | Detail |
| - | - | - |
| Keyless tier | Calls with no API key, on the `/public` paths or the MCP server. They are free, rate limited per IP address for each endpoint, and return no `usage`. | [Rate limits](https://docs.keenable.ai/rate-limits.md) |
| `X-Keenable-Title` | The header that names your application on a keyless `/public` call. Without it, the API returns `400` with `Missing app identifier`. | [API authentication](https://docs.keenable.ai/api-reference.md#authentication) |
| API key | A key that starts with `keen_`, sent in the `X-API-Key` header or as `Authorization: Bearer`. It belongs to your organization and never expires on its own. | [API keys](https://docs.keenable.ai/api-keys.md) |
| Organization | The account that owns your API keys. All its keys share one per-second rate limit. | [Rate limits](https://docs.keenable.ai/rate-limits.md) |
| Device login | A sign-in for tools that can't show a sign-in page, following RFC 8628. Your tool requests a code, a person approves it in the console, and your tool collects a new API key. `keenable login` uses it. | [Device login](https://docs.keenable.ai/authentication.md#device-login) |
| Monthly allowance | The free requests each month that an organization gets with an API key. Keenable uses it before your prepaid balance. | [Monthly allowance](https://docs.keenable.ai/credits.md#monthly-allowance) |
| `usage` | The object on each successful keyed response that says what the call was billed: `sku`, `amount`, `credits`, `paid` and `credits_remaining`. | [Reading usage per call](https://docs.keenable.ai/credits.md#reading-usage-per-call) |
| Credit | The unit `usage.credits` reports. One credit is \$0.004, so a call at \$4 per 1,000 costs 1 credit. | [Pricing](https://docs.keenable.ai/pricing.md) |
| SKU | The name a call is billed under: `search.pro`, `search.realtime`, `fetch` or `fetch.live`. | [What each call costs](https://docs.keenable.ai/pricing.md#what-each-call-costs) |
| Auto top-up | A setting that charges your saved card when your prepaid balance falls below a threshold you set. It is off until you turn it on. | [Auto top-up](https://docs.keenable.ai/auto-top-up.md) |
| `X-Request-Id` | The response header that identifies one request. Include it when you report a problem, so support can find the request in the logs. | [What to include](https://docs.keenable.ai/help.md#what-to-include) |
| `Retry-After` | The header on a `429` that says how many seconds to wait before you retry. | [When you hit a limit](https://docs.keenable.ai/rate-limits.md#when-you-hit-a-limit) |
| x402 | An open payment protocol built on HTTP `402 Payment Required`. An agent with a wallet pays for each search or fetch in USDC on Base on the `/v1/x402/*` paths, with no account. | [Pay per request](https://docs.keenable.ai/pay-per-request.md) |
| ZeroClick | A storefront where an agent with no account buys a prepaid balance and spends it on searches and fetches. | [Prepaid credits through ZeroClick](https://docs.keenable.ai/pay-per-request.md#prepaid-credits-through-zeroclick) |
| Zero data retention (ZDR) | A data retention policy that Keenable sets for an organization. It follows the API key, and a fetch with a `prompt` returns `400` with `zdr_prompt_unsupported` under it. | [Zero data retention](https://docs.keenable.ai/security.md#zero-data-retention) |

## MCP, agents and crawlers

| Term | Meaning | Detail |
| - | - | - |
| MCP | The Model Context Protocol, the way agent clients such as Claude Code and Cursor discover and call tools. The Keenable MCP server at `https://api.keenable.ai/mcp` gives an agent the `search_web_pages` and `fetch_page_content` tools. | [MCP server](https://docs.keenable.ai/mcp-server.md) |
| Streamable HTTP | The MCP transport that the remote Keenable server speaks. In a config file it is usually `"type": "http"`, and in Cline it is `"type": "streamableHttp"`. | [Other MCP clients](https://docs.keenable.ai/mcp-server.md#other-mcp-clients) |
| MCP URLs | `/mcp` takes no key or an API key, `/mcp-oauth` is for clients that sign in through a browser, and `/mcp-public` publishes no OAuth discovery metadata. All three serve the same web tools. | [Which URL to use](https://docs.keenable.ai/mcp-server.md#which-url-to-use) |
| Local bridge | The `@keenable/mcp` package, which runs as a local stdio server and forwards calls with your API key. Clients that accept only local servers, such as Claude Desktop, need it. | [Local bridge](https://docs.keenable.ai/mcp-server.md#local-bridge-with-an-api-key) |
| Agent skill | The `keenable-web-search` skill: instructions and one Python script that let an agent search without an MCP client or an API key. | [Agent skill](https://docs.keenable.ai/agent-skill.md) |
| SELECT | A separate MCP server that needs a Keenable account. Your agent writes one read-only SQL `SELECT`, and the server returns a table built from live web pages. | [SELECT](https://docs.keenable.ai/select.md) |
| Result set | The stored output of a SELECT query, with an id that a later query can put in `FROM` to read the rows again without new searches. | [Result sets](https://docs.keenable.ai/select.md#result-sets) |
| KeenableBot | The crawler that collects public pages for the Keenable index. It follows `robots.txt`. | [Keenable crawlers](https://docs.keenable.ai/crawlers.md) |
| Keenable-User | The user agent of a request made for a person or agent who asked for one page, such as a live fetch. It doesn't crawl. | [Keenable crawlers](https://docs.keenable.ai/crawlers.md#user-agents) |

## Monitors

| Term | Meaning | Detail |
| - | - | - |
| Monitor | A standing query on a topic. Keenable checks every page it crawls against your monitors and keeps the pages that report something new. It needs an API key. | [Monitors](https://docs.keenable.ai/products/monitors) |
| Monitor result | A page a monitor kept, with the fields of a search result plus `summary`, `importance` and `matched_at`. | [Read the results](https://docs.keenable.ai/products/monitors#read-the-results) |
| `importance` | How much a result matters for the monitor's topic, from 1 to 5. A monitor doesn't accept pages under 3. | [Read the results](https://docs.keenable.ai/products/monitors#read-the-results) |
| Schedule | When a monitor runs: a `cron` expression, an `interval` such as `6h`, or `once`. A monitor runs at most once an hour. | [Schedules](https://docs.keenable.ai/products/monitors#schedules) |
| Run | One scheduled or triggered pass that returns the results found since the previous run, most important first. | [What a run returns](https://docs.keenable.ai/products/monitors#what-a-run-returns) |
| Webhook event | A JSON body with `id`, `type`, `created_at`, `data` and `metadata` that Keenable posts to your webhook. `monitor.result.found` carries one new page minutes after it was crawled. | [Webhook events](https://docs.keenable.ai/products/monitors#webhook-events) |
| Delivery | One webhook event sent to your endpoint, with its attempts and last error. A failed delivery is retried with backoff. | [List deliveries](https://docs.keenable.ai/api-reference/monitors/deliveries.md) |
| Webhook signature | An HMAC-SHA256 signature in the `webhook-signature` header, made with the monitor's `webhook.secret` under the Standard Webhooks scheme. Check it on the raw body before you parse it. | [Verify a webhook](https://docs.keenable.ai/products/monitors#verify-a-webhook) |

For short answers to common questions, see the [FAQ](https://docs.keenable.ai/faq.md).


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