SceneContext · Partner integration

Enrichment API Handbook

Send one OpenRTB bid request. Get verified programme metadata back in the same HTTP response — contextual segments, IAB subcategories, normalised genres and a persistent content id.

Endpoint

POST https://rtd.scenecontext.io/v1/enrich

Auth

Bearer token, or ?api_key=

Body

OpenRTB 2.x bid request, up to 64 KB

Latency

p50 5 ms · p95 8 ms · p99 20 ms, in-region

Your key decides the contract

Three things behave differently depending on the profile behind your API key: what happens the first time we see a piece of content, what an unmatched request looks like, and which response shape you get. Everything else on this page is the same for everyone. Check which mode your key uses before you write the client — the retry logic differs.

The second setting is what an unmatched request looks like. Most profiles return 204 with no body. Some return 200 with {} instead, so that a match failure is never confusable with a transport error. Both are deliberate answers, not errors.

Integration options

Most partners integrate over HTTP and never need anything else. The rest exist because an exchange or a bidder already speaks something specific, and we would rather match it than ask you to build an adapter.

What we can tailor to you

Everything in this table is a setting on your key — not a code change on either side — and it takes effect within about fifteen seconds of us making it. If something here is wrong for you, it is a conversation, not a project.

This is not theoretical. Four partners run on this today and no two of them see the same response: one sends a GET and receives a bare list of ids, one receives protobuf on a seven-millisecond budget, one receives a complete OpenRTB content object. Same service, four contracts.

Authentication

Either form works on every endpoint. Use the header in production; the query parameter exists for environments where you cannot set headers.

Authorization: Bearer sc_dsp_xxxxxxxxxxxxxxxxxxxxxxxx

POST /v1/enrich?api_key=sc_dsp_xxxxxxxxxxxxxxxxxxxxxxxx

A missing or wrong key returns 401 with no body worth parsing. Keys carry your profile, your rate limit and your response format — treat them as environment-specific.

Request

POST the bid request as you received it from the exchange. No transformation on your side: we read the content object and ignore the rest. The content object is accepted at the top level or nested under app or site — both resolve identically.

Live channel

{
  "app":     { "bundle": "com.example.ctvapp" },
  "content": {
    "livestream": 1,
    "channel": { "id": "SPORT1.de", "name": "SPORT1" },
    "genre":   "sport"
  },
  "device":  { "geo": { "country": "DEU" } }
}

On-demand title

{
  "app":     { "bundle": "com.example.ctvapp" },
  "content": {
    "title":  "Mord mit Aussicht",
    "series": "Mord mit Aussicht",
    "genre":  "krimi"
  }
}

What we read

Response

Flat JSON by default. Fields are omitted when there is nothing behind them, so tolerate absence rather than expecting a fixed shape.

HTTP/1.1 200 OK
Cache-Control: max-age=86400

{
  "scid":     "SC4mNpQr7xKj2wBv-0",
  "segments": ["SC_TOPIC_ENTERTAINMENT_CRIME", "SC_GENRE_CRI_001",
               "SC_CHANNEL_DE_SPORT1", "SC_CTX_SAFE_PREMIUM"],
  "iab":      ["KHPC5A", "647"],
  "genres":   ["Crime", "Drama"],
  "signal_quality": { "score": 0.88 },
  "mood":     "tense",
  "audience": "general",
  "contextual_score": 0.71,
  "keywords": "ermittlung,kleinstadt,kommissarin"
}

Alternative response shapes are a profile setting, not a code change on your side: a ready-to-merge OpenRTB content.data[] block, a complete content object, or a bare segment id list. Ask and we switch your key.

Live channel

A live request resolves against the schedule rather than the title catalogue, and the answer describes the programme airing at that moment. Four fields are live-only: mood, audience, contextual_score and keywords all describe what is on air right now, not the channel in general.

HTTP/1.1 200 OK
Cache-Control: max-age=86400

{
  "segments": ["SC_CHANNEL_DE_SPORT1", "SC_TOPIC_SPORT_FOOTBALL",
               "SC_GENRE_SPO_001", "SC_CTX_TIMEOFDAY_EVENING",
               "SC_CTX_SAFE_PREMIUM"],
  "genres":   ["Sport"],
  "iab":      ["483"],
  "signal_quality": { "score": 0.91 },
  "mood":     "energetic",
  "audience": "sports_fan",
  "contextual_score": 0.78,
  "keywords": "bundesliga,spieltag,analyse",
  "epg":      { "status": "covered", "slot_end": 1790199000 }
}

The optional epg block answers a question the segments cannot: whether we hold schedule coverage for this channel at all. status: "covered" with a slot_end means a live slot resolved and tells you when it turns over — cache no further than that. channel_unknown means we do not carry this channel, which is a signal to send us the channel id or ask us to add the feed, not a transient failure.

Segment families

The live vocabulary is available at /v1/reference/segments — fetch it rather than hard-coding a snapshot.

Status codes

The two meanings of 204

Latency and your timeout

These hold for every response — enriched, no-match and first-sight alike. Calling from another data centre adds your network round trip; cross-region within the EU is typically 20 to 30 ms on top. The TLS handshake costs about 50 ms once per connection, so use a shared client with keep-alive.

Where we run

The published figures above are for a caller in the same region. If your bidders sit somewhere else, the network round trip is added on top and it will dominate everything we do. That is worth solving at the deployment layer rather than in the API.

Each serving node is self-sufficient — it answers from local data, with no call to a central service on the request path — which is what makes putting one next to you a deployment decision rather than an architecture change. Tell us the region and the network you bid from and we will tell you which of the three applies and what latency to write into the contract.

Caching

On-demand content is cacheable per content for about 24 hours, and the header says so explicitly. Because scid is stable across publishers, one resolution serves every request for the same programme wherever it airs.

Reference endpoints

Automate your channel mapping instead of consuming snapshots. Same auth and rate limit as enrich.

Both send an ETag keyed to the underlying data version. Poll with If-None-Match and you get a cheap 304 until something actually changes.

Data freshness

• Schedule — rebuilt and promoted every 2 hours on a rolling air window. A programme is resolvable while it airs.
• Serving nodes — pull new data every 15 minutes.
• Title catalogue and segment definitions — promoted on change, continuously.

First call

Confirm your key and environment before writing any integration code. On a test key the response carries "_env": "test".

curl -s -X POST https://rtd.scenecontext.io/v1/enrich \
  -H "Authorization: Bearer $SC_KEY" \
  -H "Content-Type: application/json" \
  -d '{"app":{"bundle":"com.example.ctvapp"},
       "content":{"title":"Mord mit Aussicht","genre":"krimi"}}'

Then wire it into your bid evaluation with a shared keep-alive client, a 20 ms timeout and the circuit breaker described above. Integration examples in Go and Java are available on request.