Search

Search the web and return ranked results

POST /v1/search

Search

cURL

curl --request POST \
  --url https://api.keenable.ai/v1/search \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "query": "<string>",
  "site": "<string>",
  "acquired_after": "<string>",
  "acquired_before": "<string>",
  "published_after": "<string>",
  "published_before": "<string>",
  "query_time": "<string>",
  "snippet_max_length": 123,
  "max_results": 123
}
'

200

{
  "query": "<string>",
  "results": [
    {
      "title": "<string>",
      "url": "<string>",
      "description": "<string>",
      "snippet": "<string>",
      "published_at": "<string>",
      "acquired_at": "<string>"
    }
  ]
}

Search the web and return ranked results with URLs, titles, and descriptions.

Part of the API reference, which covers the base URL, authentication, and the limits both endpoints share.

curl

curl -X POST "https://api.keenable.ai/v1/search" \
  -H "X-API-Key: keen_<your_key>" \
  -H "Content-Type: application/json" \
  -d '{ "query": "typescript best practices" }'

Without a key

POST /v1/search/public takes the same body and returns the same shape, with no API key:

curl -X POST "https://api.keenable.ai/v1/search/public" \
  -H "X-Keenable-Title: My App" \
  -H "Content-Type: application/json" \
  -d '{ "query": "typescript best practices" }'

X-Keenable-Title names your application and is required on the public endpoint; without it the request is rejected with 400 Missing app identifier. Keyless calls are rate limited per IP and consume no credits — see Authentication for the details. The playground on this page calls the keyed endpoint.

Request

query · string · required

The search query.

site · string

Restrict results to a specific site (e.g. "techcrunch.com").

acquired_after · string

Filter to pages acquired/indexed at or after this point in time. See Date and time filters for accepted formats.

acquired_before · string

Filter to pages acquired/indexed at or before this point in time. See Date and time filters for accepted formats.

published_after · string

Filter to pages published at or after this point in time. See Date and time filters for accepted formats.

published_before · string

Filter to pages published at or before this point in time. See Date and time filters for accepted formats.

query_time · string

Search the index as it stood at this point in time: pages acquired after it are excluded. Accepts a timestamp or a date (a date resolves to 00:00:00 UTC, not to the end of the day). Also re-bases relative deltas — see Point-in-time search.

snippet_max_length · integer

Maximum length, in characters, of the snippet returned per result. Must be between 180 and 10000. When omitted, a default snippet length is used.

max_results · integer

Maximum number of results to return. Must be between 1 and 50. When omitted, up to 10 results are returned.

Response

query · string

The query that was searched.

results · array

List of search results.

Show result

title · string

Page title.

url · string

Page URL.

description · string

Short summary of the page.

snippet · string

Longer text excerpt from the page content (if available).

published_at · string

When the page was published, as an ISO 8601 timestamp in UTC (if available).

acquired_at · string

When the page was acquired/indexed, as an ISO 8601 timestamp in UTC (if available).

Example

{
  "query": "typescript best practices",
  "results": [
    {
      "title": "TypeScript Best Practices 2026",
      "url": "https://example.com/ts-best-practices",
      "description": "A comprehensive guide to modern TypeScript patterns and best practices.",
      "snippet": "TypeScript Best Practices 2026 Use strict mode, prefer interfaces over type aliases for object shapes...",
      "published_at": "2026-01-15T10:30:00Z",
      "acquired_at": "2026-01-16T08:12:34Z"
    }
  ]
}

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]). When a timezone offset is not provided, the timezone is interpreted as UTC.
• Relative delta (<number><unit>, e.g. 7d, 30min) — resolves to the request time minus the delta, truncated to minute precision, or to query_time minus the delta when that is set. Supported units: min (minutes), h (hours), d (days), mo (months), y (years).

Example values:

Value	Resolves to
2026-01-15 on acquired_after / published_after	2026-01-15T00:00:00Z
2026-01-15 on acquired_before / published_before	2026-01-15T23:59:59.999Z
2026-01-15T10:30:00	2026-01-15T10:30:00Z (no offset → UTC)
2026-01-15T10:30:00Z	2026-01-15T10:30:00Z
2026-01-15T10:30:00.500-05:00	2026-01-15T15:30:00.500Z
7d	7 days before request time, truncated to the minute
30min	30 minutes before request time, truncated to the minute

Relative deltas may be combined with absolute values across the two bounds of a window:

{
  "query": "...",
  "published_after": "1y",
  "published_before": "6mo"
}

{
  "query": "...",
  "acquired_after": "2024-01-01",
  "acquired_before": "30d"
}

For example, at request time 2026-05-18T14:23:45Z, acquired_after: "2h" resolves to 2026-05-18T12:23:00Z — a document acquired at 12:22:59Z is dropped, one acquired at 12:23:00Z is kept.

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.