News

Get articles by category

Returns articles for a specific category within a taxonomy. Supports the same filtering, faceting, highlighting, and export options as /v1/news/everything.

post/v1/news/category/{taxonomy}/{categoryId}

Request

  • Base URL: https://api.apitube.io
  • URL: https://api.apitube.io/v1/news/category/{taxonomy}/{categoryId}
  • Auth: one of:
    • API key in header X-API-Key
    • API key in query parameter api_key

Path parameters

taxonomystring required

Category taxonomy (e.g. iptc_mediatopics)

categoryIdstring required

Category ID

Request body

searchstring

Extra comma-separated terms to highlight in the response, on top of the terms taken from title. Affects highlighting only — it never filters results, and it needs hl=1 to have any effect.

hl'0' | '1' | 'true' | 'false'

Enable highlighting

hl.flstring

Comma-separated fields to highlight (max 5). Values: title, description, body

hl.fragsizeinteger

Size of highlighted fragment in characters (50-500)

hl.snippetsinteger

Number of highlighted snippets per field (max 10)

hl.tag.prestring

Opening tag for highlighted text

hl.tag.poststring

Closing tag for highlighted text

promptstring

Plain-language description of the news you want, e.g. "Elon Musk, Tesla, news for the last 10 days". It is translated into the regular filters below before the search runs, and the resulting parameters are returned in meta.prompt. Explicit parameters always win over the prompt. Costs 2 extra points when the wording has not been parsed before (repeats are served from cache). Available on Basic and above — on Free and Starter the request fails with 403 ER0706. Errors: ER0706 (plan), ER0800 (length), ER0801 (translation service unavailable), ER0802 (nothing usable in the prompt).

querystring

Boolean query language over the same fields as the flat filters: AND / OR / NOT, parentheses, field:value predicates, quoted phrases with proximity, ranges [a TO b] and target-aware entity blocks {{...}}. A bare term searches the title. Combined with any flat filters through AND, and bound by the same 31-day published_at window as title. Wildcards, fuzzy (~) and boost (^) are not supported — use title.starts_with / title.ends_with / title.pattern instead. Limits: 4000 characters, 64 predicates, nesting depth 10, 20 values per group. Parse and validation failures return 400 with ER0701–ER0706 and ER0710–ER0712.

pageinteger

Page number for pagination

per_pageinteger

Number of results per page (max 250; Free is capped at 10, Starter at 50, Basic at 200)

sort.by'published_at' | 'relevance' | 'engagement' | 'quality' | 'controversy' | 'trust' | 'id' | 'new' | 'created_at' | 'source.rank.opr' | 'sentiment.overall.score' | 'sentiment.title.score' | 'sentiment.body.score' | 'read_time' | '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'

Field to sort results by

sort.order'asc' | 'desc'

Sort order

article.idstring

Comma-separated article IDs (max 5)

titlestring

Search in article titles. Supports phrase search with proximity: "climate change"~2. Title search is limited to a 31-day published_at window: without published_at.start / published_at.end the last 31 days are searched, a wider explicit range returns ER0110.

ignore.titlestring

Exclude articles containing this text in the title

title_starts_withstring

Filter articles whose title starts with the given text. Same 31-day window limit as title

title_ends_withstring

Filter articles whose title ends with the given text. Same 31-day window limit as title

title_patternstring

Filter articles whose title matches the given pattern. Same 31-day window limit as title

published_atstring

Exact date (creates 24-hour range). Format: YYYY-MM-DD or ISO 8601

published_at.startstring

Start of date range. Format: YYYY-MM-DD or ISO 8601. Combined with a title search the range may not exceed 31 days (ER0110)

published_at.endstring

End of date range. Format: YYYY-MM-DD or ISO 8601. Combined with a title search the range may not exceed 31 days (ER0110)

language.codestring

Comma-separated ISO 639-1 language codes (max 3)

ignore.language.codestring

Exclude articles in these languages (comma-separated, max 3)

source.country.codestring

Filter by source country ISO 3166-1 alpha-2 codes (comma-separated, max 3)

ignore.source.country.codestring

Exclude sources from these countries (comma-separated, max 3)

source.rank.opr.mininteger

Minimum Open PageRank score

source.rank.opr.maxinteger

Maximum Open PageRank score

source.idstring

Comma-separated source IDs (max 3)

ignore.source.idstring

