APITube News

Search news articles using APITube News API with comprehensive filtering. IMPORTANT INSTRUCTIONS FOR QUERY CONSTRUCTION: 1. DO NOT use dots in parameter names directly in the root object. Use nested objects instead. 2. The system will automatically convert nested objects to dot notation for the API. Example: Use { language: { code: "en" } } instead of { "language.code": "en" }. 3. For multiple values in one parameter, use COMMA separation (e.g., "en,ru,fr" for multiple languages). 4. Integer filters (has_*, is_*) accept ONLY 0 or 1 (e.g., has_image=1, is_duplicate=0). 5. Date format: ISO 8601 (YYYY-MM-DD or YYYY-MM-DDTHH:MM:SSZ). 6. Sentiment scores range: -1.0 (negative) to 1.0 (positive). 7. Default sorting: published_at DESC (newest first). 8. Unknown parameters are rejected with an error (-32602) instead of being silently ignored — check the spelling against the list below. 9. By default the response returns id, title, href, published_at, description and source.domain. The article body is NOT included — request it explicitly with fl (e.g. fl: "title,href,body"). AVAILABLE PARAMETERS: ### Content Search - title: Search by article title (supports up to 3 keywords with comma separation) IMPORTANT: a title search covers at most a 31-day published_at window. Omit the dates and the last 31 days are searched; pass a range wider than 31 days and the call fails with 400 ER0110. To cover a longer period, make one call per month-sized window. - ignore: { title: "keyword" } - Exclude articles with specific titles ### Languages (60+ supported) - language: { code: "en,ru,fr" } - Filter by language codes (up to 3) - ignore: { language: { code: "fr" } } - Exclude specific languages ### Categories (IPTC taxonomy) - category: { id: "medtop:04000000" } - Filter by category ID (up to 3) - ignore: { category: { id: "315" } } - Exclude categories ### Topics - topic: { id: "crypto_news,climate_change" } - Filter by topic ID (up to 3) - ignore: { topic: { id: "2" } } - Exclude topics ### Industries - industry: { id: "246771,246772" } - Filter by industry ID (up to 3) - ignore: { industry: { id: "246772" } } - Exclude industries ### Entities - entity: { id: "1278268,1282301" } - Filter by entity ID (up to 3) - ignore: { entity: { id: "315" } } - Exclude entities ### Persons - person: { name: "Elon Musk,Tim Cook" } - Filter by person name (up to 3) - ignore: { person: { name: "John Doe" } } - Exclude persons ### Locations - location: { name: "Tokyo,New York" } - Filter by location (up to 3) - ignore: { location: { name: "Paris" } } - Exclude locations ### Organizations - organization: { name: "Tesla,Apple,Google" } - Filter by organization (up to 3) - ignore: { organization: { name: "Microsoft" } } - Exclude organizations ### Disasters - disaster: { name: "Earthquake,Tsunami" } - Filter by disaster type (up to 3) - ignore: { disaster: { name: "Flood" } } - Exclude disasters ### Diseases - disease: { name: "COVID-19,Influenza" } - Filter by disease (up to 3) - ignore: { disease: { name: "Flu" } } - Exclude diseases ### Events - event: { name: "Olympics,World Cup" } - Filter by event (up to 3) - ignore: { event: { name: "Super Bowl" } } - Exclude events ### Brands - brand: { name: "Nike,Adidas" } - Filter by brand (up to 3) - ignore: { brand: { name: "Puma" } } - Exclude brands ### Authors - author: { id: "123,456" } - Filter by author ID (up to 3) - author: { name: "John Doe,Jane Smith" } - Filter by author name (up to 3) - ignore: { author: { id: "789" } } - Exclude author IDs - ignore: { author: { name: "Bob Jones" } } - Exclude author names - has_author: 1 - Articles with attributed authors (0 for without) ### Sentiment Analysis - sentiment: { overall: { score: { min: 0.5, max: 1.0 } } } - Sentiment score range - sentiment: { overall: { polarity: "positive" | "negative" | "neutral" } } - Sentiment polarity - sentiment: { title: { score: { min: -1.0, max: 1.0 } } } - Title sentiment - sentiment: { body: { score: { min: -1.0, max: 1.0 } } } - Body sentiment - sentiment: { mixed: 1 } - Articles with mixed sentiment (title/body differ) - sentiment: { consistent: 1 } - Articles with consistent sentiment ### Media Content - media: { images: { count: { min: 2, max: 10 } } } - Filter by image count - media: { videos: { count: { min: 1 } } } - Filter by video count - media: { images: { width: { min: 1200, max: 1920 } } } - Filter by image width - media: { images: { height: { min: 800, max: 1080 } } } - Filter by image height - has_image: 1 - Articles with at least one image - has_video: 1 - Articles with at least one video - has_hq_images: 1 - Articles with high-quality images (width >= 1200px) - is_media_rich: 1 - Articles with both images and videos ### Source Filtering - source: { id: "314,315" } - Filter by source ID (up to 3) - source: { domain: "cnn.com,bbc.com" } - Filter by domain (up to 3) - source: { country: { code: "us,uk,de" } } - Filter by country (up to 3) - source: { rank: { opr: { min: 0.5, max: 0.9 } } } - OpenPageRank range (0-7) - source: { bias: "left,center,right" } - Filter by media bias (up to 3) - ignore: { source: { id: "315" } } - Exclude source IDs - ignore: { source: { domain: "example.com" } } - Exclude domains - ignore: { source: { country: { code: "fr" } } } - Exclude countries - ignore: { source: { bias: "left" } } - Exclude biases - is_premium_source: 1 - Premium sources (OPR >= 6) - is_verified_source: 1 - Verified sources (OPR >= 5, not duplicates) ### Date/Time Filtering - published_at: { start: "2024-01-01", end: "2024-01-31" } - Date range - published_at: "2024-09-26" - Specific date - Supported formats: YYYY-MM-DD, YYYY-MM-DDTHH:MM:SSZ, DD-MM-YYYY, RFC3339 - Max 31 days between start and end WHEN the same call also searches titles (title, ignore.title patterns or query); a wider range returns 400 ER0110. Without a title filter the range is unlimited. - An open-ended start ({ start: "2024-01-01" } with no end) runs to the current time, so with a title filter it exceeds the window too — always pair an archive start with an end date. ### Sorting - sort: { by: "published_at" | "created_at" | "source.rank.opr" | "read_time" | "sentiment.overall.score" | "sentiment.title.score" | "sentiment.body.score" | "media.images.count" | "media.videos.count" | "media.images.width.min" | "media.images.width.max" | "media.images.height.min" | "media.images.height.max" | "media_richness" | "relevance" | "engagement" | "quality" | "controversy" | "trust" } - sort: { order: "asc" | "desc" } - Advanced sorting: relevance (search ranking), engagement (viral potential), quality (editorial), controversy (polarization), trust (credibility) ### Pagination - page: 1 - Page number (default: 1) - per_page: 10 - Results per page (default: 10). One response carries at most 25 articles, so a larger per_page is clamped to 25 — use page to walk through more. ### Content Filters - is_duplicate: 0 - Exclude duplicates (0=unique, 1=include duplicates) - is_paywall: 0 - Exclude paywalled content (0=free, 1=paywall) - is_breaking: 1 - Breaking news only - read_time: { min: 1, max: 10 } - Filter by reading time (minutes) - is_long_read: 1 - Articles with read time >= 5 minutes - is_short_read: 1 - Articles with read time < 3 minutes ### Field Selection (fl) - Default (no fl): id, title, href, published_at, description, source.domain — body excluded - fl: "id,title,source.name,published_at" - Return only specific fields - fl: "title,href,body" - Ask for the full article text explicitly when you need to read it - Supports nested fields with dot notation: source.name, sentiment.overall.score ### Faceting - facet: true - Enable faceting - facet: { field: "source.id,language.id,sentiment.overall.polarity", limit: 20, mincount: 5 } - Supported facet fields: source.id, source.country.id, source.bias, category.id, topic.id, industry.id, language.id, author.id, sentiment.*.polarity, is_duplicate, is_free, is_important, media.images.count, media.videos.count, read_time, published.year, published.month, published.day_of_week, published.hour ### Range Faceting - facet: { range: { field: "published_at", start: "2024-01-01", end: "2024-12-31", gap: "1MONTH" } } - facet: { range: { field: "sentiment.overall.score", start: -1, end: 1, gap: 0.25 } } - Date gaps: 1HOUR, 1DAY, 1WEEK, 1MONTH, 1YEAR - Numeric gaps: 0.1, 0.25, 0.5, 1, 5, 10 ### Highlighting - hl: true - Enable highlighting - hl: { fl: "title,description,body", fragsize: 300, snippets: 5, tag: { pre: "<mark>", post: "</mark>" } } - Auto-expands search terms using synonyms and morphology QUERY BUILDING EXAMPLES: - Basic search: {title: "Bitcoin", language: {code: "en"}} - Sentiment analysis: {organization: {name: "Tesla"}, sentiment: {overall: {polarity: "positive"}}} - High-quality sources: {source: {rank: {opr: {min: 0.7}}}, is_verified_source: 1} - Date range (no title filter, so any width): {published_at: {start: "2024-01-01", end: "2024-12-31"}} - Title search over an archive month: {title: "Bitcoin", published_at: {start: "2024-01-01", end: "2024-01-31"}} - Multiple filters: {title: "AI", organization: {name: "Google,Microsoft"}, language: {code: "en"}, is_breaking: 1} - With media: {has_image: 1, media: {images: {count: {min: 2}}}} - Sorted by engagement: {sort: {by: "engagement", order: "desc"}} - With faceting: {facet: true, facet: {field: "source.id,language.id", limit: 10}} - With highlighting: {title: "innovation", hl: true, hl: {fl: "title,body"}} - Breaking news: {is_breaking: 1, sort: {by: "published_at"}} - Long-form quality: {is_long_read: 1, sort: {by: "quality", order: "desc"}}

