API reference
Search API reference
Search the web with POST /v1/search: ranked results with titles, URLs and snippets, filtered by site, excluded domains, publish date or index date.
POST
Search the web and get back ranked results with titles, URLs and snippets.
The API reference covers the base URL, authentication and the limits both endpoints share.
Prefer the official SDKs (
The public endpoint requires an
For example, at request time
You see 5 titles and URLs, none on
The URL length caps a GET at roughly a few hundred hosts. A longer URL is refused before it reaches the API, with an HTTP error (typically
A value that isn’t an array of strings returns
You see up to 3 titles and URLs. Each page contains
pip install keenable, npm install keenable, cargo add keenable, or the Go module). They read KEENABLE_API_KEY from the environment and return a citable to_context() block. For raw HTTP, use the curl tab.
Without a key
POST /v1/search/public takes the same body and returns the same shape, with no API key:
X-Keenable-Title header with your application’s name. If the header is missing, the API returns 400 with Missing app identifier. If you call without a key, Keenable limits requests per IP address and charges nothing. See Authentication. The playground on this page calls the keyed endpoint.
Request
Send a JSON object with the headerContent-Type: application/json. Only query is required. A parameter that isn’t listed here returns 400 with Unknown parameter(s) and the list of supported parameters. When the name is close to a supported one, the error says which one you meant. See 400 Invalid request parameters.
What to search for. The index is semantic, so describe the page you want in plain language (
blog post comparing React and Vue performance) rather than stacking keywords.The query also takes operators: a quoted phrase for exact wording, site: for one or more sites, and - to leave out a word, a phrase or a site. See Search operators.If query is empty or missing, the API returns 400 with "query" is required. If it isn’t a string, the message is "query": must be a string.How hard to search. Each mode is billed as its own SKU. See Balance and usage.
pro: deeper retrieval and the best ranking. Billed assearch.pro.realtime: the fastest response, for latency-sensitive agent loops. Billed assearch.realtime.
400 with "mode": is not a supported search mode; use "pro" or "realtime".Return results from one site only. Subdomains are included (
python.org also matches docs.python.org), a leading www. is ignored, and a path narrows further (github.com/microsoft).To search several sites in one request, put site: operators in query instead. See Search operators. To leave sites out, use exclude_domains.Never return results from these hosts. Each entry is a host name such as
pinterest.com, and it also excludes every subdomain. To exclude a whole public suffix, write it with a leading dot: .gov. Up to 1,000 distinct entries. An empty array or null is the same as leaving it out. Results from excluded hosts are dropped, so fewer than max_results can come back.An entry Keenable can’t read as a host, such as a path (un.org/press) or a wildcard on a host (*.un.org), returns 400 with invalid_filter. See Exclude domains for the clean-up rules, the limits and the error.Keep pages published at or after this point. This is the filter for recent results. If you set it, the results leave out pages with no known publish date. Takes a date, a timestamp or a relative delta such as
7d; see Date and time filters.If Keenable can’t parse the value, the API returns 400, for example Invalid published_after value "last week": value must not contain whitespace.Keep pages published at or before this point. Same formats as
published_after; combine the two for a window.Keep pages Keenable indexed at or after this point, whatever their publish date. Use it to find pages that are new to the index. Same formats as
published_after.Search the index as it stood at this moment: pages acquired after it are excluded. It sets no lower bound, so it isn’t a recency filter. Use
published_after for recent results.Takes a timestamp, a date (a date resolves to 00:00:00 UTC, not to the end of the day), a Unix epoch as a string, or a relative delta such as 7d, which means 7 days before the request time. Relative deltas in the other filters still count back from the request time. See Point-in-time search.How many results to return, from
1 to 50. Fewer come back if fewer pages match. A value outside that range returns 400 with "max_results": must be an integer between 1 and 50.Cap on the characters of page text in each result’s
snippet, from 180 to 10000. Without it, snippets often run to several thousand characters, so set it if you only need enough text to rank or cite. See Size search results. A value outside that range returns 400 with "snippet_max_length": must be an integer between 180 and 10000.Set to
true to leave cards out of the results. A card is a result Keenable writes itself for queries such as prices, exchange rates or facts about a company, served at a URL like https://cards.keenable.ai/w/<id>. A card URL works for one day. With disable_cards, ordinary web pages take the place of cards, so you still get the same number of results.Safe search. One of
off, moderate or strict. With off, or when you leave it out, results are not filtered. With moderate or strict, results that a safety model judges unsafe at that level are removed. strict removes more than moderate. Removed results are not replaced, so a query can return fewer than max_results results, or none.Filtering works only with mode set to pro (the default) or realtime. In any other mode, moderate and strict return 400 with code invalid_parameter. The same happens when you also set disable_cards to true, when query is a URL that is fetched as is (a URL query with a non-empty exclude_domains list is searched and can be filtered), and on Time Machine search. Any other value, including null and an empty string, also returns 400 with code invalid_parameter. A request never comes back unfiltered when it asks for moderate or strict: it is filtered or it fails.What this search is for, in two or three plain sentences with no field labels. Say which facts a useful page must contain, what the query leaves out (who, where, when, the date window), which kinds of sources count or must be excluded, what you already know and what is still unknown. Don’t paste the conversation. At most 5,000 characters; an empty string counts as not sent.Keenable validates and logs
objective. It doesn’t change the results or the price yet. A value over 5,000 characters returns 400 with invalid_parameter. A GET request takes it as a query parameter. Organizations with zero data retention have it left out of the logs.Your own ID for grouping related requests, up to 128 characters. You can send it as the
X-Keenable-Session-Id header instead. If you send both, the header wins.Response
A200 returns the search and its ranked results. Fields marked required are always present; the others are left out when Keenable doesn’t know them.
The matching pages, best match first, at most
max_results of them. Search is semantic and returns the closest pages it has even for an unusual query, so judge relevance from title and snippet rather than expecting an empty list.Present if the request wasn’t answered as a plain search. If
query was a URL, Keenable fetched that page instead. With exclude_domains set, Keenable searches a URL query like any other query, so the list applies to it. If query had only site: operators, Keenable searched for the site name.What the call was billed. Present on successful calls made with a key. The public endpoint leaves it out. See Balance and usage.
Errors
Every error has the same JSON shape, with a shorterror and a message that says what to change:
The body also has a stable
code, a fix and retryable. Branch on code. Every status and code, with its exact message and fix, is on Errors.
Date and time filters
acquired_after, acquired_before, published_after, and published_before each accept one of the following formats:
- Date in RFC 3339
full-dateform (YYYY-MM-DD): covers that whole day in UTC. On an_afterbound it resolves to00:00:00on that date; on a_beforebound it resolves to23:59:59.999on that date, so pages from the named day are kept at either end. Pass a timestamp instead to cut at an exact instant. - Timestamp in ISO 8601 form (
YYYY-MM-DDTHH:MM:SS[.sss][±HH:MM]). If you leave out the timezone offset, Keenable reads the timestamp as UTC. - Relative delta (
<number><unit>, such as7dor30min): resolves to the request time minus the delta, truncated to minute precision, even whenquery_timeis set. Supported units:min(minutes),h(hours),d(days),w(weeks),mo(30 days),y(365 days).
You can mix relative deltas and absolute values across the two bounds of a window. Both of these bodies are valid:
2026-05-18T14:23:45Z, acquired_after: "2h" resolves to 2026-05-18T12:23:00Z. The results drop a page acquired at 12:22:59Z and keep one acquired at 12:23:00Z.
Mind the difference between a date and a timestamp on a _before bound: acquired_before: "2026-05-01" keeps a page acquired at 2026-05-01T14:31:13Z, while acquired_before: "2026-05-01T00:00:00Z" drops it. Use the date form to mean “up to and including that day”, and the timestamp form to cut at midnight.
Exclude domains
exclude_domains keeps results from the hosts you list out of a search. Use site to search one site, and exclude_domains to leave sites out of an open search.
This sample searches without pinterest.com and quora.com, and prints the top 5 results. The TypeScript sample needs SDK 0.1.5 or later, because version 0.1.4 ignores excludeDomains and returns unfiltered results:
pinterest.com, quora.com or their subdomains.
What an entry matches
Each entry is a host. It excludes that host and every subdomain:yahoo.com also excludes finance.yahoo.com, and blogs.un.org excludes only blogs.un.org and its subdomains, not un.org. Hosting domains on the private part of the Public Suffix List, such as github.io and blogspot.com, are accepted as hosts.
To exclude every host under a public suffix, write the suffix with a leading dot. .gov excludes nasa.gov, www.irs.gov and every other host that ends in .gov. *.gov means the same. The suffix must be on the Public Suffix List: .co.uk works, .example doesn’t. A suffix covers only the hosts under it. .gov doesn’t exclude gov.uk, which sits under .uk, so write .gov.uk for that. A bare gov or com is rejected, so a mistyped host can’t exclude a whole top-level domain.
Keenable cleans up these slips and uses the host that is left:
- whitespace around the entry and upper case
- an
http://orhttps://scheme - a port, a trailing
/, a trailing dot, and a?queryor#fragmentwith no path - a leading
www., unless the rest is a public suffix:www.github.iostays as it is - an internationalized name, which becomes punycode:
bücher.debecomesxn--bcher-kva.de - duplicates, after the clean-up
https://WWW.UN.org/ becomes un.org.
Keenable rejects these entries with 400 invalid_filter:
Limits
A list over any limit returns
400 invalid_filter. A suffix such as .gov counts as one entry, the same as a host, so one entry can cover thousands of sites. Duplicates and entries that clean up to the same host count once, so a list of 2,000 entries is valid when it has at most 1,000 different ones.
GET requests
GET /v1/search reads exclude_domains from the query string. Repeat the parameter, separate the entries with commas, or both:
431) and no JSON body. Send a long list as a JSON array in a POST body.
The API reads only the first 1,000 query parameters. If exclude_domains comes after them, the request returns 400 with the code invalid_request instead of searching without it.
Rejected entries
A rejected entry or list returns400. error is invalid_filter, the code is invalid_parameter, and three fields say what to fix:
This request sends a path:
400 with "exclude_domains": must be an array of strings instead.
With other filters
exclude_domains applies on top of every other filter. Combined with site, it removes hosts inside that site: site: "un.org" with exclude_domains: ["blogs.un.org"] returns pages from un.org and its subdomains except blogs.un.org. If exclude_domains covers the whole site, no results come back.
Search operators
Operators inquery turn part of a search into a hard filter: an exact phrase, a set of sites, or something to leave out. The rest of the query stays a plain-language description that Keenable ranks by meaning. Operators work in both modes and on the keyless path. For worked queries and the mistakes that return 400, see the Search operators guide.
A word with no operator is never a hard filter, and
OR between two plain words doesn’t make them one: both stay descriptions that Keenable ranks by. To require exact wording, put it in quotes.
This request finds pages that contain the exact error string and leaves out one site:
other side closed, and none is on github.com.
Rules that change the results:
- Write
ORandNOTin capitals. In lower case they’re ordinary words. ORbinds only the terms next to it.keyboard reviews site:wired.com OR site:theverge.comsearches both sites forkeyboard reviews.- Attach
-to its term, with no space after it:-site:reddit.com,-"sponsored post". - Two
site:terms with noORbetween them still mean either site. A page is on one site, so Keenable never requires both. - Put every site filter in one place. Use the
siteparameter for one site, orsite:operators inqueryfor several sites and exclusions. Don’t combine thesiteparameter with-site:in the query. To leave hosts out of one site, sendexclude_domainswithsite. - A query that doesn’t parse never fails. An unbalanced quote or parenthesis, a dangling
ORorNOT, or a-on its own is read as plain words, and the search still runs.