Exclude these source IDs (comma-separated, max 3)

source.domainstring

Comma-separated source domains (max 3)

ignore.source.domainstring

Exclude these source domains (comma-separated, max 3)

source.biasstring

Filter by media bias (comma-separated). Values: left, center, right

ignore.source.biasstring

Exclude sources with this media bias (comma-separated). Values: left, center, right

is_premium_source0 | 1

Filter by premium source status

is_verified_source0 | 1

Filter by verified source status

category.idstring

Comma-separated category IDs (max 3). IPTC MediaTopic slugs, e.g. medtop:04000000

ignore.category.idstring

Exclude these categories (comma-separated, max 3)

topic.idstring

Comma-separated topic IDs (max 3). Slugs from /v1/suggest/topics, e.g. industry.technology_news

ignore.topic.idstring

Exclude these topics (comma-separated, max 3)

industry.idstring

Comma-separated industry IDs (max 3)

ignore.industry.idstring

Exclude these industries (comma-separated, max 3)

entity.idstring

Comma-separated entity IDs (max 3)

ignore.entity.idstring

Exclude these entity IDs (comma-separated, max 3)

entity.sentiment.polarity'positive' | 'negative' | 'neutral'

Filter by sentiment polarity toward the entity. Requires an entity selector alongside it — entity.id, person.name, organization.name, location.name, brand.name, event.name, disease.name, disaster.name or sport.name; on its own the request fails with 400 ER0293.

entity.sentiment.score.minnumber

Minimum sentiment score toward the entity

entity.sentiment.score.maxnumber

Maximum sentiment score toward the entity

person.namestring

Filter by person name (comma-separated, max 3)

ignore.person.namestring

Exclude articles mentioning these persons (comma-separated, max 3)

organization.namestring

Filter by organization name (comma-separated, max 3)

ignore.organization.namestring

Exclude articles mentioning these organizations (comma-separated, max 3)

location.namestring

Filter by location name (comma-separated, max 3). Must match a known location entity — resolve the exact spelling with /v1/suggest/entities, otherwise the request returns 400 ER0218

ignore.location.namestring

Exclude articles mentioning these locations (comma-separated, max 3)

brand.namestring

Filter by brand name (comma-separated, max 3). Must match a known brand entity exactly — resolve the spelling with /v1/suggest/entities, otherwise the request returns 400 ER0222

ignore.brand.namestring

Exclude articles mentioning these brands (comma-separated, max 3)

disaster.namestring

Filter by natural disaster name (comma-separated, max 3). Must match a known disaster entity exactly — resolve the spelling with /v1/suggest/entities, otherwise the request returns 400 ER0224

ignore.disaster.namestring

Exclude articles mentioning these disasters (comma-separated, max 3)

disease.namestring

Filter by disease name (comma-separated, max 3). Must match a known disease entity exactly — resolve the spelling with /v1/suggest/entities, otherwise the request returns 400 ER0226

ignore.disease.namestring

Exclude articles mentioning these diseases (comma-separated, max 3)

event.namestring

Filter by event name (comma-separated, max 3). Must match a known event entity exactly — resolve the spelling with /v1/suggest/entities, otherwise the request returns 400 ER0228

ignore.event.namestring

Exclude articles mentioning these events (comma-separated, max 3)

sport.namestring

Filter by sport name (comma-separated, max 3). Must match a known sport entity exactly — resolve the spelling with /v1/suggest/entities, otherwise the request returns 400 ER0250

ignore.sport.namestring

Exclude articles mentioning these sports (comma-separated, max 3)

event.typestring

Comma-separated event types (max 5). Values: merger-acquisition, ipo, layoffs, bankruptcy, product-launch, funding-round, earnings, partnership, executive-change, lawsuit, data-breach, recall, expansion, closure, stock-movement, contract-award, spin-off, regulatory-action, election, protest, crime, terrorism, accident, policy-change, scandal, death, award-ceremony, conflict, diplomacy, health-crisis, migration, human-rights, earthquake, hurricane, flood, wildfire, tornado, tsunami, volcanic-eruption, drought, climate-event, pollution, wildlife-event, avalanche

event.category'business' | 'society' | 'environment'

Filter by event category

ignore.event.typestring

Exclude these event types (comma-separated, max 5)

sentiment.overall.scorenumber

Exact overall sentiment score

sentiment.overall.score.minnumber

