Get articles by category with /v1/news/category/{taxonomy}/{category_id}

Get articles in a specific category with /v1/news/category/{taxonomy}/{category_id}. Add shared filters to narrow the results.

Each request costs 1 point. Using the prompt parameter adds 2 points; prompt requires Basic or above.

Endpoint

GET  /v1/news/category/{taxonomy}/{category_id}
POST /v1/news/category/{taxonomy}/{category_id}

Base URL: https://api.apitube.io. Example: /v1/news/category/iptc_mediatopics/medtop:04000000.

The directory supports four category systems: iptc_mediatopics, apitube, iab-qag and iptc-subjectcode. Category autocomplete searches all four. Only two currently return articles:

Taxonomy	Categories	Articles
iptc_mediatopics	1085	the classified archive
apitube	uncategorized only	~9.7M unclassified articles
iab-qag	IAB QAG codes (IAB12, IAB24, …)	none
iptc-subjectcode	legacy numeric subject codes	none

Categories from the two empty systems return no results. Check a category with /v1/news/count before using it in a feed. An unknown taxonomy name in the path returns 404 ER0242.

Path vs. the category.id filter

You can select a category in the URL path or with a filter:

	Path form	Filter form
Request	/v1/news/category/iptc_mediatopics/medtop:04000000	/v1/news/everything?category.id=medtop:04000000
Categories per request	One	Several, comma-separated
Exclusion	Not available	ignore.category.id
Unknown ID	404 ER0241	400 ER0206

Use the path for a single-category feed or page. Use category.id to combine categories or exclude them.

Where category IDs come from

• List of Categories — the full IPTC Media Topics tree.
• /v1/suggest/categories to suggest categories as a user types.
• The categories array of any article in a response; links.self there already contains a ready-made category URL.

Parameters

Path parameters

Parameter	Type	Required	Description
taxonomy	string	Yes	Category system, for example iptc_mediatopics.
category_id	string	Yes	Category ID.

See Filters for all shared search filters, sorting, pagination, field selection and other request options.

Response format

The response uses the shared Response format. See API Response Structure for all article fields.

Request examples

curl "https://api.apitube.io/v1/news/category/iptc_mediatopics/medtop:04000000?language.code=en&per_page=10&api_key=YOUR_API_KEY"

import requests

response = requests.get(
    "https://api.apitube.io/v1/news/category/iptc_mediatopics/medtop:04000000",
    params={"language.code": "en", "per_page": 10},
    headers={"X-API-Key": "YOUR_API_KEY"},
)

for article in response.json()["results"]:
    print(article["published_at"], article["title"])

const taxonomy = 'iptc_mediatopics';
const categoryId = 'medtop:04000000';

const response = await fetch(
  `https://api.apitube.io/v1/news/category/${taxonomy}/${encodeURIComponent(categoryId)}?language.code=en`,
  { headers: { 'X-API-Key': 'YOUR_API_KEY' } }
);

console.log((await response.json()).results.length);

---

Last 24 hours in a category, most engaging first

curl "https://api.apitube.io/v1/news/category/iptc_mediatopics/medtop:04000000?published_at.start=NOW-1DAY&sort.by=engagement&api_key=YOUR_API_KEY"

Errors

Code	Status	Meaning
ER0241	404	No category with that ID
ER0242	404	The category exists but not in the taxonomy given in the path
ER0175	401	API key is missing or invalid
ER0176	402	No points left on the account
ER0203	429	Rate limit exceeded

See HTTP response codes for the full error list.

Related

• Articles by topic and by industry for other ways to group news.
• List of Categories — every valid category ID.
• Search articles — combine several categories in one query.