Input schema (JSON)
{
"type": "object",
"required": [],
"properties": {
"limit": {
"type": "integer",
"description": "Maximum number of articles to return. Default: 10. Results are ordered by similarity score (highest first)"
},
"query": {
"type": "string",
"description": "Semantic search query to find relevant articles. Supports natural language queries (e.g., 'Taylor Swift', 'NFL playoffs', 'climate change policy')"
},
"cursor": {
"type": "string",
"description": "Opaque pagination cursor from a previous response next_cursor. Continues within the top-100 candidate window."
},
"recent": {
"type": "object",
"description": "Recent mode: {since_ts: epoch seconds, take: int} or {days_back: int, take: int}. If both are provided, since_ts takes precedence."
},
"filters": {
"type": "object",
"description": "Optional metadata filters to narrow search results. Available fields: category (string), categories (array), language (string), sentiment (string), media_type (string), has_image/has_video/has_audio (boolean), length_words/length_chars/duration_seconds (number), publish_date_ts (number timestamp), keywords (array), entities (array). Operators: $eq (equals), $ne (not equals), $gt/$gte/$lt/$lte (numeric), $in/$nin (array match), $exists (field presence), $and/$or (logical). Examples: {\"category\": \"sports\"}, {\"has_video\": true}, {\"$and\":[{\"publish_date_ts\":{\"$gte\":1704067200}}]}, {\"$and\":[{\"categories\": {\"$in\": [\"sports\", \"news\"]}}]}, {\"$and\": [{\"category\": \"sports\"}, {\"has_image\": true}]}. Filters evaluated during vector search."
},
"threshold": {
"type": "number",
"description": "Similarity score threshold (0.0-1.0). Only returns articles with similarity scores above this value. Lower values = stricter matching. Default: 1.0 (returns all matches)"
},
"publishers": {
"type": "array",
"items": {
"type": "string"
},
"description": "Optional array of lowercase publisher identifiers to narrow the search (e.g. adweek, billboard). Omit to search all publishers available on Free Discovery."
},
"query_vector": {
"type": "array",
"items": {
"type": "number"
},
"description": "Optional precomputed embedding vector. If provided, retrieval uses this vector directly instead of generating one from query."
}
}
}