Minimum overall sentiment score

sentiment.overall.score.maxnumber

Maximum overall sentiment score

sentiment.overall.polarity'positive' | 'negative' | 'neutral'

Overall sentiment polarity

sentiment.title.scorenumber

Exact title sentiment score

sentiment.title.score.minnumber

Minimum title sentiment score

sentiment.title.score.maxnumber

Maximum title sentiment score

sentiment.title.polarity'positive' | 'negative' | 'neutral'

Title sentiment polarity

sentiment.body.scorenumber

Exact body sentiment score

sentiment.body.score.minnumber

Minimum body sentiment score

sentiment.body.score.maxnumber

Maximum body sentiment score

sentiment.body.polarity'positive' | 'negative' | 'neutral'

Body sentiment polarity

sentiment.mixed0 | 1

Filter for mixed sentiment (title polarity != body polarity)

sentiment.consistent0 | 1

Filter for consistent sentiment (title polarity == body polarity)

is_clickbait0 | 1

Filter by clickbait detection

sentiment_gap.minnumber

Minimum sentiment gap between title and body

sentiment_gap.maxnumber

Maximum sentiment gap between title and body

media.images.countinteger

Exact number of images

media.images.count.mininteger

Minimum number of images

media.images.count.maxinteger

Maximum number of images

media.images.width.mininteger

Minimum image width in pixels

media.images.width.maxinteger

Maximum image width in pixels

media.images.height.mininteger

Minimum image height in pixels

media.images.height.maxinteger

Maximum image height in pixels

media.videos.countinteger

Exact number of videos

media.videos.count.mininteger

Minimum number of videos

media.videos.count.maxinteger

Maximum number of videos

has_image0 | 1

Filter articles with/without images

has_video0 | 1

Filter articles with/without videos

has_hq_images0 | 1

Filter articles with high-quality images (>= 1200px width)

is_media_rich0 | 1

Filter articles with both images and videos

is_landscape_media0 | 1

Filter articles with landscape-oriented media

is_portrait_media0 | 1

Filter articles with portrait-oriented media

has_multiple_images0 | 1

Filter articles with 2+ images

has_fullhd_images0 | 1

Filter articles with Full HD images (>= 1920px width)

has_4k_images0 | 1

Filter articles with 4K images (>= 3840px width)

has_mobile_optimized_images0 | 1

Filter articles with mobile-optimized images (320-800px width)

is_instagram_ready0 | 1

Filter articles with Instagram-ready images (>= 1080px + aspect ratio)

is_twitter_card_ready0 | 1

Filter articles with Twitter Card-ready images (>= 800px + landscape)

has_consistent_image_sizes0 | 1

Filter articles with consistent image dimensions

has_thumbnail0 | 1

Filter articles with thumbnail images (<= 300px width)

has_social_share_image0 | 1

Filter articles with social share images (>= 1200x630px)

has_mixed_media0 | 1

Filter articles with both image and video media types

readability.fk_gradenumber

Exact Flesch-Kincaid grade level

readability.fk_grade.minnumber

Minimum Flesch-Kincaid grade level

readability.fk_grade.maxnumber

Maximum Flesch-Kincaid grade level

readability.easenumber

Exact Flesch Reading Ease score

readability.ease.minnumber

Minimum Flesch Reading Ease score

readability.ease.maxnumber

Maximum Flesch Reading Ease score

readability.arinumber

Exact Automated Readability Index

readability.ari.minnumber

Minimum Automated Readability Index

readability.ari.maxnumber

Maximum Automated Readability Index

readability.difficulty'beginner' | 'intermediate' | 'advanced' | 'expert'

Difficulty level

readability.audience'children' | 'general' | 'professional' | 'academic'

Target audience

readability.ageinteger

Exact reading age

readability.age.mininteger

Minimum reading age

readability.age.maxinteger

Maximum reading age

is_easy_read0 | 1

Filter for easy-to-read articles (Flesch Reading Ease >= 60)

is_difficult_read0 | 1

Filter for difficult-to-read articles (Flesch Reading Ease < 40)

read_timeinteger

Exact read time in minutes

read_time.mininteger

Minimum read time in minutes

read_time.maxinteger

Maximum read time in minutes

is_long_read0 | 1

Filter for long reads (>= 5 minutes)

is_short_read0 | 1

Filter for short reads (< 3 minutes)

