Content Recommendations API Reference

The Content Recommendations platforms offers two APIs:

Collector API — ingests content metadata and user behavior events.
Recommender API — serves personalized recommendations.

Server

https://{org}-config-prod.api.arc-cdn.net/

Variable	Description	Default
`org`	Organization identifier	`org`

Endpoints overview

Method	Path	Summary
`POST`	`/collector/v1/content`	Ingest Content
`POST`	`/collector/v1/events`	Ingest Event
`POST`	`/collector/v1/events/batch`	Ingest Events Batch
`GET`	`/recommend/recommendations`	Get Recommendations

Collector API

`POST /collector/v1/content`

Ingest content metadata. The request body accepts either an UpsertContent payload (publish or update an item) or a DeleteContent payload (remove an item from the catalogue), discriminated by the action field.

Tags: Collector, Content

Request body

application/json — one of UpsertContent or DeleteContent.

Responses

Status	Description	Schema
`202`	Accepted. The request is queued for asynchronous processing.	—
`422`	Validation Error	`HTTPValidationError`

Example — publish

{
  "action": "publish",
  "item_id": "ZSGXFR2KNFCMPN3VHPWQR3BGCE",
  "site_id": "site-1",
  "type": "article",
  "timestamp": "2026-03-27T14:30:00+00:00",
  "title": "Election results, day three",
  "categories": ["Politics"],
  "tags": ["election-2026", "results"],
  "author": "Jane Doe",
  "is_premium": false,
  "metadata": {}
}

Example — delete

{
  "action": "delete",
  "item_id": "ZSGXFR2KNFCMPN3VHPWQR3BGCE",
  "site_id": "site-1"
}

`POST /collector/v1/events`

Ingest a single user-behavior event.

Tags: Collector, Events

Request body

application/json — FYEventEnvelope.

Responses

Status	Description	Schema
`202`	Accepted. The event is queued for asynchronous processing.	—
`422`	Validation Error	`HTTPValidationError`

Example

{
  "user_id": "abc-123",
  "item_id": "ZSGXFR2KNFCMPN3VHPWQR3BGCE",
  "event_type": "video_progress",
  "timestamp": "2026-03-27T14:32:00+00:00",
  "event_value": 0.75,
  "session_id": "sess-a1b2c3"
}

`POST /collector/v1/events/batch`

Ingest a batch of user-behavior events in a single request.

Tags: Collector, Events

Request body

application/json — array of FYEventEnvelope.

Responses

Status	Description	Schema
`202`	Accepted. All events are queued for asynchronous processing.	—
`422`	Validation Error	`HTTPValidationError`

Example

[
  {
    "user_id": "abc-123",
    "item_id": "ZSGXFR2KNFCMPN3VHPWQR3BGCE",
    "event_type": "page_view",
    "timestamp": "2026-03-27T14:30:00+00:00"
  },
  {
    "user_id": "abc-123",
    "item_id": "ZSGXFR2KNFCMPN3VHPWQR3BGCE",
    "event_type": "video_progress",
    "timestamp": "2026-03-27T14:32:00+00:00",
    "event_value": 0.75,
    "session_id": "sess-a1b2c3"
  }
]

Recommender API

`GET /recommend/recommendations`

Return a ranked list of recommended items for a user on a given site.

Tags: Recommendations

Query parameters

Name	Type	Required	Default	Description
`site_id`	string	yes	—	Site scoping — used to partition content and signals by website.
`user_id`	string	yes	—	Identifier of the user receiving recommendations.
`item_id`	string \| null	no	—	Anchor item for “more like this” use cases.
`num_results`	integer (1–50)	no	`5`	Number of recommendations to return. Capped at 50 to keep response payloads bounded.
`subscription_tier`	string \| null	no	—	Caller subscription level (e.g. `"free"`, `"premium"`).
`device_type`	string \| null	no	—	Requesting device class (e.g. `"mobile"`, `"desktop"`).

Responses

Status	Description	Schema
`200`	Successful Response	`RecommendationResponse`
`422`	Validation Error	`HTTPValidationError`

