Install
Install the package. The SDK needs Python 3.9 or newer:httpx and httpcore. On macOS and many Linux distributions, system Python refuses a global pip install. If it does, run python3 -m venv .venv and source .venv/bin/activate first.
To see which version you have, run pip show 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 Keenable(), which reads the variable. To pass the key in code, use Keenable(api_key=...). If you pass no api_key and KEENABLE_API_KEY is unset, the client calls the keyless endpoints.
The constructor takes these settings:
Every call also takes
timeout, max_retries and extra_headers as keyword arguments. They override the client’s settings for that call.
Search
This program runs one keyless search and prints the top 3 results as a citable block:main.py
main.py and run python main.py. You see one [n] Title (url) header per result, followed by the page text.
Search filters are keyword arguments:
exclude_domains, published_after, published_before, acquired_after, acquired_before, snippet_max_length, max_results, query_time, objective, disable_cards, 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.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:main.py
Pass the fetch options as keyword arguments:
fetch(url, max_chars=..., live=..., prompt=...). Each one is described under Fetch parameters.
Monitors
Needs SDK 0.2.0 or later. The latest release on PyPI is 0.1.5. 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:
main.py
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.
AsyncKeenable().monitors has the same methods, and you await each one. Its list_all() is an async iterator. 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 PyPI is 0.1.5. 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. Callverify_webhook(payload, headers, secret, *, tolerance=300), imported from keenable. It needs no client and no API key.
Pass the request body exactly as received, as
bytes or str. Parsing and re-encoding the JSON changes the bytes and breaks the signature. 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 Python SDK raises 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:
status_code, code, type, fix, retryable, retry_after_seconds, 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:
main.py
Output
Async
UseAsyncKeenable when your code already runs on asyncio. It takes the same constructor settings as Keenable, and you await its search, fetch and monitors methods. To run a model’s tool call with it, use arun_tool_call in place of run_tool_call.
If you pass your own HTTP client to AsyncKeenable, pass an httpx.AsyncClient. Open the client with async with, or call await client.aclose() when you finish, so the connection pool closes. For a complete program, see Async on the SDKs page.
Notes
- To give a model web search as a tool, pass
TOOLSto your chat completions client and run each call withrun_tool_call. See Tool calling. Keenablekeeps a connection pool. Use it as a context manager, or callclose()when you finish.- Before version 0.2.0, a number passed as
timeoutlimits each httpx phase, such as connecting or one read, not the whole attempt. - Monitors and webhook verification arrived in version 0.2.0. To see what the version you installed includes, read the Python changelog.
- Source and package: README, PyPI.