Content Recommendations API filters

What it is

Scope recommendations to a specific section, content type, or both — before personalization runs — so your users only see candidates that belong in the placement.

Every call to GET /recommend/v1/recommendations runs in two stages:

Pre-personalization filtering — narrow the universe of candidate items down to the slice that is eligible for the request (this document).
Editorial reranking — apply newsroom signals on top of the model’s ranking (see Editorial Signals).

Pre-filters are more efficient than excluding the same items in your own client code: items that don’t match are never scored, never returned, and never compete with matching items for the slot.

The filter dimensions

Query param	Required	Effect
`site_id`	yes	Hard partition by website. A single tenant may host many sites; this scopes the catalog.
`section`	no	Editorial section (e.g. politics, sports). Restricts to items tagged with that category.
`content_type`	no	Content type (e.g. article, video, podcast). Restricts to items of that type.

Examples

Homepage feed for an anonymous reader on the news site:

GET /recommend/v1/recommendations
  ?site_id=news.example.com
  &user_id=anon-abc-123
  &num_results=10

Selects filter_base. Returns up to 10 free items from news.example.com.

Sports section page:

GET /recommend/v1/recommendations
  ?site_id=news.example.com
  &user_id=u-42
  &section=sports
  &num_results=20

Returns up to 20 items in the sports category.

Video-rail module on the homepage:

GET /recommend/v1/recommendations
  ?site_id=news.example.com
  &user_id=u-42
  &content_type=video
  &num_results=8

Returns up to 8 video items only.

Politics-section video rail:

GET /recommend/v1/recommendations
  ?site_id=news.example.com
  &user_id=u-42
  &section=politics
  &content_type=video
  &num_results=6

Returns up to 6 politics videos.

Key details

No model changes needed. Adjustments to filtering happen at the point of serving recommendations: the underlying model stays completely intact.
Content is always scoped to your site. Every request is automatically limited to your site’s catalog.
Extra candidates are fetched behind the scenes. The system requests more results than you asked for, so that editorial exclusions and pinned items can be applied without leaving gaps in the final response.
Filter values must match exactly. Filters look for precise matches only: no partial or fuzzy matching. If your content taxonomy uses nested categories (e.g. sports/nfl/scores), make sure values are fully resolved before sending them.

Quick API reference

GET /recommend/v1/recommendations

Parameter	Type	Default	Notes
`site_id`	string	—	Required. Partitions the catalog by website.
`user_id`	string	—	Required. Personalization key.
`item_id`	string	—	Optional. Anchor item for “more like this”.
`num_results`	int	5	1–50.
`section`	string	—	Editorial section.
`content_type`	string	—	Content type.