Find similar

POSThttps://api.typesearch.ai/v1/similar

Reads the article at url and searches the index for others about the same story. The response has the same shape as POST /v1/search, with the reference article in reference.

Body

urlurirequired
The reference article: a full URL. Results are other articles about the same story.
sourcesstring[]
Only these sources, by domain (such as diarioejemplo.example), up to 100. A domain that is not in the index comes back as a domain_not_indexed warning.
Items: up to 100
include_domainsstring[]
Only these domains or paths, up to 20. A domain includes its subdomains; a path such as diarioejemplo.example/economia includes everything under it.
Items: up to 20
exclude_domainsstring[]
Never these domains or paths, up to 20. Same matching rules as include_domains.
Items: up to 20
countriesstring[]
Only sources based in these countries: ISO 3166-1 alpha-2 codes, such as AR or US.
Items: up to 50
languagesstring[]
Only sources that publish in these languages: ISO 639-1 codes, such as es or en. A tag such as pt-BR counts as pt.
Items: up to 20
sectionsstring[]
Only these sections: the section the source declares, or the first segment of the path (economia).
Items: up to 20
daysinteger | null
The last N days, 1–365. null searches the whole index. Defaults to 7, unless published_after or published_before is set.
Range: 1–365
published_afterdate | date-time
Published on or after this moment. A bare date (2026-09-20) covers the whole day in UTC−3; a date-time needs an offset.
published_beforedate | date-time
Published on or before this moment, inclusive. Same format as published_after.
modeenum<string>Default: "normal"
ultra judges headlines only and is the cheapest · fast judges headlines and standfirsts · normal also reads the top results to confirm them · deep judges the whole index and reads more.
max_resultsintegerDefault: 10
How many results to return, 1–50.
Range: 1–50
highlightsboolean
Return a short verbatim excerpt from the articles that were read: at most one per article (two in deep), up to 25 words, never from the first paragraph. Defaults to true in deep and false otherwise.
dedupebooleanDefault: false
Collapse the same story told by several outlets into a single result, listing the others in duplicates.
tonebooleanDefault: false
Classify each result as positive, neutral or negative relative to the query, and summarise it by source.
essentialboolean
Return up to three verbatim excerpts from different sources that capture the story, with the same limits as highlights. Defaults to true in deep.
questionsmap<string, …>
Structured output: up to 8 typed questions (boolean, choice or score) answered on every result, keyed by a name you choose.
max_tokensinteger | null
A hard cap on model tokens for this request, minimum 2000. If it is reached, you get everything judged so far with incomplete: true.
Range: 2000–9007199254740991
freshbooleanDefault: false
Skip the result cache. Otherwise, an identical request within 10 minutes is served from cache at no cost.
temporalenum<string>Default: "auto"
One of: auto · off
timezonestring

Response

The same fields as POST /v1/search, with object: "similar" and reference set.

const res = await ts.similar('https://diarioejemplo.example/economia/…', {
  mode: 'fast',
  exclude_domains: ['diarioejemplo.example'],
});

200 OK

{
  "id": "req_Wn7cK2pXq9Ld",
  "object": "similar",
  "mode": "fast",
  "reference": {
    "url": "https://diarioejemplo.example/economia/…",
    "title": "Inflación: qué esperan los analistas para los próximos meses"
  },
  "found": true,
  "total": 9,
  "results": [
    {
      "url": "https://plaza.example/economia/…",
      "title": "Relevamiento de expectativas: las proyecciones de precios",
      "source": "Plaza Financiera",
      "score": 0.91,
      "found_in": "index"
    }
  ]
}