Document and test /auction API contract parameters for non-Prebid.js callers #699

Context

The POST /auction endpoint accepts AdRequest { adUnits[], config? }. When called without Prebid.js (e.g. from slim-Prebid, a native app, or a server-side caller):

• bids[] is optional — if absent or empty, AdSlot.bidders is an empty map
• An empty bidders map triggers the PBS stored-request fallback: imp.ext.prebid.storedrequest = { id: slot_code }
• Full consent pipeline runs (cookies + headers + geo + KV store)
• EC ID is generated per-call (stateless — no session threading)
• No slot-template expansion — caller must construct adUnits explicitly

Minimum valid request

{
  "adUnits": [{
    "code": "atf_sidebar_ad",
    "mediaTypes": { "banner": { "sizes": [[300, 250]] } }
  }]
}

PBS stored request keyed by "atf_sidebar_ad" must exist for this to produce bids.

Action

• Add API documentation to auction/endpoints.rs covering both inline-params and stored-request paths
• Add an integration test covering the no-bids path verifying storedrequest is set in the outgoing OpenRTB
• Confirm config passthrough keys allowed via auction.allowed_context_keys are documented for callers

Parent: #677

Resolution

Server-side automatic auction (publisher page load, no Pbjs)

Distinct from POST /auction. When a publisher page loads and slots match creative-opportunities.toml, the server fires an auction automatically via publisher.rs → build_auction_request → prebid.rs:to_openrtb. The following OpenRTB fields are populated and forwarded to PBS:

Note: device.ip and device.geo were previously missing (None). Fixed in PR #680 — missing IP caused bidders (e.g. PubMatic) to filter the request as non-human traffic, reducing fill rate.