How to filter news by topic#

To return only articles about a specific subject, add the topic.id parameter to your /v1/news/everything request with a topic identifier, for example topic.id=industry.crypto_news. The APITube News API matches it against the topics it tracks and returns only articles tagged with that topic. You can pass up to three topic IDs separated by commas, and articles tagged with any of them are returned (OR logic).

curl "https://api.apitube.io/v1/news/everything?topic.id=industry.crypto_news&api_key=YOUR_API_KEY"

You can send the key as a header (X-API-Key: YOUR_API_KEY) instead of the api_key query parameter. If you omit topic.id, no topic filter is applied and articles on every topic are returned.

What is the topic.id parameter?#

topic.id takes a topic identifier such as industry.crypto_news — a named subject tag, not a free-text keyword. Each value may be up to 80 characters; an empty or over-length value returns HTTP 400 with error ER0117. Every ID is looked up against the topics APITube tracks, and if one is not found the request fails with HTTP 400 and error ER0208 and a message like topic with ID 'foo' not found. The whole request stops on the first unknown topic, so one bad ID blocks the entire call.

Topics are a different layer from categories. A topic like industry.crypto_news is a specific subject tag, while a category is an IPTC media-topic code such as medtop:04000000. You can use both in the same request to combine a broad section with a precise subject.

How to filter by one or more topics#

Pass a single topic to read just that subject, or a comma-separated list to combine several. This request pulls articles tagged with either of two topics in one call:

curl "https://api.apitube.io/v1/news/everything?topic.id=industry.crypto_news,industry.financial_news&api_key=YOUR_API_KEY"

The maximum is three topics per request. If you list more than three, only the first three are used and the rest are silently dropped. Topic filtering is part of the shared filter chain, so it combines with other filters and with sorting:

curl "https://api.apitube.io/v1/news/everything?topic.id=industry.crypto_news&language.code=en&sort.by=published_at&sort.order=desc&api_key=YOUR_API_KEY"

How to exclude a topic#

To return everything except a subject, use ignore.topic.id. It follows the same rules — comma-separated, up to three values. This keeps general coverage while dropping crypto stories:

curl "https://api.apitube.io/v1/news/everything?ignore.topic.id=industry.crypto_news&api_key=YOUR_API_KEY"

As with the positive filter, an unknown ID in ignore.topic.id returns ER0209, and an empty or over-length value returns ER0120 — both HTTP 400. You can pass topic.id and ignore.topic.id in the same request to include one subject while excluding another.

How to find a valid topic.id#

Use the /v1/suggest/topics endpoint to look up topics before you filter. Pass a prefix and it returns matching topics, each with its id, name and a ready-made links.self URL:

curl "https://api.apitube.io/v1/suggest/topics?prefix=crypto&api_key=YOUR_API_KEY"

The prefix parameter is required; omitting it returns HTTP 400 with error ER0346. Take the id from a result and drop it straight into topic.id. The full set of supported topics is also listed in the APITube topics reference.

What does the topics object in the response contain?#

Every article in the response carries a topics array so you can see which subjects it was tagged with and reuse them:

{
    "topics": [
        {
            "id": "industry.crypto_news",
            "name": "Crypto News",
            "score": 0.82,
            "links": { "self": "https://api.apitube.io/v1/news/topic/industry.crypto_news" }
        }
    ]
}

The id here is exactly the value you pass back into topic.id for follow-up requests, name is the human-readable label, and score reflects how strongly the article matches that topic. The links.self URL points at the /v1/news/topic/{id} endpoint, which returns articles for that topic directly. To pin a topic to one publisher at the same time, combine it with How to filter news by source or domain.

Common Questions#

• How many topics can I filter by at once?
• What is the difference between a topic and a category?
• What error do I get for an unknown topic?
• How do I discover available topic IDs?

How many topics can I filter by at once?#

Up to three per parameter. topic.id and ignore.topic.id each accept a comma-separated list, and only the first three values are applied — extra values beyond the third are silently ignored. Multiple topics in one parameter use OR logic, so an article matches if it is tagged with any of them.

What is the difference between a topic and a category?#

A topic is a specific subject tag such as industry.crypto_news, filtered with topic.id. A category is a broad IPTC media-topic code such as medtop:04000000, filtered with category.id (see How to filter news by category). Use a category to scope a whole section like business, and a topic to zero in on a narrower subject within or across sections. Both can be combined in one request.

What error do I get for an unknown topic?#

A topic ID that APITube does not track returns HTTP 400 with error ER0208 (topic with ID '…' not found) for topic.id, or ER0209 for ignore.topic.id. An empty value or one longer than 80 characters returns ER0117 (ER0120 for the ignore variant). Because the request stops on the first bad ID, confirm the topic with /v1/suggest/topics before filtering.