Skip to navigation

Enrich one OpenRTB bid request in place

The SSP splice path. The body is a standard OpenRTB 2.6 bid request; only the documented input fields are read and everything else is preserved. On a hit, the response is the same bid request with the program-identity fields of app.content — id, title, series, episode, season, genre, cat, len, channel, livestream, contentrating, language — replaced atomically by the single best candidate: each is set to the resolved value or removed when resolved as absent, so no stale program facts from the request survive next to the resolution. Identity-neutral app.content fields and everything outside app.content are preserved untouched, and app.content.ext.openepg.attribution is set. season and cat belong to the replaced cluster but are never populated in v1, so a hit always removes them. Preservation is in meaning, not bytes: re-serialization may change encoding (key order, number formatting), never values — detect misses by reading the X-OpenEPG-Outcome header, not by byte-comparing bodies.

On a miss — and on a degraded resolution where the channel resolved but nothing airs at the lookup instant — the bid request comes back unchanged, HTTP 200. A channel-only splice next to foreign program fields is never produced.

Nothing is ever added to the body: no confidence, reason, notices, or debug — anything in this body must be assumed to enter the bidstream. The outcome and the confidence of the chosen candidate travel in X-OpenEPG-* response headers.

Exactly one candidate is used, always; there are no query parameters on this route. Passing a bid request that carries the needed identifier values (channel id, channel name, or show title) raises the precision of the enrichment — an app-only request on an aggregator app is a structured miss, never a guess. A supplied ext.pixalate.timestamp is honored on this route and on its batch variant: the resolution joins the schedule at that instant instead of at now, under the same window and clamping rules the lookup route applies. An instant outside the servable window is a 400 carrying TIMESTAMP_OUT_OF_WINDOW, never a silent substitution of now.

Authentication

x-api-keystring

Your Pixalate-provided API key, in the request header on every route. Credentials are never accepted in query parameters. An API key may be obtained by signing up for an account on the Pixalate developer website.

OR
AuthorizationBasic

Username/password alternative to the API-key header. Headers only — credentials are never accepted in query parameters.

Request

This endpoint expects an object.
appobjectRequired
deviceobjectRequired
extobjectOptional

Response headers

X-OpenEPG-OutcomestringOptional

HIT on a hit, or the miss reason code (APP_UNRESOLVED, OUT_OF_SCOPE, NO_COVERAGE, CHANNEL_UNRESOLVED, SHOW_UNRESOLVED).

X-OpenEPG-ConfidencestringOptional
Confidence of the spliced candidate, on a hit.
X-OpenEPG-NoticesstringOptional

Response-semantics notices, when any.

X-OpenEPG-Request-IdstringOptional
Request identifier echo, for support correlation.

Response

Enrichment performed. On a hit, the echoed bid request carries the resolved program in app.content; on a miss or a degraded resolution, the bid request is returned unchanged. Read the X-OpenEPG-Outcome header to distinguish the two without diffing the body.

appobject
deviceobject
extobjectOptional

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
413
Content Too Large Error
429
Too Many Requests Error
503
Service Unavailable Error