is_quick_read0 | 1

Filter for quick reads (<= 2 minutes)

is_medium_read0 | 1

Filter for medium-length reads (3-7 minutes)

is_deep_dive0 | 1

Filter for deep dives (>= 10 minutes)

location.bboxstring

Bounding box: minLat,maxLat,minLng,maxLng

has_location_geo0 | 1

Filter articles with/without geo-location data

location.latnumber

Latitude for radius search

location.lngnumber

Longitude for radius search

location.radiusnumber

Search radius in kilometers (requires location.lat and location.lng)

location.radius.minnumber

Minimum distance from point in km

is_duplicate0 | 1

Filter duplicate/unique articles

is_paywall0 | 1

Filter paywalled articles

is_breaking0 | 1

Filter breaking news articles

is_high_quality0 | 1

Filter high-quality articles (not duplicate, rank >= 5, has images, has author)

author.idstring

Comma-separated author IDs (max 3)

ignore.author.idstring

Exclude these author IDs (comma-separated, max 3)

author.namestring

Filter by author name (comma-separated, max 3)

ignore.author.namestring

Exclude articles by these authors (comma-separated, max 3)

has_author0 | 1

Filter articles with/without author

facet'0' | '1' | 'true' | 'false'

Enable faceting

facet.fieldstring

Comma-separated facet fields (max 5). Values: source.id, source.country.id, source.bias, language.id, author.id, category.id, topic.id, industry.id, entity.id, sentiment.overall.polarity, sentiment.title.polarity, sentiment.body.polarity, sentiment.strength, is_duplicate, is_free, is_important, media.images.count, media.videos.count, read_time, content.length, published.year, published.month, published.day_of_week, published.hour, published.weekday, published.time_of_day

facet.limitinteger

Maximum number of facet values per field (max 100)

facet.mincountinteger

Minimum count for a facet value to be included

facet.range'0' | '1' | 'true' | 'false'

Enable range faceting

facet.range.fieldstring

Field for range faceting. Values: published_at, sentiment.overall.score, sentiment.title.score, sentiment.body.score, read_time, source.rank.opr, media.images.count, media.videos.count

facet.range.startstring

Start value for range faceting (required with facet.range)

facet.range.endstring

End value for range faceting (required with facet.range)

facet.range.gapstring

Gap value for range faceting

export'json' | 'csv' | 'tsv' | 'xml' | 'rss' | 'xlsx' | 'parquet' | 'jsonl' | 'ndjson'

Export format

flstring

Comma-separated list of fields to include in the response

debug'0' | '1' | 'true' | 'false'

Include user_input in response for debugging

api_keystring

API key (alternative to X-API-Key header)

Example request

{
  "search": "tesla,elon musk",
  "hl.fl": "title,description",
  "query": "bitcoin AND NOT (etf OR futures)",
  "article.id": "12345",
  "published_at": "2025-01-15",
  "published_at.start": "2025-01-01",
  "published_at.end": "2025-01-31",
  "language.code": "en",
  "ignore.language.code": "zh,ar",
  "source.country.code": "us",
  "ignore.source.country.code": "us",
  "source.id": "100",
  "source.domain": "nytimes.com",
  "source.bias": "left",
  "ignore.source.bias": "right",
  "category.id": "medtop:04000000",
  "topic.id": "industry.technology_news",
  "industry.id": "1",
  "entity.id": "12345",
  "person.name": "Elon Musk",
  "organization.name": "Google",
  "location.name": "New York City",
  "event.type": "ipo",
  "location.bbox": "40.0,41.0,-74.5,-73.5",
  "facet.field": "source.id,category.id",
  "fl": "id,title,published_at,source.domain"
}

Response

Successful response with articles

status'ok' required

Response status

limitinteger required

Results per page

pathstring required

Current request URL

pageinteger required

Current page number

has_next_pagesboolean required

Whether more pages are available

next_pagestring

URL for the next page (empty if no next page)

has_previous_pageboolean required

Whether a previous page exists

previous_pagestring

URL for the previous page (empty if no previous page)

request_idstring required

Unique request identifier

facetsobject

Facet results (present when facet.field is specified)

highlightingobject

Highlighting results (present when hl=1)

headlinesobject[]

Headlines (present in some responses)

user_inputobject

Debug info — original request parameters (present when debug=1)

Changes

No recorded changes to this operation across all 1 revision of this API.