Example response

{
  "recommendations": [
    {
      "item_id": "ZSGXFR2KNFCMPN3VHPWQR3BGCE",
      "score": 0.91
    },
    {
      "item_id": "JYRPLD7XKVAU2NHM4FZQ6BTACE",
      "score": 0.84
    }
  ]
}

Schemas

Content schemas

`UpsertContent`

Request body for adding or updating a content item.

Field	Type	Required	Default	Description
`action`	`"publish"` (literal)	yes	—	Discriminator value.
`item_id`	string	yes	—	Stable item identifier.
`site_id`	string	yes	—	Site this item belongs to.
`type`	`ItemType`	yes	—	Content type classification.
`timestamp`	string (ISO 8601, timezone-aware)	yes	—	Publication date.
`title`	string	yes	—	Display title.
`categories`	string[]	no	—	High-level taxonomy (e.g. `Politics`, `Sports`).
`tags`	string[]	no	—	Detailed keywords.
`author`	string \| null	no	—	Content creator.
`is_premium`	boolean	no	`false`	Whether content is behind a paywall.
`metadata`	object	no	—	Flexible tenant-specific fields (additional properties allowed).

`DeleteContent`

Request body for deleting a content item.

Field	Type	Required	Description
`action`	`"delete"` (literal)	yes	Discriminator value.
`item_id`	string	yes	Identifier of the item to delete.
`site_id`	string	yes	Site the item belongs to.

`ItemType`

Content type classification for items. Enum.

Value
`article`
`video`
`podcast`

Event schemas

`FYEventEnvelope`

Canonical representation of an inbound CDP event. All CDP vendor adapters must produce this shape.

Field	Type	Required	Description
`user_id`	string	yes	Identifier of the user who triggered the event.
`item_id`	string	yes	Item the user interacted with.
`event_type`	`EventType`	yes	Type of interaction.
`timestamp`	string (ISO 8601, timezone-aware)	yes	When the interaction occurred.
`event_value`	number \| null	no	Numeric value (e.g. watch percentage `0.0`–`1.0`).
`session_id`	string \| null	no	Session identifier for grouping interactions.

Examples

{
  "event_type": "page_view",
  "item_id": "ZSGXFR2KNFCMPN3VHPWQR3BGCE",
  "timestamp": "2026-03-27T14:30:00+00:00",
  "user_id": "abc-123"
}

{
  "event_type": "video_progress",
  "event_value": 0.75,
  "item_id": "ZSGXFR2KNFCMPN3VHPWQR3BGCE",
  "session_id": "sess-a1b2c3",
  "timestamp": "2026-03-27T14:32:00+00:00",
  "user_id": "abc-123"
}

`EventType`

Types of user interactions captured by the system. Enum.

Value
`page_view`
`click`
`video_start`
`video_complete`
`video_progress`
`search`
`share`

Recommendation schemas

`RecommendationResponse`

Top-level response envelope for the recommendations endpoint.

Field	Type	Required	Description
`recommendations`	`ScoredItem`[]	yes	Recommended items, ordered by adjusted score.

`ScoredItem`

A single recommended item with its adjusted score. Score reflects post-reranking state — editorial signals (boosts, buries, pins) have already been applied by the time this is returned to the caller.

Field	Type	Required	Description
`item_id`	string	yes	CMS item identifier.
`score`	number	yes	Adjusted recommendation score (post-reranking), ranging from `0.0` to `1.0`.

Error schemas

`HTTPValidationError`

Returned when request validation fails (HTTP 422).

Field	Type	Required	Description
`detail`	`ValidationError`[]	no	One entry per failed validation rule.

`ValidationError`

Detail entry for a single failed validation rule.

Field	Type	Required	Description
`loc`	(string \| integer)[]	yes	Location of the offending field (e.g. `["body", "item_id"]`).
`msg`	string	yes	Human-readable error message.
`type`	string	yes	Error type identifier (e.g. `value_error.missing`).
`input`	any	no	The input value that failed validation.
`ctx`	object	no	Additional error context.