Search a live site for a topic

Can take up to a minute: returns a job (202) to poll at /v1/jobs/{id}, or server-sent events with stream: true.

post/v1/search/site

Request

  • Base URL: https://api.typesearch.ai
  • URL: https://api.typesearch.ai/v1/search/site
  • Auth: one of:
    • HTTP bearer
    • API key in header x-api-key

Request body

sitestring required

The live site to search, such as example.com.

querystring required
sectionsstring[]

Only these sections: the section in the feed, or the start of the URL path.

exclude_domainsstring[]

Never these domains or paths.

mode'ultra' | 'fast' | 'normal' | 'deep'

ultra: headlines only, the cheapest · fast: headlines and standfirsts · normal: reads the best matches · deep: more headlines, the topic also in other words (synonyms and acronyms), twice the reading, snippets and the essentials of each article, and the search of the sites that cover the topic when the index falls short.

max_resultsinteger
highlightsboolean

Very short verbatim excerpts (up to 25 words, never from the first paragraph) from the articles that were read: one per article, two in deep mode. On by default only in deep mode.

dedupeboolean

Groups the same story reported by several outlets.

toneboolean

Tone toward the query: positive, neutral or negative.

essentialboolean

The essentials: very short verbatim excerpts across several articles. On by default only in deep mode.

questionsobject

Structured output: typed questions (boolean, choice, score) that the model answers for each result.

max_tokensinteger nullable

Cap on model tokens. If it is reached, the response comes back with incomplete: true.

freshboolean

Skips the result cache (10 minutes).

temporal'auto' | 'off'

auto: a date in the query («today», «yesterday», «tomorrow», «on September 22», «this week») is taken out of the topic, sets the publication window (unless published_after/before are given; days only bounds it) and puts the results from that day first · off: the query is taken literally.

timezonestring

IANA time zone that decides what day «today» is. Defaults to Argentina (America/Argentina/Buenos_Aires).

streamboolean

Server-sent events instead of an asynchronous job.

Response

With stream: true, server-sent events.

idstring required
object'search' | 'site_search' | 'similar' required
mode'ultra' | 'fast' | 'normal' | 'deep' required
queriesstring[] required
foundboolean required
totalinteger required
sitestring nullable required
incompleteboolean required

The token cap (max_tokens) or the discovery time budget ran out: there may be more.

cached_atstring nullable required

Changes

No recorded changes to this operation across all 1 revision of this API.