# Trillboards Partner API Supply, on-glass SDK, sensing, device provisioning and federated learning. Everything you can call with a Trillboards **partner credential** — one `platform_api_key` (plus `sdk:*` scopes where noted) for the server-side surface, and a per-device token for the on-glass surfaces. This is one document covering five previously separate references: | Section | Credential | What it does | | --- | --- | --- | | Partner API | `platform_api_key` (Bearer) | Screens, ads, analytics, earnings, billing, webhooks | | CTV SDK & CSI | `platform_api_key` + `sdk:*` scope | On-glass measurement, occupancy, QR | | Sensing | device token | Paired training samples from edge sensing | | Device Provisioning | device token | OTA manifests and CCTV pairing | | Federated Learning | device fingerprint | Gradient / performance / taste uploads | All paths are absolute against `https://api.trillboards.com`. - Interactive reference: https://api.trillboards.com/docs#partner - OpenAPI document: https://api.trillboards.com/docs/openapi/bundled/partner.json - Every operation, machine-readable: https://api.trillboards.com/api/discover?surface=partner ## Authentication - `ApiKeyAuth`: API key in header `X-API-Key`. The same platform API key as `BearerAuth`, sent as a raw header value instead of a Bearer credential. `X-Trillboards-API-Key` is accepted as a legacy alias for this header. Scope semantics are identical. - `BearerAuth`: HTTP bearer. API key authentication. Include your API key as a Bearer token: `Authorization: Bearer trb_partner_xxxxx` - `BearerAuth__sdk`: HTTP bearer. Platform API key sent as `Authorization: Bearer `. This is the canonical carrier. Scopes listed on an operation are enforced by `middleware/apiKeyAuth.js`; ALL listed scopes must be held. A key holding a namespace wildcard (e.g. `sdk:*`) satisfies any scope in that namespace. An operation listing no scope accepts any valid, unexpired key. - `DeviceFingerprint`: API key in header `X-Device-Fingerprint`. Device fingerprint for the federated-learning write path, resolved against a known, sensor-bound device. `screenId` in the request body and `screen_id` in the query string are accepted as equivalent carriers for fielded agents that cannot set the header. - `DeviceToken`: API key in header `X-Device-Token`. The registered device's credential: the device token `check-screen` issues to the partner SDK for a registered device (never a partner API key). Every request also carries `X-Device-Timestamp` (epoch ms, within the replay window) and a single-use `X-Device-Nonce`; a reused nonce is refused 409. - `DeviceToken__sensing`: API key in header `X-Device-Token`. Per-device token issued at pairing, sent by a fielded device. `X-Trillboard-Device-Token` is accepted as a legacy alias. In production these requests must also carry a replay guard — a timestamp (`X-Device-Timestamp`) and a nonce (`X-Device-Nonce`) — or the request is rejected 400 before authentication completes. - `UserJWT`: HTTP bearer. User JWT authentication for earner-to-partner upgrade. Used only for the `/v2/earner/upgrade-to-partner` endpoint. This is the same JWT token used for the Earner Portal. ## Operations (241) ### Partners Partner account management #### POST /v1/partner/api-key/rotate Rotate API key Generates a new API key with a 24-hour grace period for the old key. Both keys work during the grace period, after which the old key is invalidated. **Important:** The new API key is only shown once. Store it securely! - Auth: `BearerAuth` HTTP bearer - Agent: agent_safe=false, idempotent=false, cost_tier=free - operationId: `rotateApiKey` Responses: - `200` New API key generated - `401` Unauthorized - Invalid or missing API key #### POST /v1/partner/billing/cancel Cancel the partner's subscription at period end Marks the partner's subscription for cancellation at the end of the current billing period. The partner retains access until then; no proration is applied. Idempotent. - Auth: `BearerAuth` HTTP bearer - Agent: agent_safe=false, idempotent=true, cost_tier=free - operationId: `cancelBillingSubscription` Responses: - `200` Subscription marked for cancellation - `401` Unauthorized - Invalid or missing API key #### GET /v1/partner/billing/plans List available partner billing plans Returns the catalogue of partner billing plans — tier name, monthly price in USD cents, included quotas (ads, impressions, audience-API calls), and per-unit overage rates. - Auth: `BearerAuth` HTTP bearer - Agent: agent_safe=true, idempotent=true, cost_tier=free - operationId: `listBillingPlans` Responses: - `200` Plan catalogue #### POST /v1/partner/billing/subscribe Subscribe the partner to a billing plan Starts or upgrades a subscription to the supplied `tier`. Returns the Stripe checkout-session URL when a card on file is missing; otherwise records the new plan and returns the active subscription. - Auth: `BearerAuth` HTTP bearer - Agent: agent_safe=false, idempotent=false, cost_tier=paid - operationId: `createBillingSubscription` Request body (`application/json`, required): `object` | Field | Type | Required | Description | | --- | --- | --- | --- | | `tier` | `string`: one of `developer`, `enterprise` | yes | | Responses: - `200` Subscription started - `400` Invalid tier - `401` Unauthorized - Invalid or missing API key #### GET /v1/partner/billing/subscription Get the partner's current subscription Returns the partner's active subscription tier, billing cycle, next invoice date, current-period usage roll-up, and the Stripe customer ID. Use this to render an in-product billing-status UI. - Auth: `BearerAuth` HTTP bearer - Agent: agent_safe=true, idempotent=true, cost_tier=free - operationId: `getBillingSubscription` Responses: - `200` Subscription - `401` Unauthorized - Invalid or missing API key #### GET /v1/partner/billing/usage Get the partner's current-period usage Returns counters for impressions, audience-API calls, and ads served in the current billing period, plus overage projection vs. plan quota. Refreshed every five minutes from the rollup pipeline. - Auth: `BearerAuth` HTTP bearer - Agent: agent_safe=true, idempotent=true, cost_tier=free - operationId: `getBillingUsage` Responses: - `200` Usage payload - `401` Unauthorized - Invalid or missing API key #### GET /v1/partner/docs Browsable HTML documentation index Returns an HTML page that renders the partner-API OpenAPI spec via Redoc, with a left-nav of every documented endpoint. Intended for humans onboarding to the API; agentic clients should fetch the raw YAML at `/docs/openapi/partner-api.yaml` instead. - Auth: none (public) - Agent: agent_safe=true, idempotent=true, cost_tier=free - operationId: `partnerDocsBrowser` Responses: - `200` Redoc-rendered documentation page #### GET /v1/partner/info Get partner info Retrieve information about the authenticated partner - Auth: `BearerAuth` HTTP bearer - Agent: agent_safe=true, idempotent=true, cost_tier=free - operationId: `getPartnerInfo` Responses: - `200` Partner info retrieved - `401` Unauthorized - Invalid or missing API key #### GET /v1/partner/ping Unauthenticated liveness probe Returns a 200 with a tiny JSON payload identifying the partner-API service. Used by load balancers, uptime monitors, and SDK install verification. No authentication required. - Auth: none (public) - Agent: agent_safe=true, idempotent=true, cost_tier=free - operationId: `partnerPing` Responses: - `200` Liveness payload #### GET /v1/partner/ping/auth Authenticated liveness probe Returns a 200 with a JSON payload including the partner ID derived from the supplied bearer token. Used during partner onboarding to confirm an API key is valid and to inspect the active tier. - Auth: `BearerAuth` HTTP bearer - Agent: agent_safe=true, idempotent=true, cost_tier=free - operationId: `partnerPingAuth` Responses: - `200` Authenticated liveness payload - `401` Unauthorized - Invalid or missing API key #### POST /v1/partner/quick-start Quick start — register partner and first device in one call Registers a new partner and creates their first device in a single API call. Returns API key, device credentials, SDK snippets, and configuration. **Rate limited:** 5 requests per hour per IP address. **Important:** The API key is only shown once in the response. Store it securely! - Auth: none (public) - Agent: agent_safe=false, idempotent=false, cost_tier=free - operationId: `quickStart` Request body (`application/json`, required): `object` | Field | Type | Required | Description | | --- | --- | --- | --- | | `company_name` | `string` | yes | Company or partner name | | `device_display` | `object` | | Display configuration for the first device | | `device_location` | `object` | | Location for the first device | | `device_name` | `string` | | Name for the first device | | `email` | `string` | yes | | | `partner_type` | `string` | | Optional legacy classification. Omit for the default self-serve Partner API key. | Responses: - `201` Partner registered and first device created - `400` Missing company_name or email - `409` Partner with this email already exists - `429` Rate limit exceeded #### POST /v1/partner/register Register a new partner Register once to receive a Partner API key. Partners are auto-activated for instant onboarding. **Important:** The API key is only shown once in the response. Store it securely! The default flow is intentionally one-stop: send your organization name, slug, and contact email. Trillboards returns a Partner API key that can authenticate partner account, device, ad-serving, impression, analytics, CMS, webhook, dashboard, earnings, and team-management endpoints in this spec. `partner_type` is optional and kept for backward compatibility with older integrations. Most developers should omit it — it never forks the key you get back. Every partner registers once and receives the same Partner API key, which already carries `sdk:*` for the CTV Measurement ingestion surface and `mcp:tools` for capability-authorized AI tools. - Auth: none (public) - Agent: agent_safe=false, idempotent=false, cost_tier=free - operationId: `registerPartner` Request body (`application/json`, required): `object` | Field | Type | Required | Description | | --- | --- | --- | --- | | `allowed_domains` | array of `string` | | Whitelist of allowed referrer domains | | `contact_email` | `string` | yes | | | `contact_name` | `string` | | | | `name` | `string` | yes | Company or partner name | | `partner_type` | `string`: one of `vending_machine`, `kiosk`, `digital_signage`, `retail_display`, `ctv_publisher`, `other` | | Optional legacy classification. Omit this field — it does not change which API key you receive. Existing integrations may continue sending historical values (including `ctv_publisher`) for backward compatibility; every partner_type mints the same self-serve Partner API key. | | `revenue_share_percent` | `number` | | Partner's revenue share percentage (negotiated per partner) | | `slug` | `string` | yes | URL-safe identifier (lowercase, no spaces) | Responses: - `201` Partner registered successfully - `400` Bad request - `409` Partner slug already exists ### Devices Device registration and management #### POST /v1/partner/device Register a device Register a new device or update an existing one. If a device with the same `device_id` already exists, it will be updated. `device_type` is the partner's mutable category. Supplying it updates the category; omitting it preserves an existing category and defaults a new device to `other`. Category updates preserve advertising classification. The response includes an `embed_url` that should be loaded in your device's WebView. - Auth: `BearerAuth` HTTP bearer - Agent: agent_safe=false, idempotent=false, cost_tier=free - operationId: `registerDevice` Request body (`application/json`, required): `object` | Field | Type | Required | Description | | --- | --- | --- | --- | | `custom_metadata` | `object` | | Any additional metadata for your records | | `description` | `string` | | Screen or venue description for enrichment | | `device_id` | `string` | yes | Your internal device identifier | | `device_type` | `string`: one of `tv`, `tablet`, `display`, `kiosk`, `other`, `mobile`, `connected_tv`, `digital_signage`, … | | Mutable partner category; defaults to other only on a new registration. Omit it to preserve an existing device's category. | | `display` | `object` | | Screen display specification. `width`/`height` are pixel resolution; `width_in`/`height_in` are physical inches. For accurate floor pricing we need physical inches — pass `width_in` + `height_in` if you've measured the screen, OR `ppi` so the server can derive inches from the pixel resolution. Pixel-only inputs (no `ppi`, no `*_in`) will NOT be recorded as physical size; they're still used for orientation detection and DSP slot dimensions. | | `display_settings` | `PartnerRegistrationDisplaySettings` | | | | `location` | `object` | | | | `mobile_settings` | `object` | | Reporting hints for moving screens (mobility_type mobile/semi_mobile). | | `mobility_type` | `string`: one of `static`, `mobile`, `semi_mobile` | | Declare a moving screen. `mobile` (taxi-top, transit) and `semi_mobile` (food truck, pop-up) screens report GPS via the heartbeat `location` field; `static` (default) screens ignore it. | | `name` | `string` | | Friendly name for the device | | `photo_url` | `string` | | Photo URL for enrichment context | | `photos` | array of `object` | | Optional additional photos for enrichment | | `placement` | `object` | | Physical placement details (optional) | | `venue` | `object` | | Venue classification details (optional). Subcategory is free text and may be auto-enriched by AI. | Responses: - `201` Device registered - `401` Unauthorized - Invalid or missing API key - `429` Rate limit exceeded #### GET /v1/partner/device/{deviceId} Get device info - Auth: `BearerAuth` HTTP bearer - Agent: agent_safe=true, idempotent=true, cost_tier=free - operationId: `getDevice` | Parameter | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `deviceId` | path | `string` | yes | Device ID, fingerprint, or external device ID | Responses: - `200` Device info - `404` Resource not found #### PATCH /v1/partner/device/{deviceId} Update device metadata Partially update device metadata. Only provided fields are updated. `device_type` changes only the partner category. Advertising type, hardware identity, and bidding settings remain unchanged. Unsupported categories return HTTP 400 with `INVALID_DEVICE_TYPE`. Changes propagate to the linked screen record. If location changes, venue enrichment is re-triggered. - Auth: `BearerAuth` HTTP bearer - Agent: agent_safe=false, idempotent=true, cost_tier=free - operationId: `updateDevice` | Parameter | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `deviceId` | path | `string` | yes | Device ID, fingerprint, or external device ID | Request body (`application/json`, required): `object` | Field | Type | Required | Description | | --- | --- | --- | --- | | `custom_metadata` | `object` | | Any additional metadata for your records | | `description` | `string` | | Screen or venue description | | `device_type` | `string`: one of `tv`, `tablet`, `display`, `kiosk`, `other`, `mobile`, `connected_tv`, `digital_signage`, … | | Mutable partner category. Omit it to preserve the current value; changing it does not alter advertising classification. | | `display` | `object` | | Screen display specification. `width`/`height` are pixels; pass `width_in`/`height_in` (inches) or `ppi` to record physical screen size for floor pricing. See POST /device for full unit semantics. | | `external_device_id` | `string` | | Partner-owned device ID used for idempotent lookup and reconciliation | | `location` | `object` | | | | `mobile_settings` | `object` | | Reporting hints for moving screens. Merges with existing settings. | | `mobility_type` | `string`: one of `static`, `mobile`, `semi_mobile` | | Update the screen's mobility. Set `mobile`/`semi_mobile` to have the heartbeat `location` field accepted for a moving screen. | | `name` | `string` | | Friendly name for the device | | `photo_url` | `string` | | | | `photos` | array of `object` | | | | `placement` | `object` | | | | `venue` | `object` | | | Responses: - `200` Device updated - `401` Unauthorized - Invalid or missing API key - `404` Resource not found - `429` Rate limit exceeded #### DELETE /v1/partner/device/{deviceId} Delete a device Soft-delete a device. It will no longer receive ads. - Auth: `BearerAuth` HTTP bearer - Agent: agent_safe=false, idempotent=true, cost_tier=free - operationId: `deleteDevice` | Parameter | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `deviceId` | path | `string` | yes | | Responses: - `200` Device deleted - `404` Resource not found #### POST /v1/partner/device/{deviceId}/commands/{commandId}/ack Acknowledge a device command Acknowledges receipt and execution of a command sent to a device. Typically called by the SDK/device after processing a fleet command. - Auth: none (public) - Agent: agent_safe=false, idempotent=true, cost_tier=free - operationId: `ackDeviceCommand` | Parameter | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `deviceId` | path | `string` | yes | Device identifier (fingerprint or external ID) | | `commandId` | path | `string` | yes | Command ID to acknowledge | Request body (`application/json`): `object` | Field | Type | Required | Description | | --- | --- | --- | --- | | `result` | `object` | | Command execution result | | `status` | `string` | | Acknowledgment status | Responses: - `200` Command acknowledged - `403` Command does not belong to this device - `404` Device or command not found #### GET /v1/partner/device/{deviceId}/heartbeat Read live device heartbeat state Read-side companion to `POST /device/{deviceId}/heartbeat`. Returns the device twin (Redis-cached, PG-fallback) so ad-serving partners can check device health before issuing ad requests. Field-level access control strips MDM compliance, vertex embeddings, identity- correction internals, partner identifiers, and Mongo `_id`. Pure read; no side effects. Authenticated via the partner API key (`Authorization: Bearer trb_partner_xxx` or `tb_prt_xxx`). Rate limit: 1000 req/min per API key. - Auth: `BearerAuth` HTTP bearer - Agent: agent_safe=true, idempotent=true, cost_tier=free - operationId: `getDeviceHeartbeat` | Parameter | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `deviceId` | path | `string` | yes | Device fingerprint or external device ID | Responses: - `200` Live device heartbeat state. - `401` Unauthorized - Invalid or missing API key - `403` Device does not belong to this partner - `404` Resource not found - `429` Rate limit exceeded #### POST /v1/partner/device/{deviceId}/heartbeat Device heartbeat Mark a device online and record `lastHeartbeatAt`. The embeddable agent-core Sensing SDK and CTV Measurement SDK send this automatically on their configured heartbeat cadence. Custom players may POST the same payload themselves. `:deviceId` accepts your `external_id` (the same value you registered) or the device fingerprint. Read the result back from `GET /device/{deviceId}/heartbeat` — `lastHeartbeatAt` is NOT included on the plain `GET /device/{deviceId}` response. Supports structured telemetry payloads (`telemetry`, `sdk`, `device`, `network`, `ad`) and legacy flat heartbeat keys for backward compatibility. The request body accepts legacy flat/nested telemetry (`PartnerHeartbeatRequest`), agent-core sensing fields, or both together. The sensing schema (`PartnerDeviceHeartbeatBody`) describes which sensing fields actually ship in production (BLE, WiFi, mDNS, SSDP, HTTP probes, skip-reason counts) and explicitly excludes stub fields with 0% production population (Phase 6 UWB / Auracast / Channel Sounding, MDM enrollment, native sensors, CSI). This registered-device heartbeat is intentionally unauthenticated. Liveness, `advertising_identity`, and `extended_identities` use the same device binding: `deviceId` must resolve to a device that was registered already, and every identity envelope must pass the typed validation below. No partner API key or device JWT is required. - Auth: none (public) - Agent: agent_safe=false, idempotent=true, cost_tier=free - operationId: `heartbeat` | Parameter | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `deviceId` | path | `string` | yes | Device fingerprint or external device ID | Request body (`application/json`): `PartnerHeartbeatRequest` | `PartnerDeviceHeartbeatBody` Responses: - `200` Heartbeat recorded #### PATCH /v1/partner/device/{deviceId}/impression-multiplier Update a device's publisher impression multiplier Update the existing screen's publisher-declared audience impressions per ad play. Authenticate with the owning partner API key. The device and linked screen must be active records owned by that partner; another partner's device returns 404. This writes only the screen multiplier and its update timestamp, preserving its device IDs and other settings. Repeat requests are idempotent. Send a JSON number between 0.1 and 100 inclusive, matching the venue-screen editor's range. Values are stored to four decimal places. Use the measurement provider's value for the applicable spot duration; a daily traffic total is a different unit. Repeat this call for each device in your fleet. The saved value is returned here and in GET /v1/partner/device/{deviceId} and GET /v1/partner/devices. It feeds the existing publisher-estimate inventory and uncurated bid paths; measured quantity and billing keep their existing precedence. - Auth: `BearerAuth` HTTP bearer - Agent: agent_safe=false, idempotent=true, cost_tier=free - operationId: `updateDeviceImpressionMultiplier` | Parameter | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `deviceId` | path | `string` | yes | Trillboards device ID, fingerprint, or URL-encoded external_device_id | Request body (`application/json`, required): `object` | Field | Type | Required | Description | | --- | --- | --- | --- | | `impression_multiplier` | `number` | yes | Publisher-declared audience impressions per ad play; stored to four decimal places | Responses: - `200` Saved multiplier, returned as a JSON number - `400` Missing, nonnumeric, out-of-range multiplier, or unexpected body fields - `401` Missing or invalid partner API key - `404` Device or linked screen not found in the authenticated partner's active records - `500` Canonical Trillboards error envelope for unexpected server errors. Surfaces the request_id so the caller can quote it to support for log correlation. #### GET /v1/partner/devices List all devices - Auth: `BearerAuth` HTTP bearer - Agent: agent_safe=true, idempotent=true, cost_tier=free - operationId: `listDevices` | Parameter | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `status` | query | `string`: one of `pending`, `active`, `offline`, `suspended` | | | | `limit` | query | `integer` | | | | `offset` | query | `integer` | | | Responses: - `200` Device list #### POST /v1/partner/devices Register a device (V2 single-call onboarding) Register — or idempotently re-register, keyed on `external_id` — a single partner device and provision its screen in one call. Returns the embeddable player URL and the server-derived device identity. Always send the device's real WebView `ua`: it is the single most important field for DSP biddability. - Auth: `BearerAuth` HTTP bearer - Agent: agent_safe=false, idempotent=true, cost_tier=free - operationId: `registerDeviceV2` Request body (`application/json`, required): `object` | Field | Type | Required | Description | | --- | --- | --- | --- | | `display` | `object` \| `object` \| `object` | | Optional display dimensions. One of three modes — the `mode` discriminator is required. | | `external_id` | `string` | yes | Your stable per-device identifier (e.g. "REC00005"). | | `hardware` | `object` | | Optional hardware identity — improves DSP device matching. | | `location` | `object` \| `object` | | Optional venue location — either lat/lng coordinates or a street address. | | `ua` | `string` | yes | The device's real WebView User-Agent. Must include a Build fingerprint and be unique per device. | Responses: - `200` Device registered (or idempotently re-registered) - `400` Bad request - `401` Unauthorized - Invalid or missing API key #### POST /v1/partner/devices/batch Bulk register devices Register up to 100 devices in a single request. Each device must include `device_id`. Optional `defaults` are applied to every device. - Auth: `BearerAuth` HTTP bearer - Agent: agent_safe=false, idempotent=false, cost_tier=free - operationId: `registerDevicesBatch` Request body (`application/json`, required): `object` | Field | Type | Required | Description | | --- | --- | --- | --- | | `defaults` | `object` | | Default fields applied to each device | | `devices` | array of `object` | yes | | Responses: - `200` Batch processed #### POST /v1/partner/devices/batch/orientation Batch update screen orientation Update `screen_orientation` for multiple devices/screens in one request. Accepts device identifiers (ObjectId, fingerprint, or partner_external_id). - Auth: `BearerAuth` HTTP bearer - Agent: agent_safe=false, idempotent=true, cost_tier=free - operationId: `batchUpdateDeviceOrientation` Request body (`application/json`, required): `object` | Field | Type | Required | Description | | --- | --- | --- | --- | | `device_ids` | array of `string` | yes | | | `screen_orientation` | `string`: one of `portrait`, `landscape`, `mixed`, `unknown` | yes | | Responses: - `200` Batch update result - `400` Bad request - `401` Unauthorized - Invalid or missing API key - `404` Resource not found - `429` Rate limit exceeded #### POST /v1/partner/devices/reconcile Reconcile device fleet Read-only diff. Post the `external_ids` you believe you have registered and get back how they map to the devices Trillboards actually has for you: `matched`, `missing` (you listed, not registered), `orphan` (registered, you did not list), `malformed` (registered with an invalid external id), and `duplicate` (one external id on more than one device), plus a `summary`. Self-service replacement for hand-rolled fleet-sync tooling. No writes. - Auth: `BearerAuth` HTTP bearer - Agent: agent_safe=true, idempotent=true, cost_tier=free - operationId: `reconcileDevices` Request body (`application/json`, required): `object` | Field | Type | Required | Description | | --- | --- | --- | --- | | `external_ids` | array of `string` | yes | Your device external IDs to reconcile. | Responses: - `200` Reconciliation diff - `400` external_ids missing, empty, or over the limit ### Screen Groups Create and manage screen groups (fleets) and their shared configuration #### GET /v1/partner/screen-groups List screen groups - Auth: `BearerAuth` HTTP bearer - Agent: agent_safe=true, idempotent=true, cost_tier=free - operationId: `listScreenGroups` | Parameter | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `limit` | query | `integer` | | | | `offset` | query | `integer` | | | Responses: - `200` A paginated list of screen groups - `401` Unauthorized - Invalid or missing API key #### POST /v1/partner/screen-groups Create a screen group Create a reusable, named, partner-scoped set of screens. Optionally seed it with `screen_ids` (each must be a screen this partner owns). Gated by SCREEN_GROUPS_ENABLED. - Auth: `BearerAuth` HTTP bearer - Agent: agent_safe=false, idempotent=false, cost_tier=free - operationId: `createScreenGroup` Request body (`application/json`, required): `object` | Field | Type | Required | Description | | --- | --- | --- | --- | | `description` | `string` | | | | `name` | `string` | yes | | | `screen_ids` | array of `string` | | | Responses: - `201` Screen group created - `400` Bad request - `401` Unauthorized - Invalid or missing API key - `403` One or more screens are not owned by this partner #### GET /v1/partner/screen-groups/{groupId} Retrieve a screen group - Auth: `BearerAuth` HTTP bearer - Agent: agent_safe=true, idempotent=true, cost_tier=free - operationId: `getScreenGroup` | Parameter | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `groupId` | path | `string` | yes | | Responses: - `200` The screen group - `401` Unauthorized - Invalid or missing API key - `404` Resource not found #### POST /v1/partner/screen-groups/{groupId} Update a screen group Partial, non-clobbering update of name / description. - Auth: `BearerAuth` HTTP bearer - Agent: agent_safe=false, idempotent=true, cost_tier=free - operationId: `updateScreenGroup` | Parameter | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `groupId` | path | `string` | yes | | Request body (`application/json`): `object` | Field | Type | Required | Description | | --- | --- | --- | --- | | `description` | `string` | | | | `name` | `string` | | | Responses: - `200` The updated screen group - `401` Unauthorized - Invalid or missing API key - `404` Resource not found #### DELETE /v1/partner/screen-groups/{groupId} Delete (archive) a screen group - Auth: `BearerAuth` HTTP bearer - Agent: agent_safe=false, idempotent=true, cost_tier=free - operationId: `deleteScreenGroup` | Parameter | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `groupId` | path | `string` | yes | | Responses: - `200` The screen group was archived - `401` Unauthorized - Invalid or missing API key - `404` Resource not found #### GET /v1/partner/screen-groups/{groupId}/analytics Get analytics for a screen group Fleet analytics (last 24h) scoped to the group's member screens. Same shape as GET /fleet/analytics. Gated by SCREEN_GROUPS_ENABLED. - Auth: `BearerAuth` HTTP bearer - Agent: agent_safe=true, idempotent=true, cost_tier=free - operationId: `getScreenGroupAnalytics` | Parameter | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `groupId` | path | `string` | yes | | Responses: - `200` Group analytics - `401` Unauthorized - Invalid or missing API key - `404` Resource not found #### POST /v1/partner/screen-groups/{groupId}/commands Run a fleet command against a screen group Fans a device command out across the group's member screens and returns a pollable fleet-command job (poll GET /fleet-commands/{id}). Max 500 member screens per command. Gated by SCREEN_GROUPS_ENABLED. - Auth: `BearerAuth` HTTP bearer - Agent: agent_safe=false, idempotent=false, cost_tier=free - operationId: `createScreenGroupCommand` | Parameter | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `groupId` | path | `string` | yes | | Request body (`application/json`, required): `object` | Field | Type | Required | Description | | --- | --- | --- | --- | | `command` | `object` | yes | | Responses: - `202` Fleet-command job created - `400` Bad request - `401` Unauthorized - Invalid or missing API key - `404` Resource not found - `429` Rate limit exceeded #### GET /v1/partner/screen-groups/{groupId}/content-policy Get a screen group's content policy The typed content/moderation policy the group carries, or `null` when the group has none of its own. Member screens inherit it at read/serve time (screen ?? group ?? partner network default ?? system default). Gated by SCREEN_GROUPS_ENABLED. - Auth: `BearerAuth` HTTP bearer - Agent: agent_safe=true, idempotent=true, cost_tier=free - operationId: `getScreenGroupContentPolicy` | Parameter | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `groupId` | path | `string` | yes | | Responses: - `200` The group's content policy (nullable) - `401` Unauthorized - Invalid or missing API key - `404` Resource not found #### PUT /v1/partner/screen-groups/{groupId}/content-policy Set a screen group's content policy Non-clobbering upsert — only the fields present in the body are written. Row existence = "this group carries a content policy". Busts the affected member caches. Gated by SCREEN_GROUPS_ENABLED. - Auth: `BearerAuth` HTTP bearer - Agent: agent_safe=false, idempotent=true, cost_tier=free - operationId: `updateScreenGroupContentPolicy` | Parameter | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `groupId` | path | `string` | yes | | Request body (`application/json`, required): `ScreenGroupContentPolicyInput` | Field | Type | Required | Description | | --- | --- | --- | --- | | `allow_adult_content` | `boolean` | | Must be a real JSON boolean — the strings `"true"`/`"false"` are rejected with `field_must_be_boolean`, unlike the L-bar PUT which accepts them. Writing `false` adds `IAB25` and `IAB25-2`..`IAB25-5` to the member screens' `bcat`; unset already blocks it via the platform default. | | `allow_alcohol` | `boolean` | | Must be a real JSON boolean — the strings `"true"`/`"false"` are rejected with `field_must_be_boolean`, unlike the L-bar PUT which accepts them. Writing `false` both rejects classified alcohol creatives on member screens and adds `IAB8-5`/`IAB8-18` to their outgoing `bcat`. | | `allow_gambling` | `boolean` | | Must be a real JSON boolean — the strings `"true"`/`"false"` are rejected with `field_must_be_boolean`, unlike the L-bar PUT which accepts them. Writing `false` adds `IAB9-7` to the member screens' `bcat`; unset already blocks gambling programmatically via the platform default. | | `allow_political` | `boolean` | | Must be a real JSON boolean — the strings `"true"`/`"false"` are rejected with `field_must_be_boolean`, unlike the L-bar PUT which accepts them. Writing `false` adds `IAB11-4` to the member screens' `bcat`; the platform default here is `true`, so political ads run unless you set this. | | `allow_profanity` | `boolean` | | Must be a real JSON boolean — the strings `"true"`/`"false"` are rejected with `field_must_be_boolean`, unlike the L-bar PUT which accepts them. Writing `false` adds `IAB25-2` to the member screens' `bcat`; unset already blocks it via the platform default. | | `allow_religious` | `boolean` | | Must be a real JSON boolean — the strings `"true"`/`"false"` are rejected with `field_must_be_boolean`, unlike the L-bar PUT which accepts them. Writing `false` adds `IAB23` to the member screens' `bcat`; the platform default here is `true`, so religious ads run unless you set this. | | `allow_tobacco` | `boolean` | | Must be a real JSON boolean — the strings `"true"`/`"false"` are rejected with `field_must_be_boolean`, unlike the L-bar PUT which accepts them. Writing `false` adds `IAB25-6` to the member screens' `bcat`; leaving it unset already blocks tobacco programmatically via the platform brand-safety default. | | `allow_violence` | `boolean` | | Must be a real JSON boolean — the strings `"true"`/`"false"` are rejected with `field_must_be_boolean`, unlike the L-bar PUT which accepts them. Writing `false` adds `IAB25-3`/`IAB25-4` to the member screens' `bcat`; unset already blocks it via the platform default. | | `allowed_categories` | array of `string` | | Array of strings, at most 100 items (`array_too_large`); a non-array is `field_must_be_array` and a non-string element is `array_items_must_be_strings`. Writing it REPLACES the stored list — there is no append — and the allow/block pair is conflict-checked case-insensitively against this patch MERGED onto the stored row, so it can 400 with `conflicting_lists` on a term you set in an earlier request. | | `allowed_keywords` | array of `string` | | Array of strings, at most 100 items (`array_too_large`); a non-array is `field_must_be_array` and a non-string element is `array_items_must_be_strings`. Writing it REPLACES the stored list — there is no append — and it is conflict-checked against `blocked_keywords`, even though at serve time this list never rejects anything — it only contributes to the content match score. | | `allowed_subjects` | array of `string` | | Array of strings, at most 100 items (`array_too_large`); a non-array is `field_must_be_array` and a non-string element is `array_items_must_be_strings`. Writing it REPLACES the stored list — there is no append — and the Subjects allow/block pair is conflict-checked against the stored row merged with this patch. Note these are matched by substring at serve time, not equality. | | `auto_approve_known_brands` | `boolean` | | Must be a real JSON boolean — the strings `"true"`/`"false"` are rejected with `field_must_be_boolean`, unlike the L-bar PUT which accepts them. Setting it `true` makes a known-brand ad bypass every category, subject and keyword check on member screens, so treat it as a widening, not a convenience. | | `blocked_categories` | array of `string` | | Array of strings, at most 100 items (`array_too_large`); a non-array is `field_must_be_array` and a non-string element is `array_items_must_be_strings`. Writing it REPLACES the stored list — there is no append — and blocking a category an earlier PUT allowed fails with `conflicting_lists` even though this request names only one side of the pair. | | `blocked_iab_categories` | array of `string` | | Array of strings capped at 100 by a DIFFERENT constant from the other lists (`PROGRAMMATIC_SETTINGS_LIMITS.max_blocked_iab_categories`), reported as `blocked_iab_categories_too_large`. It is not conflict-checked, because there is no `allowed_iab_categories` counterpart. | | `blocked_keywords` | array of `string` | | Array of strings, at most 100 items (`array_too_large`); a non-array is `field_must_be_array` and a non-string element is `array_items_must_be_strings`. Writing it REPLACES the stored list — there is no append — and unlike `allowed_keywords` this one really does reject, by case-insensitive substring match against the ad's analysed keywords. | | `blocked_subjects` | array of `string` | | Array of strings, at most 100 items (`array_too_large`); a non-array is `field_must_be_array` and a non-string element is `array_items_must_be_strings`. Writing it REPLACES the stored list — there is no append — and it is a hard reject at serve time, matched by case-insensitive substring — so a short entry blocks more than you intend. | | `content_filtering_enabled` | `boolean` | | Must be a real JSON boolean — the strings `"true"`/`"false"` are rejected with `field_must_be_boolean`, unlike the L-bar PUT which accepts them. Omitting the key leaves the stored value untouched; there is no way to reset a key back to "inherit". | | `max_age_rating` | `string`: one of `G`, `PG`, `PG-13`, `R`, `NC-17` | | One of `G`, `PG`, `PG-13`, `R`, `NC-17`; anything else is `invalid_age_rating`. Writing `G` does not give you the strictest policy — the matcher later treats `G` as `PG-13`. | | `preference_level` | `string`: one of `strict`, `moderate`, `lenient`, `permissive` | | One of `strict`, `moderate`, `lenient`, `permissive`; anything else is rejected with `invalid_preference_level`. Validated against the same constant the per-screen content-preferences PUT uses, so the two surfaces cannot drift. | Responses: - `200` The updated content policy - `400` Bad request - `401` Unauthorized - Invalid or missing API key - `404` Resource not found #### GET /v1/partner/screen-groups/{groupId}/members List a screen group's members - Auth: `BearerAuth` HTTP bearer - Agent: agent_safe=true, idempotent=true, cost_tier=free - operationId: `listScreenGroupMembers` | Parameter | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `groupId` | path | `string` | yes | | | `limit` | query | `integer` | | | | `offset` | query | `integer` | | | Responses: - `200` A paginated list of member screens - `401` Unauthorized - Invalid or missing API key - `404` Resource not found #### POST /v1/partner/screen-groups/{groupId}/members Add members to a screen group Idempotent. Partial-success: screens not owned by this partner are returned in `rejected` rather than failing the whole request. - Auth: `BearerAuth` HTTP bearer - Agent: agent_safe=false, idempotent=true, cost_tier=free - operationId: `addScreenGroupMembers` | Parameter | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `groupId` | path | `string` | yes | | Request body (`application/json`, required): `object` | Field | Type | Required | Description | | --- | --- | --- | --- | | `screen_ids` | array of `string` | yes | | Responses: - `200` The add result - `400` Bad request - `401` Unauthorized - Invalid or missing API key - `404` Resource not found #### DELETE /v1/partner/screen-groups/{groupId}/members Remove members from a screen group - Auth: `BearerAuth` HTTP bearer - Agent: agent_safe=false, idempotent=true, cost_tier=free - operationId: `removeScreenGroupMembers` | Parameter | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `groupId` | path | `string` | yes | | Request body (`application/json`, required): `object` | Field | Type | Required | Description | | --- | --- | --- | --- | | `screen_ids` | array of `string` | yes | | Responses: - `200` The remove result - `400` Bad request - `401` Unauthorized - Invalid or missing API key - `404` Resource not found #### GET /v1/partner/screen-groups/{groupId}/sensing-config Get a screen group's sensing config The group's sensing profile binding + typed performance overrides, or `null` when the group has none. Member screens inherit via the sensing resolver's group step when they have no screen-specific deployment. Gated by SCREEN_GROUPS_ENABLED. - Auth: `BearerAuth` HTTP bearer - Agent: agent_safe=true, idempotent=true, cost_tier=free - operationId: `getScreenGroupSensingConfig` | Parameter | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `groupId` | path | `string` | yes | | Responses: - `200` The group's sensing config (nullable) - `401` Unauthorized - Invalid or missing API key - `404` Resource not found #### PUT /v1/partner/screen-groups/{groupId}/sensing-config Set a screen group's sensing config Non-clobbering upsert. `profile_name` must resolve to a builtin or an existing custom profile (else 400). Busts the affected member caches. Gated by SCREEN_GROUPS_ENABLED. - Auth: `BearerAuth` HTTP bearer - Agent: agent_safe=false, idempotent=true, cost_tier=free - operationId: `updateScreenGroupSensingConfig` | Parameter | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `groupId` | path | `string` | yes | | Request body (`application/json`, required): `ScreenGroupSensingConfigInput` | Field | Type | Required | Description | | --- | --- | --- | --- | | `capture` | `object`, nullable | | Edge frame-capture cadence block (milliseconds); null clears it. Unknown keys are rejected (400). | | `capture_interval_ms` | `integer`, nullable | | Frame-capture cadence override in milliseconds (100..3600000); `null` means inherit from the base profile. Advisory in practice: this legacy scalar does not reach the device capture loop (the edge reads the nested `capture` block), the fleet floors at one analysis per 30 s, and observed cadence was measured at ~12x the declared value. | | `enabled` | `boolean` | | Set `false` to make the group step a no-op — members fall through to the next resolver layer while the overrides stay stored, so this is the reversible way to switch group sensing off. | | `estimated_fps_impact` | `number`, nullable | | Advisory workload-cost number (must be >= 0); `null` inherits the profile's own value, which the server derives from the selected models' registry `fps_cost`. Purely descriptive — setting it changes what readback and operator surfaces display and throttles nothing. | | `min_confidence` | `number`, nullable | | Detection-confidence floor in 0..1 written into the resolved profile's `thresholds.min_confidence`; `null` inherits the base profile's value (built-ins are 0.35-0.45). | | `profile_name` | `string`, nullable | | Bind the group to a builtin or existing custom profile BY NAME; a name that resolves to neither is a 400. `null` clears the binding. Never a `profile_id` — that is re-minted per screen on each redeploy. | | `report_interval_ms` | `integer`, nullable | | Observation-reporting cadence override in milliseconds (100..3600000); `null` means inherit from the base profile. | | `vision_budget` | `object`, nullable | | Per-screen cloud-vision budget block; null clears it. Unknown keys are rejected (400). | Responses: - `200` The updated sensing config - `400` Bad request - `401` Unauthorized - Invalid or missing API key - `404` Resource not found #### GET /v1/partner/screens/{screenId}/resolved-content-policy Resolve the effective content policy for a screen Introspection ("why"): the EFFECTIVE content policy for a screen and its provenance. Whole-layer coalescing — the effective policy comes from exactly ONE layer (screen ?? group ?? partner network default ?? system default). Read-only preview. Gated by SCREEN_GROUPS_ENABLED. - Auth: `BearerAuth` HTTP bearer - Agent: agent_safe=true, idempotent=true, cost_tier=free - operationId: `getResolvedContentPolicy` | Parameter | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `screenId` | path | `string` | yes | | Responses: - `200` The effective content policy + provenance - `400` Bad request - `401` Unauthorized - Invalid or missing API key - `404` Resource not found #### GET /v1/partner/screens/{screenId}/resolved-sensing-config Resolve the effective sensing config for a screen Introspection: the EFFECTIVE sensing view for a screen and its provenance (screen deployment ?? group sensing config ?? default). Read-only preview. Gated by SCREEN_GROUPS_ENABLED. - Auth: `BearerAuth` HTTP bearer - Agent: agent_safe=true, idempotent=true, cost_tier=free - operationId: `getResolvedSensingConfig` | Parameter | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `screenId` | path | `string` | yes | | Responses: - `200` The effective sensing config + provenance - `400` Bad request - `401` Unauthorized - Invalid or missing API key - `404` Resource not found ### Creative Moderation Submit creative URLs for AI classification/moderation and read the structured result #### POST /v1/partner/creatives Submit a creative for classification Point us at a public/CDN image or video URL and we return the same structured classification the Trillboards venue portal shows for every served ad: moderation verdict, age rating, confidence, IAB categories, subjects, keywords, on-screen text (OCR), setting/mood/quality, and brand/category. Classification is asynchronous (a few seconds for images, up to ~60s for video). The response carries a canonical `id` of the form `sha256:` — the content hash we computed from the fetched bytes. Poll `GET /creatives/{ref}` with that id until `status` is terminal (`approved`, `flagged`, or `blocked`). If we have already classified the same bytes, the full result is returned immediately with `200`. Use the returned `id` (or `content_sha256`) as `creative_ref` when you post log-level plays, so your plays join to this classification. - Auth: `BearerAuth` HTTP bearer - Agent: agent_safe=false, idempotent=true, cost_tier=free - operationId: `submitPartnerCreative` Request body (`application/json`, required): `object` | Field | Type | Required | Description | | --- | --- | --- | --- | | `advertiser_name` | `string` | | Optional advertiser/brand label to attach. | | `media_url` | `string` | yes | Public http(s) URL of the creative image or video. Must resolve to a public address — private/internal/cloud-metadata addresses are rejected. | Responses: - `200` Content was already classified — full result returned immediately. - `202` Accepted for classification — poll GET /creatives/{id}. - `400` Bad request - `401` Unauthorized - Invalid or missing API key - `422` media_url could not be fetched as a valid image or video. - `429` Rate limit exceeded #### GET /v1/partner/creatives/{ref} Get a creative classification Read the classification for a creative you submitted, by its `sha256:` reference (or the bare 64-char hex). A partner may only read classifications for content it has submitted. - Auth: `BearerAuth` HTTP bearer - Agent: agent_safe=true, idempotent=true, cost_tier=free - operationId: `getPartnerCreative` | Parameter | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `ref` | path | `string` | yes | The reference returned by POST /creatives — `sha256:` or the bare 64-char hex. | Responses: - `200` The creative classification (status may still be `pending`). - `400` Bad request - `401` Unauthorized - Invalid or missing API key - `404` Resource not found - `429` Rate limit exceeded ### Measurement Plays Post log-level plays for ads you serve yourself; join them to classification + audience moments #### POST /v1/partner/plays Record a log-level play Record a single log-level play for an ad you serve yourself (not through our programmatic pipes). The play lands in a dedicated NON-billing store and joins to (a) the creative classification you submitted via POST /creatives — by `creative_ref` (content_sha256) — and (b) our audience moments captured on the screen during the play window. It then surfaces through GET /analytics/content-performance and /analytics/creative-scenes for your screens. Idempotent on `play_id`. `screen_id` must be one of your registered earner screens. Measurement plays are never billed. - Auth: `BearerAuth` HTTP bearer - Agent: agent_safe=false, idempotent=true, cost_tier=free - operationId: `recordPartnerPlay` Request body (`application/json`, required): `PartnerPlay` | Field | Type | Required | Description | | --- | --- | --- | --- | | `ad_id` | `string` | | Optional ad/line identifier; defaults to the sha-keyed creative. | | `completed_at` | `string` | yes | ISO 8601 timestamp when the play completed. | | `creative_ref` | `string` | yes | The classification reference from POST /creatives — `sha256:` or the bare 64-char content hash. | | `duration_seconds` | `number` | | Play duration in seconds (default 30). | | `play_id` | `string` | yes | Your unique id for this play (idempotency key). | | `request_id` | `string` | | Optional partner request identifier. | | `screen_id` | `string` | yes | One of your registered earner-screen ids. | Responses: - `202` Play accepted (or a duplicate of a prior play_id). - `400` Bad request - `401` Unauthorized - Invalid or missing API key - `403` screen_id is not a screen registered to this partner. - `429` Rate limit exceeded #### POST /v1/partner/plays/batch Record a batch of log-level plays Submit up to 500 plays in one request (each the same shape as POST /plays). Every play is validated independently; the response reports per-play rejections (invalid_creative_ref, screen_not_owned). - Auth: `BearerAuth` HTTP bearer - Agent: agent_safe=false, idempotent=true, cost_tier=free - operationId: `recordPartnerPlaysBatch` Request body (`application/json`, required): `object` | Field | Type | Required | Description | | --- | --- | --- | --- | | `plays` | array of `PartnerPlay` | yes | | Responses: - `202` Batch accepted; see per-play results. - `400` Bad request - `401` Unauthorized - Invalid or missing API key - `429` Rate limit exceeded ### SDK Host Hooks Device-token doors the partner SDK's host hooks call (reportPlay, setTripState, reportInteraction); the screen is the device's own binding #### POST /v1/partner/device/{deviceId}/interactions Report a rider interaction from the partner SDK (reportInteraction) The partner SDK's `reportInteraction` host hook: what a rider did with this device's screen — a tap, a QR code shown or scanned, an attention prompt — with the creative on screen and how far into it. Stored for measurement only; never billed, and never an ad-lifecycle event (those go to `POST /v1/partner/device/{deviceId}/programmatic-event`). Authenticated with the device token the SDK holds. The screen is this device's own binding and the partner is that screen's partner; the body may not name a screen. Idempotent per device on `interaction_id`: a retried interaction is answered `duplicate` and stored once, and two devices that use the same id report two interactions. `occurred_at` is the device clock and must lie within the last 7 days and at most 5 minutes ahead of the server clock; any other time is refused with 400. - Auth: `DeviceToken` header `X-Device-Token` - Agent: agent_safe=false, idempotent=true, cost_tier=free - operationId: `recordPartnerDeviceInteraction` | Parameter | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `deviceId` | path | `string` | yes | This device, as the SDK addresses it — the external id it was registered with, its canonical fingerprint, or its device id. Must be the device the token was issued to. | | `X-Device-Timestamp` | header | `string` | yes | Request time in epoch milliseconds; must be within the device replay window. | | `X-Device-Nonce` | header | `string` | yes | A fresh value per request (the SDK sends a UUID); a reused nonce is refused 409. | Request body (`application/json`, required): `PartnerInteraction` | Field | Type | Required | Description | | --- | --- | --- | --- | | `creative_id` | `string` | | The creative on screen, as the host names it. | | `interaction_id` | `string` | yes | The host app's id for this interaction (idempotency key, per device). | | `occurred_at` | `string` | yes | When it happened (device clock), within the last 7 days and at most 5 minutes ahead of the server clock. | | `t_ms` | `integer` | | Milliseconds into the creative's playback when it happened. | | `type` | `string`: one of `tap`, `qr_shown`, `qr_scanned`, `dwell_prompt`, `seatbelt_reminder_shown` | yes | What happened. seatbelt_reminder_shown = the host app showed a SeatbeltReminder that agent-core 1.24 delivered to its safety-event listener; send the reminder's eventId as interaction_id. Never a programmatic ad-lifecycle event (those are POST /device/{deviceId}/programmatic-event). | Responses: - `202` Interaction accepted, or a duplicate of this device's prior interaction_id. - `400` Bad request - `401` No device token, a token we did not issue, or a token for no device. - `403` Refused after authentication: the path names another device (`device_token_path_mismatch`), the device is bound to no screen (`device_not_bound_to_screen`), the screen belongs to no partner (`screen_not_partner_bound`) or the partner is not active (`partner_inactive`); or the device credential does not match its request (`DeviceAuthRefusal`). - `409` This X-Device-Nonce was already used (a replayed request). Retry the interaction with a new nonce. - `429` Rate limit exceeded - `503` The replay guard is unavailable; retry. #### POST /v1/partner/device/{deviceId}/plays Report a play from the partner SDK (reportPlay) The partner SDK's `reportPlay` host hook: one log-level play of an ad the host app played on this device's screen, into the same non-billing store as `POST /v1/partner/plays` — the same body without `screen_id`, plus the Trillboards `impression_id` when the host played an ad Trillboards served. Authenticated with the device token the SDK holds, never a partner API key. The screen is this device's own binding and the partner is that screen's partner, so the body may not name a screen: a body carrying `screen_id`, or any field not listed, is refused with 400. Idempotent on `play_id`, shared with `POST /v1/partner/plays`, so a play reported through both is one play. When `impression_id` matches a Trillboards-served play on the same screen, on the same or an adjacent UTC day, or, without one, the same `ad_id` completes within 5 s of one, the Trillboards record of that play is kept and this report is not counted a second time. Measurement plays are never billed. `completed_at` is the device clock and must lie within the last 7 days and at most 5 minutes ahead of the server clock; any other time is refused with 400. - Auth: `DeviceToken` header `X-Device-Token` - Agent: agent_safe=false, idempotent=true, cost_tier=free - operationId: `recordPartnerDevicePlay` | Parameter | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `deviceId` | path | `string` | yes | This device, as the SDK addresses it — the external id it was registered with, its canonical fingerprint, or its device id. Must be the device the token was issued to. | | `X-Device-Timestamp` | header | `string` | yes | Request time in epoch milliseconds; must be within the device replay window. | | `X-Device-Nonce` | header | `string` | yes | A fresh value per request (the SDK sends a UUID); a reused nonce is refused 409. | Request body (`application/json`, required): `PartnerDevicePlay` | Field | Type | Required | Description | | --- | --- | --- | --- | | `ad_id` | `string` | | Optional ad/line identifier; defaults to the sha-keyed creative. | | `completed_at` | `string` | yes | When the play completed (device clock), within the last 7 days and at most 5 minutes ahead of the server clock. | | `creative_ref` | `string` | yes | The classification reference from POST /creatives — `sha256:` or the bare 64-char content hash. | | `duration_seconds` | `number` | | Play duration in seconds (default 30). | | `impression_id` | `string` | | The Trillboards impression id, when the host played an ad Trillboards served. The Trillboards record of that play is then kept and this report is not counted twice. | | `play_id` | `string` | yes | Your unique id for this play (idempotency key, shared with POST /v1/partner/plays). | | `request_id` | `string` | | Optional request identifier. | Responses: - `202` Play accepted, or a duplicate of a prior play_id. - `400` Bad request - `401` No device token, a token we did not issue, or a token for no device. - `403` Refused after authentication: the path names another device (`device_token_path_mismatch`), the device is bound to no screen (`device_not_bound_to_screen`), the screen belongs to no partner (`screen_not_partner_bound`) or the partner is not active (`partner_inactive`); or the device credential does not match its request (`DeviceAuthRefusal`). - `409` This X-Device-Nonce was already used (a replayed request). Retry the play with a new nonce. - `429` Rate limit exceeded - `503` The replay guard is unavailable; retry. #### POST /v1/partner/device/{deviceId}/trips Report a taxi-meter state change from the partner SDK (setTripState) The partner SDK's `setTripState` host hook: one meter state change — meter on or off, fare, tip, payment type, riders, destination — on this device's screen. Stored for measurement only; never billed. Authenticated with the device token the SDK holds. The screen is this device's own binding and the partner is that screen's partner; the body may not name a screen. Idempotent per device on (`trip_id`, `event_seq`): `event_seq` increases within a trip and a retry re-sends the same value, so a retried event is answered `duplicate` and stored once. Hosts number trips per vehicle, so two devices that both report trip `1` report two trips. `state_at` is the device clock and must lie within the last 7 days and at most 5 minutes ahead of the server clock; any other time is refused with 400. - Auth: `DeviceToken` header `X-Device-Token` - Agent: agent_safe=false, idempotent=true, cost_tier=free - operationId: `recordPartnerDeviceTripState` | Parameter | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `deviceId` | path | `string` | yes | This device, as the SDK addresses it — the external id it was registered with, its canonical fingerprint, or its device id. Must be the device the token was issued to. | | `X-Device-Timestamp` | header | `string` | yes | Request time in epoch milliseconds; must be within the device replay window. | | `X-Device-Nonce` | header | `string` | yes | A fresh value per request (the SDK sends a UUID); a reused nonce is refused 409. | Request body (`application/json`, required): `PartnerTripState` | Field | Type | Required | Description | | --- | --- | --- | --- | | `destination` | `string` | | The host's destination text or zone. | | `event_seq` | `integer` | yes | The event's position in the trip. Increases within a trip; a retry re-sends the same value (idempotency key with trip_id, per device). | | `fare_cents` | `integer` | | Fare so far, in the smallest currency unit. | | `meter_on` | `boolean` | yes | true while the meter runs (a hired trip). | | `passenger_count` | `integer` | | Riders the host counted. | | `payment_type` | `string` | | The host's payment type (stored trimmed and lowercased). | | `state_at` | `string` | yes | When the meter changed state (device clock), within the last 7 days and at most 5 minutes ahead of the server clock. | | `tip_cents` | `integer` | | Tip, in the smallest currency unit. | | `trip_id` | `string` | yes | The host app's trip id. Unique per device, not per partner. | Responses: - `202` Event accepted, or a duplicate of this device's prior (trip_id, event_seq). - `400` Bad request - `401` No device token, a token we did not issue, or a token for no device. - `403` Refused after authentication: the path names another device (`device_token_path_mismatch`), the device is bound to no screen (`device_not_bound_to_screen`), the screen belongs to no partner (`screen_not_partner_bound`) or the partner is not active (`partner_inactive`); or the device credential does not match its request (`DeviceAuthRefusal`). - `409` This X-Device-Nonce was already used (a replayed request). Retry the event with a new nonce. - `429` Rate limit exceeded - `503` The replay guard is unavailable; retry. ### Ads Ad serving endpoints #### GET /v1/partner/device/{deviceId}/ads Get ads for device **SDK Endpoint** - Returns ads for the specified device. This endpoint is called by the Trillboards Lite SDK. It supports ETag caching for SDK ad-catalog responses to minimize bandwidth usage and request fan-out. Browser language is accepted through the optional `lang` query parameter. If omitted, the server uses the standard `Accept-Language` request header and emits its ISO-639-1 alpha-2 primary language in the bidder-facing request. If header bidding is enabled for the screen, the response includes `header_bidding_settings` with dynamic VAST waterfall URLs for programmatic playback. Dynamic waterfall catalog responses intentionally preserve the five-minute SDK cache contract; clients fetch the returned VAST URLs when they actually attempt playback. Server-side source health may calculate request-pressure decisions for first-party upstream fetches, but the catalog keeps SQL/Admin-enabled demand sources eligible and visible. No authentication required - device is identified by fingerprint or external device ID. **The response carries TWO independent demand rails.** **1. `data.ads[]` — DIRECT BOOKINGS ONLY. Never programmatic.** Everything in this array is a first-party booking against this specific screen: a paid direct advertiser buy, a partner self-promo creative uploaded through the partner CMS, or the Trillboards instant-QR house ad. There is no DSP, no auction, and no bid in `ads[]`. If you are looking for programmatic demand and reading only this array, you will conclude we have none. **2. `data.header_bidding_settings.vast_waterfall.sources[]` — ALL programmatic demand.** Every DSP/SSP source lives here and nowhere else. **Walk the whole array in `priority` ASCENDING order** and stop at the first source that actually plays; advance on every failure class (no-fill, empty VAST, zero-``, transport error, per-source timeout, IMA load error, IMA playback error). `priority: 0` is real and valid, and gaps in the values are normal — treat `priority` as an opaque ascending sort key, never an index. `vast_tag_url` is **an alias of `sources[0].vast_url`**, present only for legacy single-tag players. It is not "the" tag: a player that reads it and stops has skipped every other source in the waterfall. This is the single most expensive integration bug we see. The waterfall may also contain a `trillboards_direct` source. That is the same direct booking as rail 1, bridged into VAST for BYO-IMA players — it is not programmatic demand. **Non-IMA / native players must fire their own tracking.** Google IMA SDK fires the VAST-embedded pixels for you. **A raw `