{
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "Search by article title. Up to 3 keywords comma-separated (OR). Phrase in quotes for exact match."
    },
    "ignore": {
      "type": "object",
      "description": "Exclusion filters — exclude articles matching these. Mirror the positive filters.",
      "properties": {
        "title": {
          "type": "string",
          "description": "Exclude titles with these keyword(s), comma-separated."
        },
        "language": {
          "type": "object",
          "properties": {
            "code": {
              "type": "string"
            }
          }
        },
        "category": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            }
          }
        },
        "topic": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            }
          }
        },
        "industry": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            }
          }
        },
        "entity": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            }
          }
        },
        "person": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string"
            }
          }
        },
        "location": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string"
            }
          }
        },
        "organization": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string"
            }
          }
        },
        "disaster": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string"
            }
          }
        },
        "disease": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string"
            }
          }
        },
        "event": {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "description": "Exclude these event codes (max 5)."
            },
            "name": {
              "type": "string",
              "description": "Exclude these named events (up to 3)."
            }
          }
        },
        "brand": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string"
            }
          }
        },
        "author": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "name": {
              "type": "string"
            }
          }
        },
        "source": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "domain": {
              "type": "string"
            },
            "country": {
              "type": "object",
              "properties": {
                "code": {
                  "type": "string"
                }
              }
            },
            "bias": {
              "type": "string"
            }
          }
        }
      }
    },
    "language": {
      "type": "object",
      "description": "Language filter.",
      "properties": {
        "code": {
          "type": "string",
          "description": "ISO codes, comma-separated up to 3 (e.g. \"en,ru,fr\")."
        }
      }
    },
    "category": {
      "type": "object",
      "description": "IPTC category filter.",
      "properties": {
        "id": {
          "type": "string",
          "description": "Category id, e.g. \"medtop:04000000\". Comma-separated up to 3."
        }
      }
    },
    "topic": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "Topic id(s), comma-separated up to 3."
        }
      }
    },
    "industry": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "Industry id(s), comma-separated up to 3."
        }
      }
    },
    "entity": {
      "type": "object",
      "description": "Named-entity filter.",
      "properties": {
        "id": {
          "type": "string",
          "description": "Numeric entity id(s), comma-separated up to 3."
        }
      }
    },
    "person": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "Person name(s), comma-separated up to 3."
        }
      }
    },
    "organization": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "Organization name(s), comma-separated up to 3."
        }
      }
    },
    "location": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "Location name(s), comma-separated up to 3."
        }
      }
    },
    "disaster": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "Disaster name(s), comma-separated up to 3."
        }
      }
    },
    "disease": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "Disease name(s), comma-separated up to 3."
        }
      }
    },
    "event": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "description": "Event codes, comma-separated (max 5) — see /v1/news/event-types, e.g. layoffs, ipo, recall, wildfire."
        },
        "category": {
          "type": "string",
          "enum": [
            "business",
            "society",
            "environment"
          ],
          "description": "Event family."
        },
        "name": {
          "type": "string",
          "description": "Named event entity, comma-separated up to 3. The directory is nearly empty — prefer type/category; an unknown name returns 400 ER0228."
        }
      }
    },
    "brand": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "Brand name(s), comma-separated up to 3."
        }
      }
    },
    "source": {
      "type": "object",
      "description": "Source filter.",
      "properties": {
        "id": {
          "type": "string",
          "description": "Source id(s), comma-separated up to 3."
        },
        "domain": {
          "type": "string",
          "description": "Domain(s), e.g. \"cnn.com,bbc.com\"."
        },
        "country": {
          "type": "object",
          "properties": {
            "code": {
              "type": "string",
              "description": "Country code(s), e.g. \"us,uk,de\"."
            }
          }
        },
        "bias": {
          "type": "string",
          "enum": [
            "left",
            "center",
            "right"
          ],
          "description": "Media bias (comma-separated for multiple)."
        },
        "rank": {
          "type": "object",
          "properties": {
            "opr": {
              "type": "object",
              "description": "OpenPageRank range (0-7).",
              "properties": {
                "min": {
                  "type": "number"
                },
                "max": {
                  "type": "number"
                }
              }
            }
          }
        }
      }
    },
    "author": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "Author id(s), comma-separated up to 3."
        },
        "name": {
          "type": "string",
          "description": "Author name(s), comma-separated up to 3."
        }
      }
    },
    "sentiment": {
      "type": "object",
      "description": "Sentiment filter. Scores range -1.0..1.0.",
      "properties": {
        "overall": {
          "type": "object",
          "properties": {
            "polarity": {
              "type": "string",
              "enum": [
                "positive",
                "negative",
                "neutral"
              ],
              "description": "Overall sentiment polarity."
            },
            "score": {
              "type": "object",
              "properties": {
                "min": {
                  "type": "number"
                },
                "max": {
                  "type": "number"
                }
              }
            }
          }
        },
        "title": {
          "type": "object",
          "properties": {
            "score": {
              "type": "object",
              "properties": {
                "min": {
                  "type": "number"
                },
                "max": {
                  "type": "number"
                }
              }
            }
          }
        },
        "body": {
          "type": "object",
          "properties": {
            "score": {
              "type": "object",
              "properties": {
                "min": {
                  "type": "number"
                },
                "max": {
                  "type": "number"
                }
              }
            }
          }
        },
        "mixed": {
          "type": "integer",
          "enum": [
            0,
            1
          ],
          "description": "Title/body sentiment differ."
        },
        "consistent": {
          "type": "integer",
          "enum": [
            0,
            1
          ],
          "description": "Title/body sentiment agree."
        }
      }
    },
    "media": {
      "type": "object",
      "description": "Media-content filter.",
      "properties": {
        "images": {
          "type": "object",
          "properties": {
            "count": {
              "type": "object",
              "properties": {
                "min": {
                  "type": "integer"
                },
                "max": {
                  "type": "integer"
                }
              }
            },
            "width": {
              "type": "object",
              "properties": {
                "min": {
                  "type": "integer"
                },
                "max": {
                  "type": "integer"
                }
              }
            },
            "height": {
              "type": "object",
              "properties": {
                "min": {
                  "type": "integer"
                },
                "max": {
                  "type": "integer"
                }
              }
            }
          }
        },
        "videos": {
          "type": "object",
          "properties": {
            "count": {
              "type": "object",
              "properties": {
                "min": {
                  "type": "integer"
                },
                "max": {
                  "type": "integer"
                }
              }
            }
          }
        }
      }
    },
    "published_at": {
      "type": "object",
      "description": "Publication date range (ISO 8601).",
      "properties": {
        "start": {
          "type": "string",
          "description": "YYYY-MM-DD or RFC3339."
        },
        "end": {
          "type": "string",
          "description": "YYYY-MM-DD or RFC3339."
        }
      }
    },
    "sort": {
      "type": "object",
      "properties": {
        "by": {
          "type": "string",
          "enum": [
            "published_at",
            "created_at",
            "id",
            "source.rank.opr",
            "read_time",
            "sentiment.overall.score",
            "sentiment.title.score",
            "sentiment.body.score",
            "media.images.count",
            "media.videos.count",
            "media.images.width.min",
            "media.images.width.max",
            "media.images.height.min",
            "media.images.height.max",
            "media_richness",
            "shares.facebook.min",
            "shares.facebook.max",
            "shares.twitter.min",
            "shares.twitter.max",
            "shares.reddit.min",
            "shares.reddit.max",
            "relevance",
            "engagement",
            "quality",
            "controversy",
            "trust"
          ],
          "description": "Field to sort by."
        },
        "order": {
          "type": "string",
          "enum": [
            "asc",
            "desc"
          ],
          "description": "Sort direction."
        }
      }
    },
    "read_time": {
      "type": "object",
      "description": "Reading time in minutes.",
      "properties": {
        "min": {
          "type": "integer"
        },
        "max": {
          "type": "integer"
        }
      }
    },
    "facet": {
      "type": [
        "boolean",
        "object"
      ],
      "description": "Enable faceting (true) or object form for analytics.",
      "properties": {
        "field": {
          "type": "string",
          "description": "Facet field(s), comma-separated."
        },
        "limit": {
          "type": "integer"
        },
        "mincount": {
          "type": "integer"
        },
        "range": {
          "type": "object",
          "description": "Range faceting → facet.range.* params.",
          "properties": {
            "field": {
              "type": "string",
              "description": "Numeric/date field to bucket."
            },
            "start": {
              "type": "string"
            },
            "end": {
              "type": "string"
            },
            "gap": {
              "type": "string",
              "description": "e.g. \"1MONTH\" for dates or \"0.25\" for numbers."
            }
          }
        }
      }
    },
    "hl": {
      "type": [
        "boolean",
        "object"
      ],
      "description": "Enable highlighting (true) or object form.",
      "properties": {
        "fl": {
          "type": "string",
          "description": "Fields to highlight, comma-separated."
        },
        "fragsize": {
          "type": "integer"
        },
        "snippets": {
          "type": "integer"
        },
        "tag": {
          "type": "object",
          "properties": {
            "pre": {
              "type": "string"
            },
            "post": {
              "type": "string"
            }
          }
        }
      }
    },
    "has_image": {
      "type": "integer",
      "enum": [
        0,
        1
      ],
      "description": "Articles with at least one image."
    },
    "has_video": {
      "type": "integer",
      "enum": [
        0,
        1
      ],
      "description": "Articles with at least one video."
    },
    "has_hq_images": {
      "type": "integer",
      "enum": [
        0,
        1
      ],
      "description": "High-quality images (width >= 1200px)."
    },
    "is_media_rich": {
      "type": "integer",
      "enum": [
        0,
        1
      ],
      "description": "Both images and videos."
    },
    "has_author": {
      "type": "integer",
      "enum": [
        0,
        1
      ],
      "description": "Has an attributed author."
    },
    "is_breaking": {
      "type": "integer",
      "enum": [
        0,
        1
      ],
      "description": "Breaking news only."
    },
    "is_duplicate": {
      "type": "integer",
      "enum": [
        0,
        1
      ],
      "description": "0 to exclude duplicates."
    },
    "is_paywall": {
      "type": "integer",
      "enum": [
        0,
        1
      ],
      "description": "0 to exclude paywalled content."
    },
    "is_long_read": {
      "type": "integer",
      "enum": [
        0,
        1
      ],
      "description": "Read time >= 5 minutes."
    },
    "is_short_read": {
      "type": "integer",
      "enum": [
        0,
        1
      ],
      "description": "Read time < 3 minutes."
    },
    "is_premium_source": {
      "type": "integer",
      "enum": [
        0,
        1
      ],
      "description": "Premium sources (OPR >= 6)."
    },
    "is_verified_source": {
      "type": "integer",
      "enum": [
        0,
        1
      ],
      "description": "Verified sources (OPR >= 5)."
    },
    "page": {
      "type": "integer",
      "minimum": 1,
      "description": "Page number (default 1)."
    },
    "per_page": {
      "type": "integer",
      "minimum": 1,
      "maximum": 25,
      "description": "Results per page (default 10). One response carries at most 25 articles."
    },
    "fl": {
      "type": "string",
      "description": "Comma-separated fields to return (dot-notation supported), e.g. \"id,title,source.name,sentiment.overall.score\"."
    }
  },
  "required": [],
  "additionalProperties": true
}

Resolve a name or prefix to APITube taxonomy IDs so you can use them in the `search_news` tool's filters. The `search_news` tool's most precise filters require IDs you cannot guess: - entity.id — numeric (persons, organizations, locations, brands, events...) - category.id — IPTC slug, e.g. "medtop:04000000" - topic.id — slug - industry.id — numeric Use this tool FIRST to look those IDs up, then pass them into `search_news`. USAGE: - type: which taxonomy to autocomplete — one of "entities", "categories", "topics", "industries". - prefix: the name (or its beginning) to search, e.g. "Tesla", "Elon", "spo". Returns an array of matches; take the `id` of the best match and put it into `search_news`: suggest({ type: "entities", prefix: "Tesla" }) → [{ id: 12345, name: "Tesla, Inc.", ... }] search_news({ entity: { id: "12345" } })

{
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "enum": [
        "entities",
        "categories",
        "topics",
        "industries"
      ],
      "description": "Which taxonomy to autocomplete."
    },
    "prefix": {
      "type": "string",
      "description": "Name or prefix to search, e.g. \"Tesla\", \"Elon\", \"spo\"."
    }
  },
  "required": [
    "type",
    "prefix"
  ],
  "additionalProperties": false
}