{ "openapi": "3.1.0", "info": { "title": "typesearch · News search API", "version": "1.0.0", "description": "News search by topic: across an index of news outlets, on a live site, or for articles similar to a given one, judged by a calibrated relevance model. Compatible endpoints for Perplexity (/compat/perplexity), Exa (/compat/exa) and Tako (/compat/tako): see the migration guides at https://typesearch.ai/docs." }, "servers": [ { "url": "https://api.typesearch.ai" } ], "security": [ { "bearer": [] }, { "apiKey": [] } ], "components": { "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer" }, "apiKey": { "type": "apiKey", "in": "header", "name": "x-api-key" } }, "schemas": { "SearchRequest": { "type": "object", "properties": { "query": { "anyOf": [ { "type": "string", "minLength": 2, "maxLength": 200 }, { "minItems": 1, "maxItems": 5, "type": "array", "items": { "type": "string", "minLength": 2, "maxLength": 200 } } ], "description": "One query, or up to 5 judged together." }, "sources": { "description": "Only these index sources (see GET /v1/sources).", "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "lanacion", "infobae", "cronista", "ambito", "pagina12", "lavoz", "perfil", "minutouno", "losandes" ] } }, "include_domains": { "description": "Only these domains or paths. A domain includes its subdomains.", "maxItems": 20, "type": "array", "items": { "type": "string", "maxLength": 200, "pattern": "^(https?:\\/\\/)?(\\*\\.)?[\\w-]+(\\.[\\w-]+)+(\\/\\S*)?$" } }, "exclude_domains": { "description": "Never these domains or paths.", "maxItems": 20, "type": "array", "items": { "type": "string", "maxLength": 200, "pattern": "^(https?:\\/\\/)?(\\*\\.)?[\\w-]+(\\.[\\w-]+)+(\\/\\S*)?$" } }, "sections": { "description": "Only these sections: the section in the feed, or the start of the URL path.", "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 60 } }, "days": { "description": "The last N days; null for the whole index. Defaults to 7 unless dates are given.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 365 }, { "type": "null" } ] }, "published_after": { "description": "Published on or after this date. A bare date is read in Argentina time (UTC−3).", "anyOf": [ { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } ] }, "published_before": { "description": "Published on or before this date; a bare date includes that whole day.", "anyOf": [ { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } ] }, "mode": { "default": "normal", "description": "ultra: headlines only, the cheapest · fast: headlines · normal: reads the best matches · deep: the whole index and more reading.", "type": "string", "enum": [ "ultra", "fast", "normal", "deep" ] }, "max_results": { "default": 10, "type": "integer", "minimum": 1, "maximum": 50 }, "highlights": { "description": "Verbatim excerpts from the articles that were read. On by default only in deep mode.", "type": "boolean" }, "dedupe": { "default": false, "description": "Groups the same story reported by several outlets.", "type": "boolean" }, "tone": { "default": false, "description": "Tone toward the query: positive, neutral or negative.", "type": "boolean" }, "essential": { "description": "The essentials: verbatim excerpts across several articles. On by default only in deep mode.", "type": "boolean" }, "questions": { "default": {}, "description": "Structured output: typed questions (boolean, choice, score) that the model answers for each result.", "type": "object", "propertyNames": { "type": "string", "pattern": "^[\\w-]{1,40}$" }, "additionalProperties": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "boolean" }, "instructions": { "anyOf": [ { "type": "string" }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/SearchRequest___schema0" } }, { "type": "array", "items": { "$ref": "#/components/schemas/SearchRequest___schema0" } } ] }, "criteria": { "type": "object", "properties": { "true": { "type": "string" }, "false": { "type": "string" } } } }, "required": [ "type", "instructions" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "choice" }, "instructions": { "anyOf": [ { "type": "string" }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/SearchRequest___schema0" } }, { "type": "array", "items": { "$ref": "#/components/schemas/SearchRequest___schema0" } } ] }, "criteria": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": [ "string", "null" ] } } }, "required": [ "type", "instructions", "criteria" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "score" }, "instructions": { "anyOf": [ { "type": "string" }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/SearchRequest___schema0" } }, { "type": "array", "items": { "$ref": "#/components/schemas/SearchRequest___schema0" } } ] }, "criteria": { "minItems": 2, "type": "array", "items": { "type": "string" } } }, "required": [ "type", "instructions", "criteria" ] } ] } }, "max_tokens": { "default": null, "description": "Cap on model tokens. If it is reached, the response comes back with incomplete: true.", "anyOf": [ { "type": "integer", "minimum": 2000, "maximum": 9007199254740991 }, { "type": "null" } ] }, "fresh": { "default": false, "description": "Skips the result cache (10 minutes).", "type": "boolean" }, "stream": { "default": false, "description": "Server-sent events while it searches: step, partial, result.", "type": "boolean" } }, "required": [ "query" ], "additionalProperties": false }, "SearchRequest___schema0": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "$ref": "#/components/schemas/SearchRequest___schema0" } }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/SearchRequest___schema0" } } ] }, "SiteSearchRequest": { "type": "object", "properties": { "site": { "type": "string", "minLength": 3, "maxLength": 500, "description": "The live site to search, such as lanacion.com.ar." }, "query": { "type": "string", "minLength": 2, "maxLength": 200 }, "sections": { "description": "Only these sections: the section in the feed, or the start of the URL path.", "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 60 } }, "exclude_domains": { "description": "Never these domains or paths.", "maxItems": 20, "type": "array", "items": { "type": "string", "maxLength": 200, "pattern": "^(https?:\\/\\/)?(\\*\\.)?[\\w-]+(\\.[\\w-]+)+(\\/\\S*)?$" } }, "mode": { "default": "normal", "description": "ultra: headlines only, the cheapest · fast: headlines · normal: reads the best matches · deep: the whole index and more reading.", "type": "string", "enum": [ "ultra", "fast", "normal", "deep" ] }, "max_results": { "default": 10, "type": "integer", "minimum": 1, "maximum": 50 }, "highlights": { "description": "Verbatim excerpts from the articles that were read. On by default only in deep mode.", "type": "boolean" }, "dedupe": { "default": false, "description": "Groups the same story reported by several outlets.", "type": "boolean" }, "tone": { "default": false, "description": "Tone toward the query: positive, neutral or negative.", "type": "boolean" }, "essential": { "description": "The essentials: verbatim excerpts across several articles. On by default only in deep mode.", "type": "boolean" }, "questions": { "default": {}, "description": "Structured output: typed questions (boolean, choice, score) that the model answers for each result.", "type": "object", "propertyNames": { "type": "string", "pattern": "^[\\w-]{1,40}$" }, "additionalProperties": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "boolean" }, "instructions": { "anyOf": [ { "type": "string" }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/SiteSearchRequest___schema0" } }, { "type": "array", "items": { "$ref": "#/components/schemas/SiteSearchRequest___schema0" } } ] }, "criteria": { "type": "object", "properties": { "true": { "type": "string" }, "false": { "type": "string" } } } }, "required": [ "type", "instructions" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "choice" }, "instructions": { "anyOf": [ { "type": "string" }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/SiteSearchRequest___schema0" } }, { "type": "array", "items": { "$ref": "#/components/schemas/SiteSearchRequest___schema0" } } ] }, "criteria": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": [ "string", "null" ] } } }, "required": [ "type", "instructions", "criteria" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "score" }, "instructions": { "anyOf": [ { "type": "string" }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/SiteSearchRequest___schema0" } }, { "type": "array", "items": { "$ref": "#/components/schemas/SiteSearchRequest___schema0" } } ] }, "criteria": { "minItems": 2, "type": "array", "items": { "type": "string" } } }, "required": [ "type", "instructions", "criteria" ] } ] } }, "max_tokens": { "default": null, "description": "Cap on model tokens. If it is reached, the response comes back with incomplete: true.", "anyOf": [ { "type": "integer", "minimum": 2000, "maximum": 9007199254740991 }, { "type": "null" } ] }, "fresh": { "default": false, "description": "Skips the result cache (10 minutes).", "type": "boolean" }, "stream": { "default": false, "description": "Server-sent events instead of an asynchronous job.", "type": "boolean" } }, "required": [ "site", "query" ], "additionalProperties": false }, "SiteSearchRequest___schema0": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "$ref": "#/components/schemas/SiteSearchRequest___schema0" } }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/SiteSearchRequest___schema0" } } ] }, "SimilarRequest": { "type": "object", "properties": { "url": { "type": "string", "maxLength": 2000, "format": "uri" }, "sources": { "description": "Only these index sources (see GET /v1/sources).", "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "lanacion", "infobae", "cronista", "ambito", "pagina12", "lavoz", "perfil", "minutouno", "losandes" ] } }, "include_domains": { "description": "Only these domains or paths. A domain includes its subdomains.", "maxItems": 20, "type": "array", "items": { "type": "string", "maxLength": 200, "pattern": "^(https?:\\/\\/)?(\\*\\.)?[\\w-]+(\\.[\\w-]+)+(\\/\\S*)?$" } }, "exclude_domains": { "description": "Never these domains or paths.", "maxItems": 20, "type": "array", "items": { "type": "string", "maxLength": 200, "pattern": "^(https?:\\/\\/)?(\\*\\.)?[\\w-]+(\\.[\\w-]+)+(\\/\\S*)?$" } }, "sections": { "description": "Only these sections: the section in the feed, or the start of the URL path.", "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 60 } }, "days": { "description": "The last N days; null for the whole index. Defaults to 7 unless dates are given.", "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 365 }, { "type": "null" } ] }, "published_after": { "description": "Published on or after this date. A bare date is read in Argentina time (UTC−3).", "anyOf": [ { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } ] }, "published_before": { "description": "Published on or before this date; a bare date includes that whole day.", "anyOf": [ { "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } ] }, "mode": { "default": "normal", "description": "ultra: headlines only, the cheapest · fast: headlines · normal: reads the best matches · deep: the whole index and more reading.", "type": "string", "enum": [ "ultra", "fast", "normal", "deep" ] }, "max_results": { "default": 10, "type": "integer", "minimum": 1, "maximum": 50 }, "highlights": { "description": "Verbatim excerpts from the articles that were read. On by default only in deep mode.", "type": "boolean" }, "dedupe": { "default": false, "description": "Groups the same story reported by several outlets.", "type": "boolean" }, "tone": { "default": false, "description": "Tone toward the query: positive, neutral or negative.", "type": "boolean" }, "essential": { "description": "The essentials: verbatim excerpts across several articles. On by default only in deep mode.", "type": "boolean" }, "questions": { "default": {}, "description": "Structured output: typed questions (boolean, choice, score) that the model answers for each result.", "type": "object", "propertyNames": { "type": "string", "pattern": "^[\\w-]{1,40}$" }, "additionalProperties": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "boolean" }, "instructions": { "anyOf": [ { "type": "string" }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/SimilarRequest___schema0" } }, { "type": "array", "items": { "$ref": "#/components/schemas/SimilarRequest___schema0" } } ] }, "criteria": { "type": "object", "properties": { "true": { "type": "string" }, "false": { "type": "string" } } } }, "required": [ "type", "instructions" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "choice" }, "instructions": { "anyOf": [ { "type": "string" }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/SimilarRequest___schema0" } }, { "type": "array", "items": { "$ref": "#/components/schemas/SimilarRequest___schema0" } } ] }, "criteria": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": [ "string", "null" ] } } }, "required": [ "type", "instructions", "criteria" ] }, { "type": "object", "properties": { "type": { "type": "string", "const": "score" }, "instructions": { "anyOf": [ { "type": "string" }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/SimilarRequest___schema0" } }, { "type": "array", "items": { "$ref": "#/components/schemas/SimilarRequest___schema0" } } ] }, "criteria": { "minItems": 2, "type": "array", "items": { "type": "string" } } }, "required": [ "type", "instructions", "criteria" ] } ] } }, "max_tokens": { "default": null, "description": "Cap on model tokens. If it is reached, the response comes back with incomplete: true.", "anyOf": [ { "type": "integer", "minimum": 2000, "maximum": 9007199254740991 }, { "type": "null" } ] }, "fresh": { "default": false, "description": "Skips the result cache (10 minutes).", "type": "boolean" } }, "required": [ "url" ], "additionalProperties": false }, "SimilarRequest___schema0": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "$ref": "#/components/schemas/SimilarRequest___schema0" } }, { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "$ref": "#/components/schemas/SimilarRequest___schema0" } } ] }, "ContentsRequest": { "type": "object", "properties": { "urls": { "minItems": 1, "maxItems": 10, "type": "array", "items": { "type": "string", "maxLength": 2000, "format": "uri" } }, "query": { "description": "With a query, the model picks the excerpts about it and says how much each article covers it.", "type": "string", "minLength": 2, "maxLength": 200 }, "highlights": { "default": true, "type": "boolean" }, "max_tokens": { "default": null, "description": "Cap on model tokens. If it is reached, the response comes back with incomplete: true.", "anyOf": [ { "type": "integer", "minimum": 2000, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "urls" ], "additionalProperties": false }, "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" ] }, "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 } }, "found_in": { "type": "string", "enum": [ "index", "homepage", "section", "site_search" ] }, "queries": { "description": "With several queries: which ones this result belongs to.", "type": "array", "items": { "type": "string" } } }, "required": [ "url", "title", "source", "published_at", "section", "snippet", "score", "headline_relevance", "read", "highlights", "tone", "answers", "duplicates", "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" ] }, "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 } }, "found_in": { "type": "string", "enum": [ "index", "homepage", "section", "site_search" ] }, "queries": { "description": "With several queries: which ones this result belongs to.", "type": "array", "items": { "type": "string" } } }, "required": [ "url", "title", "source", "published_at", "section", "snippet", "score", "headline_relevance", "read", "highlights", "tone", "answers", "duplicates", "found_in" ], "additionalProperties": false } }, "near_misses": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "title": { "type": "string" }, "source": { "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 } }, "found_in": { "type": "string", "enum": [ "index", "homepage", "section", "site_search" ] }, "queries": { "description": "With several queries: which ones this result belongs to.", "type": "array", "items": { "type": "string" } } }, "required": [ "url", "title", "source", "published_at", "section", "snippet", "score", "headline_relevance", "read", "highlights", "tone", "answers", "duplicates", "found_in" ], "additionalProperties": false } }, "rejected": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "title": { "type": "string" }, "source": { "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 } }, "found_in": { "type": "string", "enum": [ "index", "homepage", "section", "site_search" ] }, "queries": { "description": "With several queries: which ones this result belongs to.", "type": "array", "items": { "type": "string" } } }, "required": [ "url", "title", "source", "published_at", "section", "snippet", "score", "headline_relevance", "read", "highlights", "tone", "answers", "duplicates", "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" } ] } }, "required": [ "query", "found", "total", "results", "near_misses", "rejected", "diffusion", "tone", "essential" ], "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" ] }, "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 } }, "found_in": { "type": "string", "enum": [ "index", "homepage", "section", "site_search" ] }, "queries": { "description": "With several queries: which ones this result belongs to.", "type": "array", "items": { "type": "string" } } }, "required": [ "url", "title", "source", "published_at", "section", "snippet", "score", "headline_relevance", "read", "highlights", "tone", "answers", "duplicates", "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" ] }, "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 } }, "found_in": { "type": "string", "enum": [ "index", "homepage", "section", "site_search" ] }, "queries": { "description": "With several queries: which ones this result belongs to.", "type": "array", "items": { "type": "string" } } }, "required": [ "url", "title", "source", "published_at", "section", "snippet", "score", "headline_relevance", "read", "highlights", "tone", "answers", "duplicates", "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" } ] }, "site": { "type": [ "string", "null" ] }, "index": { "anyOf": [ { "type": "object", "properties": { "sources": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "articles": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "updated_at": { "type": [ "string", "null" ] }, "sources_without_articles": { "type": "array", "items": { "type": "string" } } }, "required": [ "sources", "articles", "updated_at", "sources_without_articles" ], "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: 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" } ] }, "incomplete": { "type": "boolean" }, "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", "site", "index", "usage", "budget", "incomplete", "cached_at", "warnings" ], "additionalProperties": false }, "ContentsResponse": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "contents" }, "results": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "status": { "type": "string", "enum": [ "ok", "error" ] }, "error": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false }, { "type": "null" } ] }, "title": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "published_at": { "type": [ "string", "null" ] }, "source": { "type": [ "string", "null" ] }, "excerpt": { "description": "The start of the article, kept short: never the full text.", "type": [ "string", "null" ] }, "highlights": { "type": "array", "items": { "type": "string" } }, "relevance": { "description": "With query: probability that the article is about it.", "type": [ "number", "null" ] } }, "required": [ "url", "status", "error", "title", "description", "published_at", "source", "excerpt", "highlights", "relevance" ], "additionalProperties": false } }, "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: 0 when it came from the cache. Null in partial results.", "type": [ "number", "null" ] }, "duration_ms": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "tokens", "calls", "cost_usd", "duration_ms" ], "additionalProperties": false } }, "required": [ "id", "object", "results", "usage" ], "additionalProperties": false }, "Job": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "const": "job" }, "status": { "type": "string", "enum": [ "queued", "running", "succeeded", "failed" ] }, "created_at": { "type": "string" }, "finished_at": { "type": [ "string", "null" ] }, "result": { "anyOf": [ { "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" ] }, "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 } }, "found_in": { "type": "string", "enum": [ "index", "homepage", "section", "site_search" ] }, "queries": { "description": "With several queries: which ones this result belongs to.", "type": "array", "items": { "type": "string" } } }, "required": [ "url", "title", "source", "published_at", "section", "snippet", "score", "headline_relevance", "read", "highlights", "tone", "answers", "duplicates", "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" ] }, "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 } }, "found_in": { "type": "string", "enum": [ "index", "homepage", "section", "site_search" ] }, "queries": { "description": "With several queries: which ones this result belongs to.", "type": "array", "items": { "type": "string" } } }, "required": [ "url", "title", "source", "published_at", "section", "snippet", "score", "headline_relevance", "read", "highlights", "tone", "answers", "duplicates", "found_in" ], "additionalProperties": false } }, "near_misses": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "title": { "type": "string" }, "source": { "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 } }, "found_in": { "type": "string", "enum": [ "index", "homepage", "section", "site_search" ] }, "queries": { "description": "With several queries: which ones this result belongs to.", "type": "array", "items": { "type": "string" } } }, "required": [ "url", "title", "source", "published_at", "section", "snippet", "score", "headline_relevance", "read", "highlights", "tone", "answers", "duplicates", "found_in" ], "additionalProperties": false } }, "rejected": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "title": { "type": "string" }, "source": { "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 } }, "found_in": { "type": "string", "enum": [ "index", "homepage", "section", "site_search" ] }, "queries": { "description": "With several queries: which ones this result belongs to.", "type": "array", "items": { "type": "string" } } }, "required": [ "url", "title", "source", "published_at", "section", "snippet", "score", "headline_relevance", "read", "highlights", "tone", "answers", "duplicates", "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" } ] } }, "required": [ "query", "found", "total", "results", "near_misses", "rejected", "diffusion", "tone", "essential" ], "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" ] }, "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 } }, "found_in": { "type": "string", "enum": [ "index", "homepage", "section", "site_search" ] }, "queries": { "description": "With several queries: which ones this result belongs to.", "type": "array", "items": { "type": "string" } } }, "required": [ "url", "title", "source", "published_at", "section", "snippet", "score", "headline_relevance", "read", "highlights", "tone", "answers", "duplicates", "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" ] }, "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 } }, "found_in": { "type": "string", "enum": [ "index", "homepage", "section", "site_search" ] }, "queries": { "description": "With several queries: which ones this result belongs to.", "type": "array", "items": { "type": "string" } } }, "required": [ "url", "title", "source", "published_at", "section", "snippet", "score", "headline_relevance", "read", "highlights", "tone", "answers", "duplicates", "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" } ] }, "site": { "type": [ "string", "null" ] }, "index": { "anyOf": [ { "type": "object", "properties": { "sources": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "articles": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "updated_at": { "type": [ "string", "null" ] }, "sources_without_articles": { "type": "array", "items": { "type": "string" } } }, "required": [ "sources", "articles", "updated_at", "sources_without_articles" ], "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: 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" } ] }, "incomplete": { "type": "boolean" }, "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", "site", "index", "usage", "budget", "incomplete", "cached_at", "warnings" ], "additionalProperties": false }, { "type": "null" } ] }, "error": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "detail": { "type": "string" }, "code": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "object", "status", "created_at", "finished_at", "result", "error" ], "additionalProperties": false }, "Sources": { "type": "object", "properties": { "object": { "type": "string", "const": "sources" }, "updated_at": { "type": [ "string", "null" ] }, "articles": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "sources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "homepage": { "type": "string" }, "articles": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "last_ingested_at": { "type": [ "string", "null" ] }, "via": { "type": [ "string", "null" ] }, "error": { "type": [ "string", "null" ] }, "retry_at": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "homepage", "articles", "last_ingested_at", "via", "error", "retry_at" ], "additionalProperties": false } } }, "required": [ "object", "updated_at", "articles", "sources" ], "additionalProperties": false }, "Usage": { "type": "object", "properties": { "object": { "type": "string", "const": "usage" }, "key": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": false }, "limits": { "type": "object", "properties": { "tokens_per_day": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "requests_per_minute": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "requests_per_second": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "tokens_per_day", "requests_per_minute", "requests_per_second" ], "additionalProperties": false }, "today": { "type": "object", "properties": { "requests": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "tokens": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "cost_usd": { "type": "number" }, "remaining_tokens": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "requests", "tokens", "cost_usd", "remaining_tokens" ], "additionalProperties": false }, "last_30_days": { "type": "object", "properties": { "requests": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "tokens": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "cost_usd": { "type": "number" } }, "required": [ "requests", "tokens", "cost_usd" ], "additionalProperties": false }, "credit": { "anyOf": [ { "type": "object", "properties": { "balance_usd": { "type": "number" }, "plan": { "type": "string", "enum": [ "payg", "plan" ] }, "spent_this_month_usd": { "type": "number" }, "monthly_limit_usd": { "type": [ "number", "null" ] } }, "required": [ "balance_usd", "plan", "spent_this_month_usd", "monthly_limit_usd" ], "additionalProperties": false }, { "type": "null" } ], "description": "The organization credit behind this key. Null for internal keys, which are not billed." } }, "required": [ "object", "key", "limits", "today", "last_30_days", "credit" ], "additionalProperties": false }, "Problem": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "detail": { "type": "string" }, "code": { "type": "string" }, "request_id": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "path", "message" ], "additionalProperties": false } } }, "required": [ "type", "title", "status", "detail", "code", "request_id" ], "additionalProperties": false } } }, "paths": { "/v1/search": { "post": { "summary": "Search the index for one topic, or up to five", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchRequest" } } } }, "responses": { "200": { "description": "The result; with stream: true, server-sent events.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" } }, "text/event-stream": { "schema": { "type": "string", "description": "Server-sent events: step, partial, result or error; `data` is JSON." } } } }, "402": { "description": "Payment required: `insufficient_credits` (no credit left), `spend_limit_reached` (the key hit its monthly limit) or `budget_too_small`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "Error (RFC 9457). In English unless the request sends `Accept-Language: es`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/search/site": { "post": { "summary": "Search a live site for a topic", "description": "Can take up to a minute: returns a job (202) to poll at /v1/jobs/{id}, or server-sent events with stream: true.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteSearchRequest" } } } }, "responses": { "200": { "description": "With stream: true, server-sent events.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" } }, "text/event-stream": { "schema": { "type": "string", "description": "Server-sent events: step, partial, result or error; `data` is JSON." } } } }, "202": { "description": "The job that was created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "402": { "description": "Payment required: `insufficient_credits` (no credit left), `spend_limit_reached` (the key hit its monthly limit) or `budget_too_small`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "Error (RFC 9457). In English unless the request sends `Accept-Language: es`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/jobs/{id}": { "get": { "summary": "Get a job’s status and result", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The job id returned by POST /v1/search/site.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The job.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } }, "402": { "description": "Payment required: `insufficient_credits` (no credit left), `spend_limit_reached` (the key hit its monthly limit) or `budget_too_small`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "Error (RFC 9457). In English unless the request sends `Accept-Language: es`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/similar": { "post": { "summary": "Find index articles about the same story as a URL", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimilarRequest" } } } }, "responses": { "200": { "description": "The result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" } } } }, "402": { "description": "Payment required: `insufficient_credits` (no credit left), `spend_limit_reached` (the key hit its monthly limit) or `budget_too_small`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "Error (RFC 9457). In English unless the request sends `Accept-Language: es`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/contents": { "post": { "summary": "Get metadata and short excerpts for up to 10 URLs", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentsRequest" } } } }, "responses": { "200": { "description": "One entry per URL, each with its own status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentsResponse" } } } }, "402": { "description": "Payment required: `insufficient_credits` (no credit left), `spend_limit_reached` (the key hit its monthly limit) or `budget_too_small`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "Error (RFC 9457). In English unless the request sends `Accept-Language: es`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/sources": { "get": { "summary": "List the index sources and their status", "responses": { "200": { "description": "The sources.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Sources" } } } }, "402": { "description": "Payment required: `insufficient_credits` (no credit left), `spend_limit_reached` (the key hit its monthly limit) or `budget_too_small`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "Error (RFC 9457). In English unless the request sends `Accept-Language: es`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/usage": { "get": { "summary": "Get this key’s usage and limits", "responses": { "200": { "description": "The usage.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Usage" } } } }, "402": { "description": "Payment required: `insufficient_credits` (no credit left), `spend_limit_reached` (the key hit its monthly limit) or `budget_too_small`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "default": { "description": "Error (RFC 9457). In English unless the request sends `Accept-Language: es`.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } } } }