{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://artifacts.apis.io/typesearch-ai/json-schema/typesearch-ai-search-response-schema.json", "title": "SearchResponse", "x-generated": "2026-10-31", "x-method": "derived", "x-generator": "derive-json-schema.py", "x-source": "openapi/typesearch-ai-api-v1-openapi.json#/components/schemas/SearchResponse", "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "search", "site_search", "similar" ] }, "mode": { "type": "string", "enum": [ "ultra", "fast", "normal", "deep" ] }, "queries": { "type": "array", "items": { "type": "string" } }, "found": { "type": "boolean" }, "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "results": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "title": { "type": "string" }, "source": { "type": [ "string", "null" ] }, "country": { "description": "Country of the source (ISO 3166-1 alpha-2), when known.", "type": [ "string", "null" ] }, "language": { "description": "Language of the source (ISO 639-1), when known: for a source in several languages, the one asked for in `languages`, or its main one.", "type": [ "string", "null" ] }, "published_at": { "type": [ "string", "null" ] }, "section": { "type": [ "string", "null" ] }, "snippet": { "description": "The standfirst or description, as the outlet published it.", "type": [ "string", "null" ] }, "score": { "type": "number", "description": "Probability that the article is about the query: from reading it if it was read, otherwise from its headline." }, "headline_relevance": { "type": "number" }, "read": { "anyOf": [ { "type": "object", "properties": { "probability": { "type": "number" }, "centrality": { "type": "number", "description": "0 not mentioned · 3 main topic." } }, "required": [ "probability", "centrality" ], "additionalProperties": false }, { "type": "null" } ] }, "highlights": { "type": "array", "items": { "type": "string" } }, "tone": { "anyOf": [ { "type": "object", "properties": { "label": { "type": "string", "enum": [ "positive", "neutral", "negative" ] }, "probabilities": { "type": "object", "propertyNames": { "type": "string", "enum": [ "positive", "neutral", "negative" ] }, "additionalProperties": { "type": "number" }, "required": [ "positive", "neutral", "negative" ] }, "basis": { "type": "string", "enum": [ "article", "headline" ] } }, "required": [ "label", "probabilities", "basis" ], "additionalProperties": false }, { "type": "null" } ] }, "answers": { "anyOf": [ { "type": "object", "properties": { "basis": { "type": "string", "enum": [ "article", "headline" ] }, "values": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "boolean" }, "probability": { "type": "number" } }, "required": [ "type", "probability" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "choice" }, "choice": { "type": "string" }, "probabilities": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "number" } }, "confidence": { "type": "number" } }, "required": [ "type", "choice" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "score" }, "score": { "type": "number" }, "probabilities": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "number" } }, "confidence": { "type": "number" } }, "required": [ "type", "score" ], "additionalProperties": false } ] } } }, "required": [ "basis", "values" ], "additionalProperties": false }, { "type": "null" } ] }, "duplicates": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "title": { "type": "string" }, "source": { "type": [ "string", "null" ] } }, "required": [ "url", "title", "source" ], "additionalProperties": false } }, "date_match": { "anyOf": [ { "type": "string", "enum": [ "exact", "adjacent", "unknown", "outside" ] }, { "type": "null" } ], "description": "When the query names a date: whether the article is about that day (exact), the day before or after (adjacent), cannot tell (unknown) or another date (outside). Null otherwise." }, "referenced_date": { "description": "When the query names a date: the day the article is about (YYYY-MM-DD, in the request time zone), from its headline, its publication date or reading it.", "type": [ "string", "null" ] }, "found_in": { "type": "string", "enum": [ "index", "homepage", "section", "site_search", "discovery", "custom_index" ], "description": "Where it was found: the index; a live site (homepage, section, site_search); discovery, a source beyond the index read at the original site for this request; or custom_index, your own index (`index`)." }, "data": { "description": "Custom index: the structured data the page declares about itself (schema.org and Open Graph): price, high_price, currency, availability, brand, sku, gtin, rating, reviews. Null if it declares none.", "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": [ "string", "number" ] } }, { "type": "null" } ] }, "queries": { "description": "With several queries: which ones this result belongs to.", "type": "array", "items": { "type": "string" } } }, "required": [ "url", "title", "source", "country", "language", "published_at", "section", "snippet", "score", "headline_relevance", "read", "highlights", "tone", "answers", "duplicates", "date_match", "referenced_date", "found_in" ], "additionalProperties": false } }, "groups": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "query": { "type": "string" }, "found": { "type": "boolean" }, "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "results": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "title": { "type": "string" }, "source": { "type": [ "string", "null" ] }, "country": { "description": "Country of the source (ISO 3166-1 alpha-2), when known.", "type": [ "string", "null" ] }, "language": { "description": "Language of the source (ISO 639-1), when known: for a source in several languages, the one asked for in `languages`, or its main one.", "type": [ "string", "null" ] }, "published_at": { "type": [ "string", "null" ] }, "section": { "type": [ "string", "null" ] }, "snippet": { "description": "The standfirst or description, as the outlet published it.", "type": [ "string", "null" ] }, "score": { "type": "number", "description": "Probability that the article is about the query: from reading it if it was read, otherwise from its headline." }, "headline_relevance": { "type": "number" }, "read": { "anyOf": [ { "type": "object", "properties": { "probability": { "type": "number" }, "centrality": { "type": "number", "description": "0 not mentioned · 3 main topic." } }, "required": [ "probability", "centrality" ], "additionalProperties": false }, { "type": "null" } ] }, "highlights": { "type": "array", "items": { "type": "string" } }, "tone": { "anyOf": [ { "type": "object", "properties": { "label": { "type": "string", "enum": [ "positive", "neutral", "negative" ] }, "probabilities": { "type": "object", "propertyNames": { "type": "string", "enum": [ "positive", "neutral", "negative" ] }, "additionalProperties": { "type": "number" }, "required": [ "positive", "neutral", "negative" ] }, "basis": { "type": "string", "enum": [ "article", "headline" ] } }, "required": [ "label", "probabilities", "basis" ], "additionalProperties": false }, { "type": "null" } ] }, "answers": { "anyOf": [ { "type": "object", "properties": { "basis": { "type": "string", "enum": [ "article", "headline" ] }, "values": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "boolean" }, "probability": { "type": "number" } }, "required": [ "type", "probability" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "choice" }, "choice": { "type": "string" }, "probabilities": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "number" } }, "confidence": { "type": "number" } }, "required": [ "type", "choice" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "score" }, "score": { "type": "number" }, "probabilities": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "number" } }, "confidence": { "type": "number" } }, "required": [ "type", "score" ], "additionalProperties": false } ] } } }, "required": [ "basis", "values" ], "additionalProperties": false }, { "type": "null" } ] }, "duplicates": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "title": { "type": "string" }, "source": { "type": [ "string", "null" ] } }, "required": [ "url", "title", "source" ], "additionalProperties": false } }, "date_match": { "anyOf": [ { "type": "string", "enum": [ "exact", "adjacent", "unknown", "outside" ] }, { "type": "null" } ], "description": "When the query names a date: whether the article is about that day (exact), the day before or after (adjacent), cannot tell (unknown) or another date (outside). Null otherwise." }, "referenced_date": { "description": "When the query names a date: the day the article is about (YYYY-MM-DD, in the request time zone), from its headline, its publication date or reading it.", "type": [ "string", "null" ] }, "found_in": { "type": "string", "enum": [ "index", "homepage", "section", "site_search", "discovery", "custom_index" ], "description": "Where it was found: the index; a live site (homepage, section, site_search); discovery, a source beyond the index read at the original site for this request; or custom_index, your own index (`index`)." }, "data": { "description": "Custom index: the structured data the page declares about itself (schema.org and Open Graph): price, high_price, currency, availability, brand, sku, gtin, rating, reviews. Null if it declares none.", "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": [ "string", "number" ] } }, { "type": "null" } ] }, "queries": { "description": "With several queries: which ones this result belongs to.", "type": "array", "items": { "type": "string" } } }, "required": [ "url", "title", "source", "country", "language", "published_at", "section", "snippet", "score", "headline_relevance", "read", "highlights", "tone", "answers", "duplicates", "date_match", "referenced_date", "found_in" ], "additionalProperties": false } }, "near_misses": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "title": { "type": "string" }, "source": { "type": [ "string", "null" ] }, "country": { "description": "Country of the source (ISO 3166-1 alpha-2), when known.", "type": [ "string", "null" ] }, "language": { "description": "Language of the source (ISO 639-1), when known: for a source in several languages, the one asked for in `languages`, or its main one.", "type": [ "string", "null" ] }, "published_at": { "type": [ "string", "null" ] }, "section": { "type": [ "string", "null" ] }, "snippet": { "description": "The standfirst or description, as the outlet published it.", "type": [ "string", "null" ] }, "score": { "type": "number", "description": "Probability that the article is about the query: from reading it if it was read, otherwise from its headline." }, "headline_relevance": { "type": "number" }, "read": { "anyOf": [ { "type": "object", "properties": { "probability": { "type": "number" }, "centrality": { "type": "number", "description": "0 not mentioned · 3 main topic." } }, "required": [ "probability", "centrality" ], "additionalProperties": false }, { "type": "null" } ] }, "highlights": { "type": "array", "items": { "type": "string" } }, "tone": { "anyOf": [ { "type": "object", "properties": { "label": { "type": "string", "enum": [ "positive", "neutral", "negative" ] }, "probabilities": { "type": "object", "propertyNames": { "type": "string", "enum": [ "positive", "neutral", "negative" ] }, "additionalProperties": { "type": "number" }, "required": [ "positive", "neutral", "negative" ] }, "basis": { "type": "string", "enum": [ "article", "headline" ] } }, "required": [ "label", "probabilities", "basis" ], "additionalProperties": false }, { "type": "null" } ] }, "answers": { "anyOf": [ { "type": "object", "properties": { "basis": { "type": "string", "enum": [ "article", "headline" ] }, "values": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "boolean" }, "probability": { "type": "number" } }, "required": [ "type", "probability" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "choice" }, "choice": { "type": "string" }, "probabilities": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "number" } }, "confidence": { "type": "number" } }, "required": [ "type", "choice" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "score" }, "score": { "type": "number" }, "probabilities": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "number" } }, "confidence": { "type": "number" } }, "required": [ "type", "score" ], "additionalProperties": false } ] } } }, "required": [ "basis", "values" ], "additionalProperties": false }, { "type": "null" } ] }, "duplicates": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "title": { "type": "string" }, "source": { "type": [ "string", "null" ] } }, "required": [ "url", "title", "source" ], "additionalProperties": false } }, "date_match": { "anyOf": [ { "type": "string", "enum": [ "exact", "adjacent", "unknown", "outside" ] }, { "type": "null" } ], "description": "When the query names a date: whether the article is about that day (exact), the day before or after (adjacent), cannot tell (unknown) or another date (outside). Null otherwise." }, "referenced_date": { "description": "When the query names a date: the day the article is about (YYYY-MM-DD, in the request time zone), from its headline, its publication date or reading it.", "type": [ "string", "null" ] }, "found_in": { "type": "string", "enum": [ "index", "homepage", "section", "site_search", "discovery", "custom_index" ], "description": "Where it was found: the index; a live site (homepage, section, site_search); discovery, a source beyond the index read at the original site for this request; or custom_index, your own index (`index`)." }, "data": { "description": "Custom index: the structured data the page declares about itself (schema.org and Open Graph): price, high_price, currency, availability, brand, sku, gtin, rating, reviews. Null if it declares none.", "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": [ "string", "number" ] } }, { "type": "null" } ] }, "queries": { "description": "With several queries: which ones this result belongs to.", "type": "array", "items": { "type": "string" } } }, "required": [ "url", "title", "source", "country", "language", "published_at", "section", "snippet", "score", "headline_relevance", "read", "highlights", "tone", "answers", "duplicates", "date_match", "referenced_date", "found_in" ], "additionalProperties": false } }, "rejected": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "title": { "type": "string" }, "source": { "type": [ "string", "null" ] }, "country": { "description": "Country of the source (ISO 3166-1 alpha-2), when known.", "type": [ "string", "null" ] }, "language": { "description": "Language of the source (ISO 639-1), when known: for a source in several languages, the one asked for in `languages`, or its main one.", "type": [ "string", "null" ] }, "published_at": { "type": [ "string", "null" ] }, "section": { "type": [ "string", "null" ] }, "snippet": { "description": "The standfirst or description, as the outlet published it.", "type": [ "string", "null" ] }, "score": { "type": "number", "description": "Probability that the article is about the query: from reading it if it was read, otherwise from its headline." }, "headline_relevance": { "type": "number" }, "read": { "anyOf": [ { "type": "object", "properties": { "probability": { "type": "number" }, "centrality": { "type": "number", "description": "0 not mentioned · 3 main topic." } }, "required": [ "probability", "centrality" ], "additionalProperties": false }, { "type": "null" } ] }, "highlights": { "type": "array", "items": { "type": "string" } }, "tone": { "anyOf": [ { "type": "object", "properties": { "label": { "type": "string", "enum": [ "positive", "neutral", "negative" ] }, "probabilities": { "type": "object", "propertyNames": { "type": "string", "enum": [ "positive", "neutral", "negative" ] }, "additionalProperties": { "type": "number" }, "required": [ "positive", "neutral", "negative" ] }, "basis": { "type": "string", "enum": [ "article", "headline" ] } }, "required": [ "label", "probabilities", "basis" ], "additionalProperties": false }, { "type": "null" } ] }, "answers": { "anyOf": [ { "type": "object", "properties": { "basis": { "type": "string", "enum": [ "article", "headline" ] }, "values": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "boolean" }, "probability": { "type": "number" } }, "required": [ "type", "probability" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "choice" }, "choice": { "type": "string" }, "probabilities": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "number" } }, "confidence": { "type": "number" } }, "required": [ "type", "choice" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "score" }, "score": { "type": "number" }, "probabilities": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "number" } }, "confidence": { "type": "number" } }, "required": [ "type", "score" ], "additionalProperties": false } ] } } }, "required": [ "basis", "values" ], "additionalProperties": false }, { "type": "null" } ] }, "duplicates": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "title": { "type": "string" }, "source": { "type": [ "string", "null" ] } }, "required": [ "url", "title", "source" ], "additionalProperties": false } }, "date_match": { "anyOf": [ { "type": "string", "enum": [ "exact", "adjacent", "unknown", "outside" ] }, { "type": "null" } ], "description": "When the query names a date: whether the article is about that day (exact), the day before or after (adjacent), cannot tell (unknown) or another date (outside). Null otherwise." }, "referenced_date": { "description": "When the query names a date: the day the article is about (YYYY-MM-DD, in the request time zone), from its headline, its publication date or reading it.", "type": [ "string", "null" ] }, "found_in": { "type": "string", "enum": [ "index", "homepage", "section", "site_search", "discovery", "custom_index" ], "description": "Where it was found: the index; a live site (homepage, section, site_search); discovery, a source beyond the index read at the original site for this request; or custom_index, your own index (`index`)." }, "data": { "description": "Custom index: the structured data the page declares about itself (schema.org and Open Graph): price, high_price, currency, availability, brand, sku, gtin, rating, reviews. Null if it declares none.", "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": [ "string", "number" ] } }, { "type": "null" } ] }, "queries": { "description": "With several queries: which ones this result belongs to.", "type": "array", "items": { "type": "string" } } }, "required": [ "url", "title", "source", "country", "language", "published_at", "section", "snippet", "score", "headline_relevance", "read", "highlights", "tone", "answers", "duplicates", "date_match", "referenced_date", "found_in" ], "additionalProperties": false } }, "diffusion": { "anyOf": [ { "type": "object", "properties": { "by_day": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "string" }, "count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "day", "count" ], "additionalProperties": false } }, "by_source": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string" }, "count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "first_published_at": { "type": "string" } }, "required": [ "source", "count", "first_published_at" ], "additionalProperties": false } }, "first": { "anyOf": [ { "type": "object", "properties": { "source": { "type": [ "string", "null" ] }, "url": { "type": "string" }, "title": { "type": "string" }, "published_at": { "type": "string" } }, "required": [ "source", "url", "title", "published_at" ], "additionalProperties": false }, { "type": "null" } ] }, "undated": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "by_day", "by_source", "first", "undated" ], "additionalProperties": false }, { "type": "null" } ] }, "tone": { "anyOf": [ { "type": "object", "properties": { "articles": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "overall": { "type": "object", "properties": { "positive": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "neutral": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "negative": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "positive", "neutral", "negative" ], "additionalProperties": false }, "by_source": { "type": "array", "items": { "type": "object", "properties": { "positive": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "neutral": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "negative": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "source": { "type": "string" } }, "required": [ "positive", "neutral", "negative", "source" ], "additionalProperties": false } } }, "required": [ "articles", "overall", "by_source" ], "additionalProperties": false }, { "type": "null" } ] }, "essential": { "anyOf": [ { "type": "object", "properties": { "excerpts": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" }, "url": { "type": "string" }, "source": { "type": [ "string", "null" ] }, "title": { "type": "string" } }, "required": [ "text", "url", "source", "title" ], "additionalProperties": false } } }, "required": [ "excerpts" ], "additionalProperties": false }, { "type": "null" } ] }, "temporal": { "anyOf": [ { "type": "object", "properties": { "expression": { "description": "The date words in the query, such as «hoy»; null when the query asks for the latest without naming a date.", "type": [ "string", "null" ] }, "from": { "description": "First day of the period the query refers to (YYYY-MM-DD, in `timezone`).", "type": [ "string", "null" ] }, "to": { "description": "Last day of that period; the same as `from` for a single day.", "type": [ "string", "null" ] }, "timezone": { "type": "string" }, "basis": { "type": "string", "enum": [ "published", "event", "recency" ], "description": "published: what was published about that day · event: news about what is scheduled for that day (published before it) · recency: the query asks for the latest without naming a date, so the newest go first." }, "window": { "anyOf": [ { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" } }, "required": [ "from", "to" ], "additionalProperties": false }, { "type": "null" } ], "description": "The publication window the date set, when it did. Null when published_after/before (or days) in the request took precedence: then the date only sorts." }, "widened": { "type": "boolean", "description": "No result is from the requested day: they come from the days around it." } }, "required": [ "expression", "from", "to", "timezone", "basis", "window", "widened" ], "additionalProperties": false }, { "type": "null" } ], "description": "How the date in the query was read: the topic was judged without it, and the results from that day go first. Null when the query names none." } }, "required": [ "query", "found", "total", "results", "near_misses", "rejected", "diffusion", "tone", "essential", "temporal" ], "additionalProperties": false } }, { "type": "null" } ], "description": "With several queries: the breakdown for each one." }, "near_misses": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "title": { "type": "string" }, "source": { "type": [ "string", "null" ] }, "country": { "description": "Country of the source (ISO 3166-1 alpha-2), when known.", "type": [ "string", "null" ] }, "language": { "description": "Language of the source (ISO 639-1), when known: for a source in several languages, the one asked for in `languages`, or its main one.", "type": [ "string", "null" ] }, "published_at": { "type": [ "string", "null" ] }, "section": { "type": [ "string", "null" ] }, "snippet": { "description": "The standfirst or description, as the outlet published it.", "type": [ "string", "null" ] }, "score": { "type": "number", "description": "Probability that the article is about the query: from reading it if it was read, otherwise from its headline." }, "headline_relevance": { "type": "number" }, "read": { "anyOf": [ { "type": "object", "properties": { "probability": { "type": "number" }, "centrality": { "type": "number", "description": "0 not mentioned · 3 main topic." } }, "required": [ "probability", "centrality" ], "additionalProperties": false }, { "type": "null" } ] }, "highlights": { "type": "array", "items": { "type": "string" } }, "tone": { "anyOf": [ { "type": "object", "properties": { "label": { "type": "string", "enum": [ "positive", "neutral", "negative" ] }, "probabilities": { "type": "object", "propertyNames": { "type": "string", "enum": [ "positive", "neutral", "negative" ] }, "additionalProperties": { "type": "number" }, "required": [ "positive", "neutral", "negative" ] }, "basis": { "type": "string", "enum": [ "article", "headline" ] } }, "required": [ "label", "probabilities", "basis" ], "additionalProperties": false }, { "type": "null" } ] }, "answers": { "anyOf": [ { "type": "object", "properties": { "basis": { "type": "string", "enum": [ "article", "headline" ] }, "values": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "boolean" }, "probability": { "type": "number" } }, "required": [ "type", "probability" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "choice" }, "choice": { "type": "string" }, "probabilities": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "number" } }, "confidence": { "type": "number" } }, "required": [ "type", "choice" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "score" }, "score": { "type": "number" }, "probabilities": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "number" } }, "confidence": { "type": "number" } }, "required": [ "type", "score" ], "additionalProperties": false } ] } } }, "required": [ "basis", "values" ], "additionalProperties": false }, { "type": "null" } ] }, "duplicates": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "title": { "type": "string" }, "source": { "type": [ "string", "null" ] } }, "required": [ "url", "title", "source" ], "additionalProperties": false } }, "date_match": { "anyOf": [ { "type": "string", "enum": [ "exact", "adjacent", "unknown", "outside" ] }, { "type": "null" } ], "description": "When the query names a date: whether the article is about that day (exact), the day before or after (adjacent), cannot tell (unknown) or another date (outside). Null otherwise." }, "referenced_date": { "description": "When the query names a date: the day the article is about (YYYY-MM-DD, in the request time zone), from its headline, its publication date or reading it.", "type": [ "string", "null" ] }, "found_in": { "type": "string", "enum": [ "index", "homepage", "section", "site_search", "discovery", "custom_index" ], "description": "Where it was found: the index; a live site (homepage, section, site_search); discovery, a source beyond the index read at the original site for this request; or custom_index, your own index (`index`)." }, "data": { "description": "Custom index: the structured data the page declares about itself (schema.org and Open Graph): price, high_price, currency, availability, brand, sku, gtin, rating, reviews. Null if it declares none.", "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": [ "string", "number" ] } }, { "type": "null" } ] }, "queries": { "description": "With several queries: which ones this result belongs to.", "type": "array", "items": { "type": "string" } } }, "required": [ "url", "title", "source", "country", "language", "published_at", "section", "snippet", "score", "headline_relevance", "read", "highlights", "tone", "answers", "duplicates", "date_match", "referenced_date", "found_in" ], "additionalProperties": false }, "description": "If nothing was found: the closest matches." }, "rejected": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "title": { "type": "string" }, "source": { "type": [ "string", "null" ] }, "country": { "description": "Country of the source (ISO 3166-1 alpha-2), when known.", "type": [ "string", "null" ] }, "language": { "description": "Language of the source (ISO 639-1), when known: for a source in several languages, the one asked for in `languages`, or its main one.", "type": [ "string", "null" ] }, "published_at": { "type": [ "string", "null" ] }, "section": { "type": [ "string", "null" ] }, "snippet": { "description": "The standfirst or description, as the outlet published it.", "type": [ "string", "null" ] }, "score": { "type": "number", "description": "Probability that the article is about the query: from reading it if it was read, otherwise from its headline." }, "headline_relevance": { "type": "number" }, "read": { "anyOf": [ { "type": "object", "properties": { "probability": { "type": "number" }, "centrality": { "type": "number", "description": "0 not mentioned · 3 main topic." } }, "required": [ "probability", "centrality" ], "additionalProperties": false }, { "type": "null" } ] }, "highlights": { "type": "array", "items": { "type": "string" } }, "tone": { "anyOf": [ { "type": "object", "properties": { "label": { "type": "string", "enum": [ "positive", "neutral", "negative" ] }, "probabilities": { "type": "object", "propertyNames": { "type": "string", "enum": [ "positive", "neutral", "negative" ] }, "additionalProperties": { "type": "number" }, "required": [ "positive", "neutral", "negative" ] }, "basis": { "type": "string", "enum": [ "article", "headline" ] } }, "required": [ "label", "probabilities", "basis" ], "additionalProperties": false }, { "type": "null" } ] }, "answers": { "anyOf": [ { "type": "object", "properties": { "basis": { "type": "string", "enum": [ "article", "headline" ] }, "values": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "boolean" }, "probability": { "type": "number" } }, "required": [ "type", "probability" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "choice" }, "choice": { "type": "string" }, "probabilities": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "number" } }, "confidence": { "type": "number" } }, "required": [ "type", "choice" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "score" }, "score": { "type": "number" }, "probabilities": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "number" } }, "confidence": { "type": "number" } }, "required": [ "type", "score" ], "additionalProperties": false } ] } } }, "required": [ "basis", "values" ], "additionalProperties": false }, { "type": "null" } ] }, "duplicates": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "title": { "type": "string" }, "source": { "type": [ "string", "null" ] } }, "required": [ "url", "title", "source" ], "additionalProperties": false } }, "date_match": { "anyOf": [ { "type": "string", "enum": [ "exact", "adjacent", "unknown", "outside" ] }, { "type": "null" } ], "description": "When the query names a date: whether the article is about that day (exact), the day before or after (adjacent), cannot tell (unknown) or another date (outside). Null otherwise." }, "referenced_date": { "description": "When the query names a date: the day the article is about (YYYY-MM-DD, in the request time zone), from its headline, its publication date or reading it.", "type": [ "string", "null" ] }, "found_in": { "type": "string", "enum": [ "index", "homepage", "section", "site_search", "discovery", "custom_index" ], "description": "Where it was found: the index; a live site (homepage, section, site_search); discovery, a source beyond the index read at the original site for this request; or custom_index, your own index (`index`)." }, "data": { "description": "Custom index: the structured data the page declares about itself (schema.org and Open Graph): price, high_price, currency, availability, brand, sku, gtin, rating, reviews. Null if it declares none.", "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": [ "string", "number" ] } }, { "type": "null" } ] }, "queries": { "description": "With several queries: which ones this result belongs to.", "type": "array", "items": { "type": "string" } } }, "required": [ "url", "title", "source", "country", "language", "published_at", "section", "snippet", "score", "headline_relevance", "read", "highlights", "tone", "answers", "duplicates", "date_match", "referenced_date", "found_in" ], "additionalProperties": false }, "description": "The headline looked relevant, but reading the article ruled it out." }, "diffusion": { "anyOf": [ { "type": "object", "properties": { "by_day": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "string" }, "count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "day", "count" ], "additionalProperties": false } }, "by_source": { "type": "array", "items": { "type": "object", "properties": { "source": { "type": "string" }, "count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "first_published_at": { "type": "string" } }, "required": [ "source", "count", "first_published_at" ], "additionalProperties": false } }, "first": { "anyOf": [ { "type": "object", "properties": { "source": { "type": [ "string", "null" ] }, "url": { "type": "string" }, "title": { "type": "string" }, "published_at": { "type": "string" } }, "required": [ "source", "url", "title", "published_at" ], "additionalProperties": false }, { "type": "null" } ] }, "undated": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "by_day", "by_source", "first", "undated" ], "additionalProperties": false }, { "type": "null" } ] }, "tone": { "anyOf": [ { "type": "object", "properties": { "articles": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "overall": { "type": "object", "properties": { "positive": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "neutral": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "negative": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "positive", "neutral", "negative" ], "additionalProperties": false }, "by_source": { "type": "array", "items": { "type": "object", "properties": { "positive": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "neutral": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "negative": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "source": { "type": "string" } }, "required": [ "positive", "neutral", "negative", "source" ], "additionalProperties": false } } }, "required": [ "articles", "overall", "by_source" ], "additionalProperties": false }, { "type": "null" } ] }, "essential": { "anyOf": [ { "type": "object", "properties": { "excerpts": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" }, "url": { "type": "string" }, "source": { "type": [ "string", "null" ] }, "title": { "type": "string" } }, "required": [ "text", "url", "source", "title" ], "additionalProperties": false } } }, "required": [ "excerpts" ], "additionalProperties": false }, { "type": "null" } ] }, "reference": { "anyOf": [ { "type": "object", "properties": { "url": { "type": "string" }, "title": { "type": "string" } }, "required": [ "url", "title" ], "additionalProperties": false }, { "type": "null" } ] }, "custom_index": { "description": "With `index`: the custom index that was searched.", "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, { "type": "null" } ] }, "temporal": { "anyOf": [ { "type": "object", "properties": { "expression": { "description": "The date words in the query, such as «hoy»; null when the query asks for the latest without naming a date.", "type": [ "string", "null" ] }, "from": { "description": "First day of the period the query refers to (YYYY-MM-DD, in `timezone`).", "type": [ "string", "null" ] }, "to": { "description": "Last day of that period; the same as `from` for a single day.", "type": [ "string", "null" ] }, "timezone": { "type": "string" }, "basis": { "type": "string", "enum": [ "published", "event", "recency" ], "description": "published: what was published about that day · event: news about what is scheduled for that day (published before it) · recency: the query asks for the latest without naming a date, so the newest go first." }, "window": { "anyOf": [ { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" } }, "required": [ "from", "to" ], "additionalProperties": false }, { "type": "null" } ], "description": "The publication window the date set, when it did. Null when published_after/before (or days) in the request took precedence: then the date only sorts." }, "widened": { "type": "boolean", "description": "No result is from the requested day: they come from the days around it." } }, "required": [ "expression", "from", "to", "timezone", "basis", "window", "widened" ], "additionalProperties": false }, { "type": "null" } ], "description": "How the date in the query was read: the topic was judged without it, and the results from that day go first. Null when the query names none." }, "site": { "type": [ "string", "null" ] }, "index": { "anyOf": [ { "type": "object", "properties": { "updated_at": { "description": "The oldest last refresh among the sources searched: how fresh the index was for this request.", "type": [ "string", "null" ] } }, "required": [ "updated_at" ], "additionalProperties": false }, { "type": "null" } ] }, "usage": { "type": "object", "properties": { "tokens": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Model tokens used by this request. 0 when it came from the cache." }, "calls": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "cost_usd": { "description": "What this request was billed, in USD: the list price of its mode (see `pricing` in GET /v1/usage), per query. 0 when it came from the cache. Null in partial results.", "type": [ "number", "null" ] }, "headlines": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "from_memory": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "pages_direct": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "pages_browser": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "duration_ms": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "tokens", "calls", "cost_usd", "headlines", "from_memory", "pages_direct", "pages_browser", "duration_ms" ], "additionalProperties": false }, "budget": { "anyOf": [ { "type": "object", "properties": { "max_tokens": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "used": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "exhausted": { "type": "boolean" } }, "required": [ "max_tokens", "used", "exhausted" ], "additionalProperties": false }, { "type": "null" } ] }, "discovery": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "string", "enum": [ "used", "background", "skipped", "budget", "timeout" ], "description": "used: it searched beyond the index within the time budget · background: in ultra or fast there was nothing to check quickly; it keeps learning in the background · skipped: the index had enough, or it does not apply · budget: the discovery limit was reached · timeout: the time budget ran out (incomplete: true)." }, "sites": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Sites beyond the index that contributed candidates." }, "ms": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Time it added to this request, in milliseconds." } }, "required": [ "status", "sites", "ms" ], "additionalProperties": false }, { "type": "null" } ], "description": "Discovery: when the index has fewer than 3 good matches, typesearch looks for sources beyond it and reads them at the original site. Null only in partial events, while it is still running." }, "incomplete": { "type": "boolean", "description": "The token cap (max_tokens) or the discovery time budget ran out: there may be more." }, "cached_at": { "type": [ "string", "null" ] }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } } }, "required": [ "id", "object", "mode", "queries", "found", "total", "results", "groups", "near_misses", "rejected", "diffusion", "tone", "essential", "reference", "temporal", "site", "index", "usage", "budget", "discovery", "incomplete", "cached_at", "warnings" ], "additionalProperties": false }