Editorial Signals in the Content Recommendations API

Overview

Editorial Signals are a layer of human-controlled ranking rules that sit on top the Content Recommendation API’s machine-learned recommendations.

They let your newsroom override, nudge, or filter the model’s output without retraining anything: the changes take effect on the very next recommendation request.

In short: AI decides what is likely to engage a given reader; signals decide what is editorially encouraged, discouraged, or required for that reader to see (or not see).

Signals are exposed through a dedicated service: the Signals API (/signals/v1).

The four signal types

There are four distinct signal types. Each one answers a different editorial question.

Signal type	Editorial question	Effect on the ranked list
Boost	”I want this to do better than the model thinks it will.”	Multiplies the item’s AI score by a weight between 1.0 and 10.0. Item rises naturally in the ranking.
Bury	”I want this to do worse than the model thinks it will.”	Multiplies the item’s AI score by a weight between 0.0 and 0.9. Item falls in the ranking but isn’t removed.
Pin	”This item must appear at position N.”	Forces the item into a specific 1-indexed slot, even if the content was not included in the preliminary candidate set. An absolute position override.
Exclude	”This item must not appear at all, regardless of relevance.”	Removes the item from the candidate set entirely. Takes precedence over every other signal, including Pin.

Boost and Bury are soft — they bias the ranking. Pin and Exclude are hard — they override it. The reranker applies them in a deterministic order (exclude → boost/bury → sort → pin → truncate), so the outcome is predictable no matter how many signals stack up on the same response.

Two ways to drive signals

The Signals API is intentionally agnostic about who is creating signals. That gives you two complementary integration patterns, and most newsrooms will run both at once.

1. Rules-based, automated from the content ingestion process

This pattern produces signals as a side effect of content moving through your CMS or content pipeline. It is best for organization-wide editorial policy: rules that should always be true without anyone clicking a button.

There’s no user interface to manage rules, so implementing these within custom middleware code is required.

For Arc XP customers, that will typically entail extending the content synchronization integration to set Signals during the content ingest/update moment.

Common examples:

• Always favor staff-bylined content. When a story is ingested with a staff byline, your ingestion worker calls POST /signals/v1/signals with a boost of, say, 1.5. Wire content from outside the newsroom no longer competes on equal footing with staff-produced reporting.
• Promote breaking news automatically. When the CMS flags a story as breaking, your pipeline opens a boost signal with a higher weight (e.g. 5.0) and a short end_at window — typically 30 to 90 minutes. The story floods every reader’s feed for the duration of the breaking-news window and quietly steps back to AI-only ranking when it expires.
• Enforce content category policy. Suppress unloved content categories during specific dayparts using a bury with a weight of 0.3 and a scheduled start_at/end_at.

2. Manual, driven by editorial curation tools

This pattern produces signals from a person clicking a button. It is best for moment-to-moment editorial judgment.

Note

The following examples reference user interface elements that are not yet available within Arc XP. To offer Manual Editorial Configuration Tools, customers on Arc XP can leverage WebSked pitching to trigger an IFX integration that invokes the relevant Signals API.

Customers leveraging a different content management system can build out their own user interface within the content management system or within Microsoft Teams or Slack as desired.

Common examples:

• Highlight a single story. A homepage editor clicks “Pin to slot 1” on a developing investigation. The curation tool calls POST /signals/v1/signals with signal_type: "pin" and position: 1. From that moment on, every reader’s personalized recommendation list opens with that story.
• Quietly suppress a story. Legal asks for a piece to be pulled from recommendations while a correction is drafted. An editor clicks “Hide from recommendations.” The curation tool creates an exclude signal. The story remains published and linkable, it just stops appearing in any Content Recommendations-driven module until the signal is removed.
• Counter-program the algorithm. A producer notices that the model is over-saturating one beat. They apply a short-lived bury to two or three specific items to rebalance the page in real time.
• Time-boxed promotion. A live blog or live event needs to dominate the page for the duration of the event. Editorial sets a pin with start_at = event start, end_at = event end. The pin self-removes when the event ends.

What this looks like at runtime

When a reader requests recommendations, the Recommender API:

1. Asks the AI model’s top candidates and scores.
2. Loads every active signal.
3. Hands the candidate list and the signals to the reranker, which:
   • Drops any item under an active exclude signal.
   • Multiplies each remaining item’s score by its boost or bury weight.
   • Re-sorts by the adjusted score.
   • Inserts pin signals at their absolute positions (and synthesizes a coherent score so the response is internally consistent).
   • Truncates to the requested page size.
4. Returns the final list.

No model retraining. No batch job. No cache to bust.

The signal you wrote a second ago is the signal that ranks the next request.

Scheduling

Every signal supports optional start_at and end_at timestamps:

• start_at — the signal does nothing until this time. Useful for scheduled promotions, or pre-staging top-news rules ahead of a known event.
• end_at — the signal stops applying at this time without you having to call back to delete it. Critical for breaking-news boosts (which should decay, not linger) and any time-boxed editorial campaign.

A signal with neither field is active immediately and active forever, until explicitly deleted via DELETE /signals/v1/signals/{id}.

Site isolation

All signals are scoped to a single site within your instance. You can boost, bury, pin, and exclude items in the context of one site without impacting any others.

Operational properties

• No retraining required. Signals are pure post-processing.
• Bounded volume. The list endpoint returns all matching signals in one response, because the reranker already loads the full set on every recommendation request.
• Editorial provenance. Every signal records its created_by and created_at timestamp, so it is always possible to audit who applied what override and when.
• Reversible. Deleting a signal restores pure AI ranking for that item on the next request. There is no “soft delete,” the change is immediate and complete.

When not to use signals

Signals are a precision tool. They are not a substitute for:

• Removing content from the index — if a story is unpublished, it should leave the content collection through normal CMS lifecycle, not via a permanent exclude signal.

Quick API reference

All endpoints are under /signals/v1 and require tenant-scoped authentication.

Method	Path	Purpose
POST	/signals	Create a signal. Body: site_id, item_id, signal_type, optional weight / position / start_at / end_at.
GET	/signals	List signals for the tenant. Optional filters: site_id, item_id, signal_type.
GET	/signals/{id}	Fetch a single signal.
DELETE	/signals/{id}	Remove a signal. Effective on the next recommendation request.