Suggest Categories

The /v1/suggest/categories endpoint provides autocomplete functionality for searching categories by name prefix. It is useful for building filter interfaces: the returned id can be passed directly to the category.id parameter of the news endpoints.

To use the API, you'll require an API key. You can obtain an API key by signing up for an account on the APITube website.

Endpoint

GET /v1/suggest/categories

This endpoint returns a list of categories matching the provided name prefix.

Query Parameters

Parameter	Type	Required	Description
prefix	string	Yes	The name prefix to search for. Minimum 1 character.
api_key	string	Yes*	Your API key. Can also be provided via headers.

* Required if not provided in headers

Response Format

The endpoint returns an array of category objects with the following structure:

[
  {
    "id": 0,
    "name": "string",
    "taxonomy": "string",
    "links": {
      "self": "string"
    }
  }
]

Response Fields

Field	Type	Description
id	integer	Category identifier. Use it directly in the category.id filter.
name	string	Category name
taxonomy	string	Category taxonomy (e.g. iptc_mediatopics)
links.self	string	URL to get news articles in this category (/v1/news/category/{taxonomy}/{id})

Request Examples

Using query parameter

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

Using header authentication

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.apitube.io/v1/suggest/categories?prefix=politic"

Using Bearer token

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.apitube.io/v1/suggest/categories?prefix=econom"

Response Example

[
  {
    "id": 11100000,
    "name": "sport",
    "taxonomy": "iptc_mediatopics",
    "links": {
      "self": "https://api.apitube.io/v1/news/category/iptc_mediatopics/11100000"
    }
  }
]

Error Responses

Missing or Invalid API Key

{
  "errors": [
    {
      "code": "ER0201",
      "message": "API key is required. Provide it via X-API-Key header or api_key query parameter."
    }
  ]
}

Status Code: 401

Missing Prefix Parameter

{
  "errors": [
    {
      "code": "ER0346",
      "message": "`Prefix` in query required."
    }
  ]
}

Status Code: 400