Resolve named identifiers to the best-matching program

post

https://epg-api.pixalate.com/v1/lookup

The flat REST path: one JSON object of named identifier parameters in, a
diagnostic envelope out. Each additional identifier parameter you provide
increases the precision of the results: bundle alone fully resolves
single-channel apps but returns a structured miss on aggregator apps; adding
channelId or channelName resolves the channel and joins the schedule at the
lookup instant; adding title resolves the program directly. One
uniform response shape covers every outcome — parts are populated or empty, never
reshaped.

Unlike the passthrough route, this route returns confidence and per-candidate
diagnostics in the body — use it for impression-log enrichment, DSP-side lookups,
and integration debugging. Both routes honor a supplied instant; this one reads it
from the flat timestamp field below. Pass verbose: true during integration
against an environment that offers the debug object: it shows exactly how each
input was read. The sandbox at dev-epg-api.pixalate.com offers it.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

One flat lookup: the identifier parameters as named fields plus the processing
controls. Each additional identifier parameter increases the precision of the
results. There is no user-agent field on this route — platform signal arrives as
the explicit os value.

bundle

string

required

Required. App store bundle/ID. Alone it fully resolves single-channel apps; on an aggregator (multi-channel) app with no channel or show identifier alongside it, the result is a structured CHANNEL_UNRESOLVED miss, never a guess.

channelId

string

Native/platform channel identifier, matched exactly against known identifiers (substring containment as a fallback). Strictly supersedes channelName — when present, the name is not consulted.

channelName

string

Channel display name (fuzzy name match). Consulted only when channelId is absent. Capped at 256 characters; longer values are truncated.

title

string

Show/program title. Fuzzy match, scoped to the declared app's catalog; a resolved show always carries its channel association. When the channel path and the show path disagree, the channel + timestamp result wins and this input is marked CONFLICT in verbose debug. Capped at 256 characters; longer values are truncated.

string

enum

Platform/OS, from a fixed enumerated vocabulary. An out-of-vocabulary value, including a different letter case, → 400 — never silently degraded. Omit the field for a platform not listed; resolution then runs against all platforms.

Allowed:

devicetype

integer

Optional OpenRTB device type. Accepted and retained for forward compatibility; not consulted by resolution during the beta.

timestamp

date-time

ISO 8601 UTC lookup instant; absent means now. Per item in batch, so an impression log enriches against the schedule as of each impression. Up to 5 minutes in the future clamps to now (TIMESTAMP_CLAMPED notice); further in the future, older than the 7-day window, or unparseable → 400.

verbose

boolean

Defaults to false

Ask for the debug object in the response. Whether the request is answered with one is a property of the environment: an environment that does not offer the debug object returns the ordinary envelope without it, and with nothing on the wire to say so. The sandbox at dev-epg-api.pixalate.com offers it.

Responses

200Lookup performed (hit or structured miss).

400Malformed request — a non-conforming body, a missing or empty required field, a read field of the wrong type, a timestamp violation (unparseable, more than 5 minutes in the future, or older than the 7-day window), an out-of-vocabulary os, or an exceeded batch cap.

401Missing or unknown credential.

403Known credential without entitlement to this product.

413The request body exceeded the maximum number of bytes this route accepts. Applies to the single (non-batch) operations; well below what a real payload from this route ever produces, so it signals a malformed or abusive request rather than an ordinary large one.

429Rate limit exceeded. Retry-After says when the window clears.

503Serving infrastructure degraded — the API fails closed and never masquerades as a data miss. Retry after the indicated delay.