Skip to main content
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 (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:
The public endpoint requires an 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 header Content-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.
string
required
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.
string
default:"pro"
How hard to search. Each mode is billed as its own SKU. See Balance and usage.
  • pro: deeper retrieval and the best ranking. Billed as search.pro.
  • realtime: the fastest response, for latency-sensitive agent loops. Billed as search.realtime.
Any other value returns 400 with "mode": is not a supported search mode; use "pro" or "realtime".
string
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.
array of strings
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.
string
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.
string
Keep pages published at or before this point. Same formats as published_after; combine the two for a window.
string
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.
string
Keep pages Keenable indexed at or before this point. Same formats as published_after.
string
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.
integer
default:"10"
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.
integer
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.
boolean
default:"false"
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.
string
default:"off"
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.
string
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.
string
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

A 200 returns the search and its ranked results. Fields marked required are always present; the others are left out when Keenable doesn’t know them.
string
required
The query you sent, unchanged.
string
required
The mode that served the request: pro or realtime.
array of objects
required
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.
string
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.
object
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 short error 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-date form (YYYY-MM-DD): covers that whole day in UTC. On an _after bound it resolves to 00:00:00 on that date; on a _before bound it resolves to 23:59:59.999 on 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 as 7d or 30min): resolves to the request time minus the delta, truncated to minute precision, even when query_time is set. Supported units: min (minutes), h (hours), d (days), w (weeks), mo (30 days), y (365 days).
Example values: You can mix relative deltas and absolute values across the two bounds of a window. Both of these bodies are valid:
For example, at request time 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:
You see 5 titles and URLs, none on 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:// or https:// scheme
  • a port, a trailing /, a trailing dot, and a ?query or #fragment with no path
  • a leading www., unless the rest is a public suffix: www.github.io stays as it is
  • an internationalized name, which becomes punycode: bücher.de becomes xn--bcher-kva.de
  • duplicates, after the clean-up
So 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:
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 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 returns 400. error is invalid_filter, the code is invalid_parameter, and three fields say what to fix: This request sends a path:
A value that isn’t an array of strings returns 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 in query 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:
You see up to 3 titles and URLs. Each page contains other side closed, and none is on github.com. Rules that change the results:
  • Write OR and NOT in capitals. In lower case they’re ordinary words.
  • OR binds only the terms next to it. keyboard reviews site:wired.com OR site:theverge.com searches both sites for keyboard reviews.
  • Attach - to its term, with no space after it: -site:reddit.com, -"sponsored post".
  • Two site: terms with no OR between 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 site parameter for one site, or site: operators in query for several sites and exclusions. Don’t combine the site parameter with -site: in the query. To leave hosts out of one site, send exclude_domains with site.
  • A query that doesn’t parse never fails. An unbalanced quote or parenthesis, a dangling OR or NOT, or a - on its own is read as plain words, and the search still runs.