Search the index for one topic, or up to five

When the index has fewer than 3 good matches for a single query, discovery looks for sources beyond it within a time budget (3 s in normal, 8 s in deep; ultra and fast add at most 0.8 s: the open news index and one relevance check, the rest keeps learning in the background): outlets proposed by a topic model and by an open news index, read at the original site with robots.txt respected and judged by the same relevance model; in deep, also the search that those sites declare, with a topic keyword. Discovered results come with found_in: discovery; discovery says what it did and incomplete whether the time ran out. With stream: true, index results arrive first and discovered ones in later partial events. Open news index built from the GDELT Project (gdeltproject.org).

post/v1/search

Request

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

Request body

indexstring

Search your own custom index (idx_…, see /v1/indexes) instead of the news index: the same modes, prices, questions and tone. One query per request; no date filter unless you pass days or dates.

sourcesstring[]

Only these index sources, by domain, such as example.com.

include_domainsstring[]

Only these domains or paths. A domain includes its subdomains.

exclude_domainsstring[]

Never these domains or paths.

countriesstring[]

Only sources from these countries: ISO 3166-1 alpha-2 codes, such as AR or US.

languagesstring[]

Only sources that publish in these languages: ISO 639-1 codes, such as es or en (a BCP 47 tag such as pt-BR counts as pt).

sectionsstring[]

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

daysinteger nullable

The last N days; null for the whole index. Defaults to 7 unless dates are given.

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 while it searches: step, partial, result.

Response

The result; 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.