Docs/Wire contract (v1)

Wire contract (v1)

A single ad-serving REST contract — request, render, report — implemented identically by every official SDK. This section is the authoritative reference; if you're integrating without an SDK, start here.

Unfamiliar terms?

This reference uses words like "slot", "fill", imp_id and "auction" freely. If any of them are new, Core concepts explains all of them in plain language first.
Every claim in this reference is verified directly against the theaimart-adnetwork (Rust/actix-web) backend source — not written from memory or stale docs. If the backend contract ever changes, this reference changes first, then every SDK follows.

Base URL & transport

NameTypeRequiredNotes
Production base URLOptionalhttps://api.adx.theaimart.co
Serve API prefixOptional/api/v1/serve
ProtocolOptionalHTTP/1.1 or h2c; responses may be gzip/brotli if Accept-Encoding advertises it
Response Content-TypeOptionalapplication/json (VAST responses use application/xml, out of scope for v1 SDKs)
Cache-ControlOptionalno-store — ad responses must never be cached

Every SDK exposes baseUrl/base_url as a constructor option (default: the production URL above) so you can point at a staging environment.

Endpoints used by a publisher SDK

NameTypeRequiredNotes
GET /api/v1/serve/adOptionalRequest an ad decision — the core call. See Requesting an ad.
POST /api/v1/serve/viewableOptionalViewability beacon (≥50% on-screen for ≥1s). See Beacons.
GET /api/v1/serve/click?id={imp_id}OptionalClick tracker → 302 redirect to the advertiser. See Beacons.

Do not call these yourself

The SDK never calls POST /api/v1/serve/impression — that endpoint is for external/VAST integrations and requires six server-known UUIDs. Impressions for the /serve/ad flow are recorded server-side automatically when the ad is served. Calling it yourself double-counts.

GET /api/v1/serve/vast (video/VAST) is excluded from v1 of every SDK in this repo — its impression pixel is a POST-only, body-required route and its click-through imp_id is never persisted, so clicks redirect to a fallback. Don't ship rewarded/instream video against this backend until that's fixed.

The request/response lifecycle

Every integration, regardless of platform, follows the same three-step lifecycle:

  1. Request — GET /api/v1/serve/ad?api_key=…&slot_id=… with an explicit, fraud-safe User-Agent.
  2. Parse & render — the body is one of four shapes (no-fill / internal image / OpenRTB HTML / house image). Parse the discriminator in order; render HTML only in a sandboxed context.
  3. Report — fire the viewability beacon once, when the ad is ≥50% visible for ≥1 continuous second. Clicks need no extra call — click_url is pre-wrapped.

Versioning

SDKs follow SemVer independently but all track this contract's major version (v1). A breaking change to the wire contract bumps the major version of every SDK simultaneously. Every SDK also sends an X-Adx-Sdk header (name + version) for observability — it is not part of the User-Agent and does not affect fraud scoring.

Reference index