NORMA Ads API (1.0.0)

Implements RFC 6749 §4.4 Client Credentials grant. Returns a short-lived RS256-signed JWT bearer token. Rate limited to 10 requests/minute per IP.

Returns the RSA public key set used to verify NORMA-issued JWTs.

Returns all 11 NORMA moment types with floor CPM prices and typical CTR ranges. This endpoint is public (no authentication required) and cached for 1 hour.

Returns floor prices and clearing price percentiles (p25/p50/p75/p90) for all moment types. Data is privacy-safe (no individual bids exposed) and cached for 15 minutes. Useful for bid strategy optimization.

Returns all campaigns for the authenticated advertiser, newest first.

Creates a new ad campaign with an initial creative. The campaign is set to active status immediately. The icon_url must be a publicly reachable HTTPS URL (verified via HEAD request at creation time). Bid CPM must meet or exceed the floor price for all selected moment types.

Returns full campaign detail including the primary creative.

Updates mutable campaign fields. The following fields are immutable after creation and cannot be changed: moment_types, sports, start_date, creative. Bid changes propagate to the bids table synchronously.

Transitions an active campaign to paused status. No-ops if already paused.

Transitions a paused campaign back to active. Fails if budget is exhausted.

Adds a new creative variant to an existing campaign for A/B testing. Traffic is split equally across all approved variants. Variants are labeled variant_a, variant_b, variant_c, etc. automatically.

Returns floor prices and clearing price percentiles (p25/p50/p75/p90) for all moment types. Data is privacy-safe (no individual bids exposed) and cached for 15 minutes. Useful for bid strategy optimization.

Returns aggregated performance metrics for a campaign over a date range. Optional breakdown by moment_type or creative for granular analysis. Rate limited to 60 requests/minute per advertiser.

Returns impression, click, and spend data over time. Use granularity=day for daily aggregates (reads from materialized view, fast) or granularity=hour for hourly data (reads raw impressions, slower).

Returns impression, click, and conversion metrics for a specific creative.

Registers a URL to receive NORMA event notifications. A 32-byte hex signing secret is generated and returned once — store it immediately. Use the X-Norma-Signature header (sha256=<hex>) to verify delivery.

NORMA signs with HMAC-SHA256 using the shared secret:

X-Norma-Signature: sha256=<hmac_hex>

Sets the endpoint to inactive. Delivery will stop. Cannot be re-activated via API.

Fires a conversion.recorded test event to the endpoint. Useful for verifying connectivity and signature verification before going live.

Records a conversion event for a click that originated from a NORMA ad. The GET method is standard for mobile attribution partners who use URL macros in postback URLs.

Deduplication is enforced: if converted=true is already set on the click, returns { status: "already_recorded" }. Use idempotency_key to safely retry without creating duplicates.

Conversions outside the 7-day attribution window are rejected.

Records a conversion event via JSON body. Equivalent to the GET endpoint but accepts a JSON body instead of query parameters. Both formats are supported for maximum partner compatibility.