{"openapi":"3.1.0","info":{"title":"OpenAD API","version":"1.0.0","summary":"Independent OpenAD advertising, evidence and settlement API.","description":"Contract-first API of the OpenAD platform (task OPENAD-EXEC-20260912-01).\nAPP (app.cogiens.com/openad) and CP (cp.cogiens.com/openad) integrate exclusively through\nthis API with short-lived OIDC access tokens; they never access the OpenAD database.\nEvery operation declares `x-milestone` (delivery milestone) and `x-permission` (RBAC permission,\nor `public` / `authenticated` / `device`).\n"},"servers":[{"url":"https://api.openad.cogiens.com","description":"Production entry (disabled until M6 gates and separate authorization)"},{"url":"http://127.0.0.1:8080","description":"Local isolated development"}],"security":[{"cogiensOidc":[]}],"tags":[{"name":"system"},{"name":"identity"},{"name":"tenancy"},{"name":"audit"}],"paths":{"/healthz":{"get":{"operationId":"getHealth","tags":["system"],"summary":"Liveness probe","security":[],"x-milestone":0,"x-permission":"public","responses":{"200":{"description":"Process is alive","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health"}}}}}}},"/readyz":{"get":{"operationId":"getReadiness","tags":["system"],"summary":"Readiness probe (database reachable and migrations current)","security":[],"x-milestone":0,"x-permission":"public","responses":{"200":{"description":"Ready","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Readiness"}}}},"503":{"description":"Not ready","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Readiness"}}}}}}},"/metrics":{"get":{"operationId":"getMetrics","tags":["system"],"summary":"Prometheus metrics for the private monitoring network (metrics bearer token; 404 unless configured)","security":[],"x-milestone":6,"x-permission":"public","responses":{"200":{"description":"Prometheus text exposition format 0.0.4","content":{"text/plain":{"schema":{"type":"string"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/openapi.json":{"get":{"operationId":"getOpenApiDocument","tags":["system"],"summary":"This contract as JSON","security":[],"x-milestone":0,"x-permission":"public","responses":{"200":{"description":"OpenAPI document","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/me":{"get":{"operationId":"getMe","tags":["identity"],"summary":"Resolve the calling principal, active tenant, roles and permissions","x-milestone":0,"x-permission":"authenticated","parameters":[{"$ref":"#/components/parameters/TenantHeader"},{"$ref":"#/components/parameters/TraceId"}],"responses":{"200":{"description":"Principal","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Me"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/tenants":{"get":{"operationId":"listTenants","tags":["tenancy"],"summary":"List tenants visible to the caller","x-milestone":0,"x-permission":"tenant:read","parameters":[{"$ref":"#/components/parameters/TenantHeader"},{"$ref":"#/components/parameters/TraceId"},{"$ref":"#/components/parameters/Limit"},{"name":"after","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Tenants","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TenantList"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"post":{"operationId":"createTenant","tags":["tenancy"],"summary":"Create a tenant (platform administrators)","x-milestone":0,"x-permission":"tenant:create","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/TraceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TenantCreate"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Tenant"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"}}}},"/v1/tenants/{tenantId}":{"get":{"operationId":"getTenant","tags":["tenancy"],"summary":"Get a tenant","x-milestone":0,"x-permission":"tenant:read","parameters":[{"$ref":"#/components/parameters/TenantIdPath"},{"$ref":"#/components/parameters/TenantHeader"},{"$ref":"#/components/parameters/TraceId"}],"responses":{"200":{"description":"Tenant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Tenant"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/tenants/{tenantId}/status":{"post":{"operationId":"changeTenantStatus","tags":["tenancy"],"summary":"Suspend, reactivate or close a tenant (audited, reason required)","x-milestone":0,"x-permission":"tenant:suspend","parameters":[{"$ref":"#/components/parameters/TenantIdPath"},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/TraceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TenantStatusChange"}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Tenant"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"}}}},"/v1/role-assignments":{"post":{"operationId":"createRoleAssignment","tags":["identity"],"summary":"Grant a role to an identity (tenant admins within their tenant; platform admins for platform roles)","x-milestone":0,"x-permission":"member:manage","parameters":[{"$ref":"#/components/parameters/TenantHeader"},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/TraceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoleAssignmentCreate"}}}},"responses":{"201":{"description":"Granted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoleAssignment"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"}}}},"/v1/audit-events":{"get":{"operationId":"listAuditEvents","tags":["audit"],"summary":"List audit events visible to the caller (newest first)","x-milestone":0,"x-permission":"audit:read","parameters":[{"$ref":"#/components/parameters/TenantHeader"},{"$ref":"#/components/parameters/TraceId"},{"$ref":"#/components/parameters/Limit"},{"name":"before_seq","in":"query","required":false,"schema":{"type":"integer","minimum":1}}],"responses":{"200":{"description":"Audit events","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditEventList"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/audit-events/verification":{"get":{"operationId":"verifyAuditChain","tags":["audit"],"summary":"Recompute the audit hash chain (platform auditors)","x-milestone":0,"x-permission":"audit:export","parameters":[{"$ref":"#/components/parameters/TraceId"}],"responses":{"200":{"description":"Verification result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditChainVerification"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/onboarding":{"post":{"operationId":"selfOnboard","tags":["identity"],"summary":"Self-onboard the calling identity as advertiser, contributor or venue operator (pilot whitelisting is separate)","x-milestone":1,"x-permission":"authenticated","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/TraceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OnboardingRequest"}}}},"responses":{"201":{"description":"Onboarded tenant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Tenant"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"}}}},"/v1/platform/signing-keys":{"get":{"operationId":"getPlatformSigningKeys","tags":["devices"],"summary":"Platform Ed25519 public keys used to sign device policies and manifests","security":[],"x-milestone":1,"x-permission":"public","responses":{"200":{"description":"Keys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlatformSigningKeys"}}}}}}},"/v1/venues":{"get":{"operationId":"listVenues","tags":["screens"],"summary":"List venues","x-milestone":1,"x-permission":"venue:read","parameters":[{"$ref":"#/components/parameters/TenantHeader"},{"$ref":"#/components/parameters/TraceId"},{"$ref":"#/components/parameters/Limit"},{"name":"after","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Venues","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VenueList"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"post":{"operationId":"createVenue","tags":["screens"],"summary":"Register a venue (public venues require a posted notice before camera measurement)","x-milestone":1,"x-permission":"venue:manage","parameters":[{"$ref":"#/components/parameters/TenantHeader"},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/TraceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VenueCreate"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Venue"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"}}}},"/v1/venues/{venueId}":{"get":{"operationId":"getVenue","tags":["screens"],"summary":"Get a venue","x-milestone":1,"x-permission":"venue:read","parameters":[{"$ref":"#/components/parameters/VenueIdPath"},{"$ref":"#/components/parameters/TenantHeader"},{"$ref":"#/components/parameters/TraceId"}],"responses":{"200":{"description":"Venue","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Venue"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/venues/{venueId}/notice":{"post":{"operationId":"updateVenueNotice","tags":["screens"],"summary":"Record that the public camera-measurement notice was posted or removed (with evidence hash)","x-milestone":1,"x-permission":"venue:manage","parameters":[{"$ref":"#/components/parameters/VenueIdPath"},{"$ref":"#/components/parameters/TenantHeader"},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/TraceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VenueNoticeUpdate"}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Venue"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"}}}},"/v1/screens":{"get":{"operationId":"listScreens","tags":["screens"],"summary":"List screens","x-milestone":1,"x-permission":"screen:read","parameters":[{"$ref":"#/components/parameters/TenantHeader"},{"$ref":"#/components/parameters/TraceId"},{"$ref":"#/components/parameters/Limit"},{"name":"after","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"venue_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Screens","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScreenList"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"post":{"operationId":"createScreen","tags":["screens"],"summary":"Register a screen in a venue (pending activation)","x-milestone":1,"x-permission":"screen:manage","parameters":[{"$ref":"#/components/parameters/TenantHeader"},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/TraceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScreenCreate"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Screen"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"}}}},"/v1/screens/{screenId}":{"get":{"operationId":"getScreen","tags":["screens"],"summary":"Get a screen","x-milestone":1,"x-permission":"screen:read","parameters":[{"$ref":"#/components/parameters/ScreenIdPath"},{"$ref":"#/components/parameters/TenantHeader"},{"$ref":"#/components/parameters/TraceId"}],"responses":{"200":{"description":"Screen","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Screen"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/screens/{screenId}/status":{"post":{"operationId":"changeScreenStatus","tags":["screens"],"summary":"Suspend, reactivate or retire a screen (retirement revokes its device key)","x-milestone":1,"x-permission":"screen:manage","parameters":[{"$ref":"#/components/parameters/ScreenIdPath"},{"$ref":"#/components/parameters/TenantHeader"},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/TraceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScreenStatusChange"}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Screen"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"}}}},"/v1/screens/{screenId}/playback-policy":{"get":{"operationId":"getPlaybackPolicy","tags":["screens"],"summary":"Current contributor playback preferences for a screen","x-milestone":1,"x-permission":"screen:read","parameters":[{"$ref":"#/components/parameters/ScreenIdPath"},{"$ref":"#/components/parameters/TenantHeader"},{"$ref":"#/components/parameters/TraceId"}],"responses":{"200":{"description":"Current version","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlaybackPolicyVersion"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"put":{"operationId":"setPlaybackPolicy","tags":["screens"],"summary":"Publish a new version of the playback preferences (categories, daily time, windows, volume)","x-milestone":1,"x-permission":"screen:manage","parameters":[{"$ref":"#/components/parameters/ScreenIdPath"},{"$ref":"#/components/parameters/TenantHeader"},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/TraceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlaybackPreferences"}}}},"responses":{"200":{"description":"New version","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlaybackPolicyVersion"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"}}}},"/v1/screens/{screenId}/activation-codes":{"post":{"operationId":"createActivationCode","tags":["screens"],"summary":"Issue a one-time activation code (15 minutes) to pair a player with the screen","x-milestone":1,"x-permission":"screen:manage","parameters":[{"$ref":"#/components/parameters/ScreenIdPath"},{"$ref":"#/components/parameters/TenantHeader"},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/TraceId"}],"responses":{"201":{"description":"Code (shown once; only its hash is stored)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ActivationCode"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"}}}},"/v1/screens/{screenId}/device-keys":{"get":{"operationId":"listDeviceKeys","tags":["screens"],"summary":"Device key history of a screen","x-milestone":1,"x-permission":"screen:read","parameters":[{"$ref":"#/components/parameters/ScreenIdPath"},{"$ref":"#/components/parameters/TenantHeader"},{"$ref":"#/components/parameters/TraceId"}],"responses":{"200":{"description":"Keys","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeviceKeyList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/screens/{screenId}/device-keys/{keyId}/revoke":{"post":{"operationId":"revokeDeviceKey","tags":["screens"],"summary":"Revoke a device key immediately (lost or compromised player)","x-milestone":1,"x-permission":"screen:manage","parameters":[{"$ref":"#/components/parameters/ScreenIdPath"},{"name":"keyId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/TenantHeader"},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/TraceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReasonBody"}}}},"responses":{"200":{"description":"Revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeviceKey"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"}}}},"/v1/screens/{screenId}/heartbeats":{"get":{"operationId":"listScreenHeartbeats","tags":["screens"],"summary":"Latest heartbeats received from the screen's players","x-milestone":1,"x-permission":"screen:read","parameters":[{"$ref":"#/components/parameters/ScreenIdPath"},{"$ref":"#/components/parameters/TenantHeader"},{"$ref":"#/components/parameters/TraceId"},{"$ref":"#/components/parameters/Limit"}],"responses":{"200":{"description":"Heartbeats","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HeartbeatList"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/consents":{"get":{"operationId":"listConsents","tags":["consent"],"summary":"Current consent state and full history for a screen or venue","x-milestone":1,"x-permission":"consent:read","parameters":[{"$ref":"#/components/parameters/TenantHeader"},{"$ref":"#/components/parameters/TraceId"},{"name":"target_type","in":"query","required":true,"schema":{"enum":["screen","venue"]}},{"name":"target_id","in":"query","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Consent state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConsentState"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"post":{"operationId":"recordConsent","tags":["consent"],"summary":"Grant or withdraw consent (append-only; withdrawal applies at the next device policy fetch)","x-milestone":1,"x-permission":"consent:manage","parameters":[{"$ref":"#/components/parameters/TenantHeader"},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/TraceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConsentCreate"}}}},"responses":{"201":{"description":"Recorded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConsentRecord"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"}}}},"/v1/devices/activate":{"post":{"operationId":"activateDevice","tags":["devices"],"summary":"Pair a player using a one-time code and proof of possession of its locally generated Ed25519 key","security":[],"x-milestone":1,"x-permission":"public","parameters":[{"$ref":"#/components/parameters/TraceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeviceActivation"}}}},"responses":{"201":{"description":"Activated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeviceActivationResult"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"409":{"$ref":"#/components/responses/Conflict"}}}},"/v1/device/heartbeats":{"post":{"operationId":"submitHeartbeats","tags":["devices"],"summary":"Submit heartbeats (live or offline backlog, idempotent by boot_id+seq)","security":[{"deviceSignature":[]}],"x-milestone":1,"x-permission":"device:heartbeat","parameters":[{"$ref":"#/components/parameters/DeviceKey"},{"$ref":"#/components/parameters/DeviceTimestamp"},{"$ref":"#/components/parameters/DeviceNonce"},{"$ref":"#/components/parameters/DeviceSignature"},{"$ref":"#/components/parameters/TraceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HeartbeatBatch"}}}},"responses":{"200":{"description":"Batch result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HeartbeatBatchResult"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/device/capabilities":{"post":{"operationId":"reportCapabilities","tags":["devices"],"summary":"Report probed player capabilities (camera availability/permission, models, display)","security":[{"deviceSignature":[]}],"x-milestone":1,"x-permission":"device:heartbeat","parameters":[{"$ref":"#/components/parameters/DeviceKey"},{"$ref":"#/components/parameters/DeviceTimestamp"},{"$ref":"#/components/parameters/DeviceNonce"},{"$ref":"#/components/parameters/DeviceSignature"},{"$ref":"#/components/parameters/TraceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeviceCapabilities"}}}},"responses":{"200":{"description":"Recorded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CapabilityReportResult"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/device/policy":{"get":{"operationId":"getDevicePolicy","tags":["devices"],"summary":"Platform-signed device policy (participation, camera/demographic permissions, preferences)","security":[{"deviceSignature":[]}],"x-milestone":1,"x-permission":"device:manifest_read","parameters":[{"$ref":"#/components/parameters/DeviceKey"},{"$ref":"#/components/parameters/DeviceTimestamp"},{"$ref":"#/components/parameters/DeviceNonce"},{"$ref":"#/components/parameters/DeviceSignature"},{"$ref":"#/components/parameters/TraceId"}],"responses":{"200":{"description":"Signed policy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignedDevicePolicy"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/device/keys/rotate":{"post":{"operationId":"rotateDeviceKey","tags":["devices"],"summary":"Rotate the device key (request signed by the current key, proof signed by the new key)","security":[{"deviceSignature":[]}],"x-milestone":1,"x-permission":"device:key_rotate","parameters":[{"$ref":"#/components/parameters/DeviceKey"},{"$ref":"#/components/parameters/DeviceTimestamp"},{"$ref":"#/components/parameters/DeviceNonce"},{"$ref":"#/components/parameters/DeviceSignature"},{"$ref":"#/components/parameters/TraceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeyRotation"}}}},"responses":{"200":{"description":"Rotated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeyRotationResult"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"}}}},"/v1/advertiser-profile":{"get":{"operationId":"getAdvertiserProfile","tags":["advertising"],"summary":"Advertiser profile of the active tenant","x-milestone":2,"x-permission":"advertiser:read","parameters":[{"$ref":"#/components/parameters/TenantHeader"},{"$ref":"#/components/parameters/TraceId"}],"responses":{"200":{"description":"Profile","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdvertiserProfile"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"put":{"operationId":"upsertAdvertiserProfile","tags":["advertising"],"summary":"Create or update the advertiser profile (advertiser tenants only)","x-milestone":2,"x-permission":"advertiser:manage","parameters":[{"$ref":"#/components/parameters/TenantHeader"},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/TraceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdvertiserProfileInput"}}}},"responses":{"200":{"description":"Profile","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdvertiserProfile"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"}}}},"/v1/contracts":{"get":{"operationId":"listContracts","tags":["advertising"],"summary":"Contracts visible to the caller (advertisers see their own; finance sees all)","x-milestone":2,"x-permission":"contract:read","parameters":[{"$ref":"#/components/parameters/TenantHeader"},{"$ref":"#/components/parameters/TraceId"},{"name":"advertiser_tenant_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Contracts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContractList"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"post":{"operationId":"createContract","tags":["advertising"],"summary":"Create a draft advertiser contract with rate card and credit limit (finance)","x-milestone":2,"x-permission":"contract:manage","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/TraceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContractCreate"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contract"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"}}}},"/v1/contracts/{contractId}/status":{"post":{"operationId":"changeContractStatus","tags":["advertising"],"summary":"Activate or terminate a contract (terms freeze on activation)","x-milestone":2,"x-permission":"contract:manage","parameters":[{"name":"contractId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/TraceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContractStatusChange"}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contract"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"}}}},"/v1/topups":{"post":{"operationId":"createTopup","tags":["funding"],"summary":"Start a prepaid top-up through the sandbox payment provider (no real funds in P1)","x-milestone":2,"x-permission":"funding:topup","parameters":[{"$ref":"#/components/parameters/TenantHeader"},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/TraceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TopupCreate"}}}},"responses":{"201":{"description":"Pending payment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payment"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"}}}},"/v1/webhooks/payments/sandbox":{"post":{"operationId":"sandboxPaymentWebhook","tags":["funding"],"summary":"Sandbox payment provider callback (HMAC-signed, idempotent by event id)","security":[],"x-milestone":2,"x-permission":"public","parameters":[{"name":"x-openad-sandbox-signature","in":"header","required":true,"schema":{"type":"string","pattern":"^t=[0-9]+,v1=[0-9a-f]{64}$"}},{"$ref":"#/components/parameters/TraceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxPaymentEvent"}}}},"responses":{"200":{"description":"Processed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payment"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"}}}},"/v1/payments":{"get":{"operationId":"listPayments","tags":["funding"],"summary":"Payments of the active tenant (finance sees all)","x-milestone":2,"x-permission":"ledger:read","parameters":[{"$ref":"#/components/parameters/TenantHeader"},{"$ref":"#/components/parameters/TraceId"},{"$ref":"#/components/parameters/Limit"}],"responses":{"200":{"description":"Payments","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentList"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/advertiser-balance":{"get":{"operationId":"getAdvertiserBalance","tags":["funding"],"summary":"Prepaid, reserved and credit balances derived from the ledger","x-milestone":2,"x-permission":"ledger:read","parameters":[{"$ref":"#/components/parameters/TenantHeader"},{"$ref":"#/components/parameters/TraceId"},{"name":"currency","in":"query","required":true,"schema":{"type":"string","pattern":"^[A-Z]{3}$"}}],"responses":{"200":{"description":"Balance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdvertiserBalance"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/creative-uploads":{"post":{"operationId":"uploadCreativeAsset","tags":["creatives"],"summary":"Upload a creative asset; content is sniffed, scanned and stored only if clean","x-milestone":2,"x-permission":"creative:manage","parameters":[{"$ref":"#/components/parameters/TenantHeader"},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/TraceId"}],"requestBody":{"required":true,"content":{"image/png":{"schema":{"type":"string","contentMediaType":"image/png"}},"image/jpeg":{"schema":{"type":"string","contentMediaType":"image/jpeg"}},"image/gif":{"schema":{"type":"string","contentMediaType":"image/gif"}},"image/webp":{"schema":{"type":"string","contentMediaType":"image/webp"}},"video/mp4":{"schema":{"type":"string","contentMediaType":"video/mp4"}},"video/webm":{"schema":{"type":"string","contentMediaType":"video/webm"}}}},"responses":{"201":{"description":"Clean upload stored","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreativeUpload"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"413":{"$ref":"#/components/responses/BadRequest"},"415":{"$ref":"#/components/responses/BadRequest"},"422":{"$ref":"#/components/responses/Unprocessable"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/creatives":{"get":{"operationId":"listCreatives","tags":["creatives"],"summary":"Creatives of the active tenant","x-milestone":2,"x-permission":"creative:read","parameters":[{"$ref":"#/components/parameters/TenantHeader"},{"$ref":"#/components/parameters/TraceId"},{"$ref":"#/components/parameters/Limit"}],"responses":{"200":{"description":"Creatives","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreativeList"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"post":{"operationId":"createCreative","tags":["creatives"],"summary":"Create a creative (content lives in immutable versions)","x-milestone":2,"x-permission":"creative:manage","parameters":[{"$ref":"#/components/parameters/TenantHeader"},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/TraceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreativeCreate"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Creative"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"}}}},"/v1/creatives/{creativeId}":{"get":{"operationId":"getCreative","tags":["creatives"],"summary":"Creative with all versions","x-milestone":2,"x-permission":"creative:read","parameters":[{"$ref":"#/components/parameters/CreativeIdPath"},{"$ref":"#/components/parameters/TenantHeader"},{"$ref":"#/components/parameters/TraceId"}],"responses":{"200":{"description":"Creative","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreativeDetail"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/creatives/{creativeId}/versions":{"post":{"operationId":"createCreativeVersion","tags":["creatives"],"summary":"Create a new immutable version (runs landing page check and machine pre-review)","x-milestone":2,"x-permission":"creative:manage","parameters":[{"$ref":"#/components/parameters/CreativeIdPath"},{"$ref":"#/components/parameters/TenantHeader"},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/TraceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreativeVersionCreate"}}}},"responses":{"201":{"description":"Draft version","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreativeVersion"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"}}}},"/v1/creatives/{creativeId}/versions/{version}/submit":{"post":{"operationId":"submitCreativeVersion","tags":["creatives"],"summary":"Submit a draft version for review (machine reject ends review; otherwise queued for a human reviewer)","x-milestone":2,"x-permission":"creative:manage","parameters":[{"$ref":"#/components/parameters/CreativeIdPath"},{"$ref":"#/components/parameters/VersionPath"},{"$ref":"#/components/parameters/TenantHeader"},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/TraceId"}],"responses":{"200":{"description":"Submitted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreativeVersion"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"}}}},"/v1/creatives/{creativeId}/versions/{version}/takedown":{"post":{"operationId":"takedownCreativeVersion","tags":["creatives"],"summary":"Emergency takedown of an approved creative version (effective at next player policy sync)","x-milestone":2,"x-permission":"campaign:emergency_stop","parameters":[{"$ref":"#/components/parameters/CreativeIdPath"},{"$ref":"#/components/parameters/VersionPath"},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/TraceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReasonBody"}}}},"responses":{"200":{"description":"Taken down","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreativeVersion"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"}}}},"/v1/reviews/queue":{"get":{"operationId":"listReviewQueue","tags":["reviews"],"summary":"Creative versions and campaigns awaiting human review","x-milestone":2,"x-permission":"creative:review","parameters":[{"$ref":"#/components/parameters/TraceId"}],"responses":{"200":{"description":"Queue","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReviewQueue"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/reviews/creative-versions/{versionId}":{"post":{"operationId":"decideCreativeVersion","tags":["reviews"],"summary":"Human review decision for a creative version (reviewer may not be the author)","x-milestone":2,"x-permission":"creative:review","parameters":[{"name":"versionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/TraceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReviewDecision"}}}},"responses":{"200":{"description":"Decided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreativeVersion"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"}}}},"/v1/reviews/campaigns/{campaignId}":{"post":{"operationId":"decideCampaign","tags":["reviews"],"summary":"Human review decision for a submitted campaign","x-milestone":2,"x-permission":"creative:review","parameters":[{"$ref":"#/components/parameters/CampaignIdPath"},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/TraceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReviewDecision"}}}},"responses":{"200":{"description":"Decided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Campaign"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"}}}},"/v1/campaigns":{"get":{"operationId":"listCampaigns","tags":["campaigns"],"summary":"Campaigns visible to the caller","x-milestone":2,"x-permission":"campaign:read","parameters":[{"$ref":"#/components/parameters/TenantHeader"},{"$ref":"#/components/parameters/TraceId"},{"$ref":"#/components/parameters/Limit"},{"name":"status","in":"query","required":false,"schema":{"$ref":"#/components/schemas/CampaignStatus"}}],"responses":{"200":{"description":"Campaigns","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignList"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"post":{"operationId":"createCampaign","tags":["campaigns"],"summary":"Create a DRAFT campaign under an active contract","x-milestone":2,"x-permission":"campaign:manage","parameters":[{"$ref":"#/components/parameters/TenantHeader"},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/TraceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignInput"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Campaign"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"}}}},"/v1/campaigns/{campaignId}":{"get":{"operationId":"getCampaign","tags":["campaigns"],"summary":"Campaign with creatives","x-milestone":2,"x-permission":"campaign:read","parameters":[{"$ref":"#/components/parameters/CampaignIdPath"},{"$ref":"#/components/parameters/TenantHeader"},{"$ref":"#/components/parameters/TraceId"}],"responses":{"200":{"description":"Campaign","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Campaign"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"put":{"operationId":"updateCampaign","tags":["campaigns"],"summary":"Replace campaign terms (DRAFT only; revise approved or rejected campaigns first)","x-milestone":2,"x-permission":"campaign:manage","parameters":[{"$ref":"#/components/parameters/CampaignIdPath"},{"$ref":"#/components/parameters/TenantHeader"},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/TraceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignInput"}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Campaign"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"}}}},"/v1/campaigns/{campaignId}/revise":{"$ref":"#/components/pathItems/revise"},"/v1/campaigns/{campaignId}/submit":{"$ref":"#/components/pathItems/submit"},"/v1/campaigns/{campaignId}/fund":{"$ref":"#/components/pathItems/fund"},"/v1/campaigns/{campaignId}/publish":{"$ref":"#/components/pathItems/publish"},"/v1/campaigns/{campaignId}/pause":{"$ref":"#/components/pathItems/pause"},"/v1/campaigns/{campaignId}/resume":{"$ref":"#/components/pathItems/resume"},"/v1/campaigns/{campaignId}/cancel":{"$ref":"#/components/pathItems/cancel"},"/v1/campaigns/{campaignId}/emergency-stop":{"$ref":"#/components/pathItems/emergency-stop"},"/v1/campaigns/{campaignId}/transitions":{"get":{"operationId":"listCampaignTransitions","tags":["campaigns"],"summary":"Complete lifecycle history (actor, reason, time, version, evidence)","x-milestone":2,"x-permission":"campaign:read","parameters":[{"$ref":"#/components/parameters/CampaignIdPath"},{"$ref":"#/components/parameters/TenantHeader"},{"$ref":"#/components/parameters/TraceId"}],"responses":{"200":{"description":"Transitions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignTransitionList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/refunds":{"get":{"operationId":"listRefunds","tags":["funding"],"summary":"Refund requests (advertisers see their own; finance sees all)","x-milestone":2,"x-permission":"ledger:read","parameters":[{"$ref":"#/components/parameters/TenantHeader"},{"$ref":"#/components/parameters/TraceId"}],"responses":{"200":{"description":"Refunds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefundList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"post":{"operationId":"requestRefund","tags":["funding"],"summary":"Request a refund of unreserved prepaid balance","x-milestone":2,"x-permission":"refund:request","parameters":[{"$ref":"#/components/parameters/TenantHeader"},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/TraceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefundCreate"}}}},"responses":{"201":{"description":"Requested","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Refund"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"}}}},"/v1/refunds/{refundId}/decision":{"post":{"operationId":"decideRefund","tags":["funding"],"summary":"Approve (and pay out through the sandbox) or reject a refund request (finance)","x-milestone":2,"x-permission":"refund:approve","parameters":[{"name":"refundId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/TraceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Decision"}}}},"responses":{"200":{"description":"Decided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Refund"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"}}}},"/v1/invoices":{"get":{"operationId":"listInvoices","tags":["funding"],"summary":"Invoice requests and issued invoices","x-milestone":2,"x-permission":"invoice:read","parameters":[{"$ref":"#/components/parameters/TenantHeader"},{"$ref":"#/components/parameters/TraceId"}],"responses":{"200":{"description":"Invoices","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}},"post":{"operationId":"requestInvoice","tags":["funding"],"summary":"Request an invoice for paid amounts (tax separately stated)","x-milestone":2,"x-permission":"invoice:request","parameters":[{"$ref":"#/components/parameters/TenantHeader"},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/TraceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceCreate"}}}},"responses":{"201":{"description":"Requested","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invoice"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"}}}},"/v1/invoices/{invoiceId}/issue":{"$ref":"#/components/pathItems/issue"},"/v1/invoices/{invoiceId}/reject":{"$ref":"#/components/pathItems/reject"},"/v1/invoices/{invoiceId}/void":{"$ref":"#/components/pathItems/void"},"/v1/ops/campaign-scheduler/run":{"post":{"operationId":"runCampaignScheduler","tags":["operations"],"summary":"Advance scheduled, serving and paused campaigns by time (also run by the scheduler worker)","x-milestone":2,"x-permission":"policy:manage","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/TraceId"}],"responses":{"200":{"description":"Advanced campaigns","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulerRun"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"}}}},"/v1/device/manifest":{"get":{"operationId":"getDeviceManifest","tags":["devices"],"summary":"Platform-signed delivery manifest (eligible campaigns and creatives, attention rules)","security":[{"deviceSignature":[]}],"x-milestone":3,"x-permission":"device:manifest_read","parameters":[{"$ref":"#/components/parameters/DeviceKey"},{"$ref":"#/components/parameters/DeviceTimestamp"},{"$ref":"#/components/parameters/DeviceNonce"},{"$ref":"#/components/parameters/DeviceSignature"},{"$ref":"#/components/parameters/TraceId"}],"responses":{"200":{"description":"Signed manifest","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignedManifest"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/device/assets/{sha256}":{"get":{"operationId":"getDeviceAsset","tags":["devices"],"summary":"Download a creative asset that a recent manifest delivered to this screen (verify the SHA-256 before use)","security":[{"deviceSignature":[]}],"x-milestone":3,"x-permission":"device:manifest_read","parameters":[{"name":"sha256","in":"path","required":true,"schema":{"type":"string","pattern":"^[0-9a-f]{64}$"}},{"$ref":"#/components/parameters/DeviceKey"},{"$ref":"#/components/parameters/DeviceTimestamp"},{"$ref":"#/components/parameters/DeviceNonce"},{"$ref":"#/components/parameters/DeviceSignature"},{"$ref":"#/components/parameters/TraceId"}],"responses":{"200":{"description":"Asset bytes","content":{"application/octet-stream":{"schema":{"type":"string","contentMediaType":"application/octet-stream"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/device/evidence":{"post":{"operationId":"submitEvidence","tags":["evidence"],"summary":"Submit signed play and attention evidence (statistics only; idempotent by event_id; offline backlog allowed)","security":[{"deviceSignature":[]}],"x-milestone":3,"x-permission":"device:evidence_submit","parameters":[{"$ref":"#/components/parameters/DeviceKey"},{"$ref":"#/components/parameters/DeviceTimestamp"},{"$ref":"#/components/parameters/DeviceNonce"},{"$ref":"#/components/parameters/DeviceSignature"},{"$ref":"#/components/parameters/TraceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EvidenceBatch"}}}},"responses":{"200":{"description":"Per-item results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EvidenceBatchResult"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/evidence":{"get":{"operationId":"listEvidence","tags":["evidence"],"summary":"Evidence visible to the caller (screen owners, advertisers of the campaign, risk and auditors)","x-milestone":3,"x-permission":"evidence:read","parameters":[{"$ref":"#/components/parameters/TenantHeader"},{"$ref":"#/components/parameters/TraceId"},{"$ref":"#/components/parameters/Limit"},{"name":"campaign_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"screen_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"grade","in":"query","required":false,"schema":{"$ref":"#/components/schemas/EvidenceGrade"}}],"responses":{"200":{"description":"Evidence","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EvidenceList"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/evidence/{evidenceId}":{"get":{"operationId":"getEvidence","tags":["evidence"],"summary":"Evidence with the signed document, device public key, decisions and review — independently verifiable","x-milestone":3,"x-permission":"evidence:read","parameters":[{"$ref":"#/components/parameters/EvidenceIdPath"},{"$ref":"#/components/parameters/TenantHeader"},{"$ref":"#/components/parameters/TraceId"}],"responses":{"200":{"description":"Evidence detail","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EvidenceDetail"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/evidence/{evidenceId}/review":{"post":{"operationId":"reviewEvidence","tags":["evidence"],"summary":"Risk review of suspect (grade C) evidence to A, B or R","x-milestone":3,"x-permission":"fraud:decide","parameters":[{"$ref":"#/components/parameters/EvidenceIdPath"},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/TraceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EvidenceReviewRequest"}}}},"responses":{"200":{"description":"Reviewed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EvidenceDetail"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"}}}},"/v1/campaigns/{campaignId}/evidence-summary":{"get":{"operationId":"getCampaignEvidenceSummary","tags":["evidence"],"summary":"Aggregated verified plays, attention, group views and demographic statistics for a campaign","x-milestone":3,"x-permission":"campaign:read","parameters":[{"$ref":"#/components/parameters/CampaignIdPath"},{"$ref":"#/components/parameters/TenantHeader"},{"$ref":"#/components/parameters/TraceId"}],"responses":{"200":{"description":"Summary","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignEvidenceSummary"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/tax-rules":{"post":{"operationId":"createTaxRule","tags":["settlement"],"summary":"Record a versioned indirect tax rule (separately stated tax deducted from BMR)","x-milestone":4,"x-permission":"settlement:run","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/TraceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxRuleCreate"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxRule"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"}}},"get":{"operationId":"listTaxRules","tags":["settlement"],"summary":"Indirect tax rule versions","x-milestone":4,"x-permission":"settlement:read","parameters":[{"$ref":"#/components/parameters/TraceId"}],"responses":{"200":{"description":"Tax rules","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaxRuleList"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/revenue-share-rules":{"post":{"operationId":"createRevenueShareRule","tags":["settlement"],"summary":"Approve a new revenue share rule version (contributor share never below 5000 bps)","x-milestone":4,"x-permission":"settlement:run","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/TraceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RevenueShareRuleCreate"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RevenueShareRule"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"}}},"get":{"operationId":"listRevenueShareRules","tags":["settlement"],"summary":"Revenue share rule versions","x-milestone":4,"x-permission":"settlement:read","parameters":[{"$ref":"#/components/parameters/TraceId"}],"responses":{"200":{"description":"Rules","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RevenueShareRuleList"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/billing/runs":{"post":{"operationId":"runBilling","tags":["billing"],"summary":"Bill effective evidence not yet billed (each evidence at most once, capped by the reserved budget)","x-milestone":4,"x-permission":"settlement:run","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/TraceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingRunRequest"}}}},"responses":{"200":{"description":"Billing run","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingRunResult"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"}}}},"/v1/billing/lines":{"get":{"operationId":"listBillingLines","tags":["billing"],"summary":"Billing lines visible to the caller (advertiser of the campaign, contributor of the screen, finance)","x-milestone":4,"x-permission":"ledger:read","parameters":[{"$ref":"#/components/parameters/TenantHeader"},{"$ref":"#/components/parameters/Limit"},{"name":"campaign_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/TraceId"}],"responses":{"200":{"description":"Billing lines","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BillingLineList"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/evidence/{evidenceId}/ivt":{"post":{"operationId":"confirmIvt","tags":["billing"],"summary":"Confirm billed evidence as invalid traffic and refund its charge to the advertiser","x-milestone":4,"x-permission":"fraud:decide","parameters":[{"$ref":"#/components/parameters/EvidenceIdPath"},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/TraceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReasonBody"}}}},"responses":{"201":{"description":"IVT confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IvtFinding"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"}}}},"/v1/campaigns/{campaignId}/reconcile":{"post":{"operationId":"reconcileCampaign","tags":["billing"],"summary":"Bill remaining evidence of an ended campaign and release its unused reserved budget","x-milestone":4,"x-permission":"settlement:run","parameters":[{"$ref":"#/components/parameters/CampaignIdPath"},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/TraceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReasonBody"}}}},"responses":{"200":{"description":"Reconciled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignReconciliation"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"}}}},"/v1/settlements":{"post":{"operationId":"calculateSettlement","tags":["settlement"],"summary":"Calculate a settlement from unsettled billing lines and confirmed IVT refunds","x-milestone":4,"x-permission":"settlement:run","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/TraceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SettlementCreate"}}}},"responses":{"201":{"description":"Calculated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SettlementDetail"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"}}},"get":{"operationId":"listSettlements","tags":["settlement"],"summary":"Settlement runs","x-milestone":4,"x-permission":"settlement:read","parameters":[{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/TraceId"}],"responses":{"200":{"description":"Settlements","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SettlementList"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/settlements/{settlementId}":{"get":{"operationId":"getSettlement","tags":["settlement"],"summary":"Settlement with inputs, allocations and compliance ratio","x-milestone":4,"x-permission":"settlement:read","parameters":[{"$ref":"#/components/parameters/SettlementIdPath"},{"$ref":"#/components/parameters/TraceId"}],"responses":{"200":{"description":"Settlement","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SettlementDetail"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/settlements/{settlementId}/post":{"post":{"operationId":"postSettlement","tags":["settlement"],"summary":"Post a calculated settlement to the ledger","x-milestone":4,"x-permission":"settlement:run","parameters":[{"$ref":"#/components/parameters/SettlementIdPath"},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/TraceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReasonBody"}}}},"responses":{"200":{"description":"Posted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SettlementDetail"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"}}}},"/v1/settlements/{settlementId}/discard":{"post":{"operationId":"discardSettlement","tags":["settlement"],"summary":"Discard a calculated settlement that was not posted (releases its inputs)","x-milestone":4,"x-permission":"settlement:run","parameters":[{"$ref":"#/components/parameters/SettlementIdPath"},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/TraceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReasonBody"}}}},"responses":{"200":{"description":"Discarded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SettlementDetail"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"}}}},"/v1/settlements/{settlementId}/reverse":{"post":{"operationId":"reverseSettlement","tags":["settlement"],"summary":"Reverse a posted settlement by an exact mirror journal (inputs become available again)","x-milestone":4,"x-permission":"settlement:reverse","parameters":[{"$ref":"#/components/parameters/SettlementIdPath"},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/TraceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReasonBody"}}}},"responses":{"200":{"description":"Reversed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SettlementDetail"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"}}}},"/v1/settlements/{settlementId}/replay":{"get":{"operationId":"replaySettlement","tags":["settlement"],"summary":"Recompute a settlement and its billing lines from immutable inputs and compare hashes","x-milestone":4,"x-permission":"settlement:read","parameters":[{"$ref":"#/components/parameters/SettlementIdPath"},{"$ref":"#/components/parameters/TraceId"}],"responses":{"200":{"description":"Replay result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SettlementReplay"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Unprocessable"}}}},"/v1/reports/contributor-share":{"get":{"operationId":"getContributorShareReport","tags":["reports"],"summary":"Operational report of the contributor share (>= 50% of BMR) for every settlement","x-milestone":4,"x-permission":"report:read","parameters":[{"$ref":"#/components/parameters/TenantHeader"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/TraceId"}],"responses":{"200":{"description":"Report","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContributorShareReport"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/reconciliations":{"post":{"operationId":"runReconciliation","tags":["settlement"],"summary":"Reconcile ledger, billing, settlements, withdrawals and deposits for a currency","x-milestone":4,"x-permission":"settlement:run","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/TraceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReconciliationRequest"}}}},"responses":{"201":{"description":"Reconciliation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReconciliationRun"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"}}}},"/v1/earnings":{"get":{"operationId":"getEarnings","tags":["earnings"],"summary":"Contributor earnings, payable balance, withdrawals, water coins and AWG offsets","x-milestone":4,"x-permission":"earnings:read","parameters":[{"$ref":"#/components/parameters/TenantHeader"},{"name":"currency","in":"query","required":true,"schema":{"$ref":"#/components/schemas/Currency"}},{"$ref":"#/components/parameters/TraceId"}],"responses":{"200":{"description":"Earnings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Earnings"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/withdrawals":{"post":{"operationId":"requestWithdrawal","tags":["earnings"],"summary":"Request a withdrawal of the payable balance (sandbox payout; funds are held immediately)","x-milestone":4,"x-permission":"withdrawal:request","parameters":[{"$ref":"#/components/parameters/TenantHeader"},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/TraceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WithdrawalCreate"}}}},"responses":{"201":{"description":"Requested","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Withdrawal"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"}}},"get":{"operationId":"listWithdrawals","tags":["earnings"],"summary":"Withdrawals visible to the caller","x-milestone":4,"x-permission":"earnings:read","parameters":[{"$ref":"#/components/parameters/TenantHeader"},{"$ref":"#/components/parameters/Limit"},{"$ref":"#/components/parameters/TraceId"}],"responses":{"200":{"description":"Withdrawals","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WithdrawalList"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/withdrawals/{withdrawalId}/decision":{"post":{"operationId":"decideWithdrawal","tags":["earnings"],"summary":"Approve (sandbox payout) or reject a withdrawal; the requester cannot decide","x-milestone":4,"x-permission":"withdrawal:approve","parameters":[{"$ref":"#/components/parameters/WithdrawalIdPath"},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/TraceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WithdrawalDecision"}}}},"responses":{"200":{"description":"Decided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Withdrawal"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"}}}},"/v1/points-rules":{"post":{"operationId":"createPointsRule","tags":["earnings"],"summary":"Approve a fixed water coin conversion rule version (not transferable, no cash-out)","x-milestone":4,"x-permission":"settlement:run","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/TraceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PointsRuleCreate"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PointsRule"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"}}}},"/v1/points/conversions":{"post":{"operationId":"convertToWaterCoins","tags":["earnings"],"summary":"Convert payable earnings into water coins at the current fixed rule","x-milestone":4,"x-permission":"points:convert","parameters":[{"$ref":"#/components/parameters/TenantHeader"},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/TraceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PointsConversionCreate"}}}},"responses":{"201":{"description":"Converted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PointsConversion"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"}}}},"/v1/points/redemptions":{"post":{"operationId":"redeemWaterCoins","tags":["earnings"],"summary":"Record drinking water consumed with water coins","x-milestone":4,"x-permission":"awg:manage","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/TraceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PointsRedemptionCreate"}}}},"responses":{"201":{"description":"Redeemed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PointsRedemption"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"}}}},"/v1/awg/contracts":{"post":{"operationId":"createAwgContract","tags":["awg"],"summary":"Create an AWG device deposit contract for a contributor","x-milestone":4,"x-permission":"awg:manage","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/TraceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AwgContractCreate"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AwgContract"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"}}},"get":{"operationId":"listAwgContracts","tags":["awg"],"summary":"AWG deposit contracts with outstanding deposit and offset election","x-milestone":4,"x-permission":"earnings:read","parameters":[{"$ref":"#/components/parameters/TenantHeader"},{"$ref":"#/components/parameters/TraceId"}],"responses":{"200":{"description":"Contracts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AwgContractList"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/awg/contracts/{contractId}/activate":{"post":{"operationId":"activateAwgContract","tags":["awg"],"summary":"Activate a signed deposit contract (books the deposit receivable)","x-milestone":4,"x-permission":"awg:manage","parameters":[{"$ref":"#/components/parameters/AwgContractIdPath"},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/TraceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReasonBody"}}}},"responses":{"200":{"description":"Activated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AwgContract"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"}}}},"/v1/awg/contracts/{contractId}/election":{"post":{"operationId":"electAwgOffset","tags":["awg"],"summary":"Contributor's explicit choice to offset (or stop offsetting) earnings against the deposit","x-milestone":4,"x-permission":"awg:offset_elect","parameters":[{"$ref":"#/components/parameters/AwgContractIdPath"},{"$ref":"#/components/parameters/TenantHeader"},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/TraceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AwgElectionRequest"}}}},"responses":{"200":{"description":"Recorded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AwgContract"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"}}}},"/v1/awg/offsets/runs":{"post":{"operationId":"applyAwgOffsets","tags":["awg"],"summary":"Apply payable earnings to deposits of contracts with an active election","x-milestone":4,"x-permission":"awg:manage","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/TraceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AwgOffsetRunRequest"}}}},"responses":{"200":{"description":"Offsets applied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AwgOffsetRunResult"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"}}}},"/v1/awg/contracts/{contractId}/terminate":{"post":{"operationId":"terminateAwgContract","tags":["awg"],"summary":"Terminate a contract; any outstanding deposit is written off by journal","x-milestone":4,"x-permission":"awg:manage","parameters":[{"$ref":"#/components/parameters/AwgContractIdPath"},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/TraceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReasonBody"}}}},"responses":{"200":{"description":"Terminated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AwgContract"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"}}}},"/v1/appeals":{"post":{"operationId":"submitAppeal","tags":["appeals"],"summary":"Open an appeal about a decision, charge, earnings or evidence grade visible to the tenant","x-milestone":5,"x-permission":"appeal:submit","parameters":[{"$ref":"#/components/parameters/TenantHeader"},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/TraceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppealCreate"}}}},"responses":{"201":{"description":"Opened","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Appeal"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"}}},"get":{"operationId":"listAppeals","tags":["appeals"],"summary":"Appeals opened by the caller's tenant","x-milestone":5,"x-permission":"appeal:submit","parameters":[{"$ref":"#/components/parameters/TenantHeader"},{"$ref":"#/components/parameters/Limit"},{"name":"status","in":"query","required":false,"schema":{"enum":["open","in_review","resolved","rejected"]}},{"$ref":"#/components/parameters/TraceId"}],"responses":{"200":{"description":"Appeals","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppealList"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/appeals/{appealId}":{"get":{"operationId":"getAppeal","tags":["appeals"],"summary":"An appeal with its message thread","x-milestone":5,"x-permission":"appeal:submit","parameters":[{"$ref":"#/components/parameters/AppealIdPath"},{"$ref":"#/components/parameters/TenantHeader"},{"$ref":"#/components/parameters/TraceId"}],"responses":{"200":{"description":"Appeal","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Appeal"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/appeals/{appealId}/messages":{"post":{"operationId":"addAppealMessage","tags":["appeals"],"summary":"Add information to an open appeal","x-milestone":5,"x-permission":"appeal:submit","parameters":[{"$ref":"#/components/parameters/AppealIdPath"},{"$ref":"#/components/parameters/TenantHeader"},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/TraceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppealMessageCreate"}}}},"responses":{"201":{"description":"Added","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Appeal"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"}}}},"/v1/appeal-queue":{"get":{"operationId":"listAppealQueue","tags":["appeals"],"summary":"Support queue of appeals ordered by SLA due time","x-milestone":5,"x-permission":"appeal:handle","parameters":[{"$ref":"#/components/parameters/Limit"},{"name":"status","in":"query","required":false,"schema":{"enum":["open","in_review","resolved","rejected"]}},{"$ref":"#/components/parameters/TraceId"}],"responses":{"200":{"description":"Appeals","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppealList"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/appeal-queue/{appealId}":{"get":{"operationId":"getAppealForHandling","tags":["appeals"],"summary":"An appeal with its thread for the handler","x-milestone":5,"x-permission":"appeal:handle","parameters":[{"$ref":"#/components/parameters/AppealIdPath"},{"$ref":"#/components/parameters/TraceId"}],"responses":{"200":{"description":"Appeal","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Appeal"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/appeal-queue/{appealId}/decision":{"post":{"operationId":"handleAppeal","tags":["appeals"],"summary":"Reply to an appeal and move it to in review, resolved or rejected","x-milestone":5,"x-permission":"appeal:handle","parameters":[{"$ref":"#/components/parameters/AppealIdPath"},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/TraceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppealDecision"}}}},"responses":{"200":{"description":"Handled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Appeal"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"}}}},"/v1/alerts/scan":{"post":{"operationId":"runAlertScan","tags":["alerts"],"summary":"Evaluate operational conditions and raise, refresh or auto-resolve alerts","x-milestone":5,"x-permission":"policy:manage","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/TraceId"}],"responses":{"200":{"description":"Scan result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AlertScanResult"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"}}}},"/v1/alerts":{"get":{"operationId":"listAlerts","tags":["alerts"],"summary":"Operational alerts","x-milestone":5,"x-permission":"alert:read","parameters":[{"$ref":"#/components/parameters/Limit"},{"name":"status","in":"query","required":false,"schema":{"enum":["open","acknowledged","resolved"]}},{"name":"severity","in":"query","required":false,"schema":{"enum":["info","warning","critical"]}},{"$ref":"#/components/parameters/TraceId"}],"responses":{"200":{"description":"Alerts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AlertList"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/alerts/{alertId}/acknowledge":{"post":{"operationId":"acknowledgeAlert","tags":["alerts"],"summary":"Acknowledge an open alert","x-milestone":5,"x-permission":"alert:manage","parameters":[{"$ref":"#/components/parameters/AlertIdPath"},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/TraceId"}],"responses":{"200":{"description":"Acknowledged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Alert"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"}}}},"/v1/alerts/{alertId}/resolve":{"post":{"operationId":"resolveAlert","tags":["alerts"],"summary":"Resolve an alert with a recorded resolution","x-milestone":5,"x-permission":"alert:manage","parameters":[{"$ref":"#/components/parameters/AlertIdPath"},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/TraceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AlertResolve"}}}},"responses":{"200":{"description":"Resolved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Alert"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"}}}},"/v1/audit-events/export":{"get":{"operationId":"exportAuditEvents","tags":["audit"],"summary":"Export a contiguous range of the audit chain with a verification manifest","x-milestone":5,"x-permission":"audit:export","parameters":[{"name":"from_seq","in":"query","required":false,"schema":{"type":"integer","minimum":1}},{"name":"to_seq","in":"query","required":false,"schema":{"type":"integer","minimum":1}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":5000,"default":1000}},{"$ref":"#/components/parameters/TraceId"}],"responses":{"200":{"description":"Audit export","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditExport"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/Unprocessable"}}}},"/v1/reports/operations":{"get":{"operationId":"getOperationsOverview","tags":["reports"],"summary":"Operations overview for the CP console: queues, alerts, campaigns, screens, withdrawals, reconciliation and contributor share","x-milestone":5,"x-permission":"report:read","parameters":[{"$ref":"#/components/parameters/TenantHeader"},{"$ref":"#/components/parameters/TraceId"}],"responses":{"200":{"description":"Overview","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OperationsOverview"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}}},"components":{"pathItems":{"revise":{"post":{"operationId":"reviseCampaign","tags":["campaigns"],"summary":"Return an approved or rejected campaign to DRAFT for editing (requires re-review)","x-milestone":2,"x-permission":"campaign:manage","parameters":[{"$ref":"#/components/parameters/CampaignIdPath"},{"$ref":"#/components/parameters/TenantHeader"},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/TraceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransitionRequest"}}}},"responses":{"200":{"description":"Transitioned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Campaign"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"}}}},"submit":{"post":{"operationId":"submitCampaign","tags":["campaigns"],"summary":"Submit a DRAFT campaign for review (all creatives must be approved, contract active)","x-milestone":2,"x-permission":"campaign:manage","parameters":[{"$ref":"#/components/parameters/CampaignIdPath"},{"$ref":"#/components/parameters/TenantHeader"},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/TraceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransitionRequest"}}}},"responses":{"200":{"description":"Transitioned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Campaign"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"}}}},"fund":{"post":{"operationId":"fundCampaign","tags":["campaigns"],"summary":"Reserve the full budget from prepaid balance (and contract credit) in the ledger","x-milestone":2,"x-permission":"funding:topup","parameters":[{"$ref":"#/components/parameters/CampaignIdPath"},{"$ref":"#/components/parameters/TenantHeader"},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/TraceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransitionRequest"}}}},"responses":{"200":{"description":"Transitioned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Campaign"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"}}}},"publish":{"post":{"operationId":"publishCampaign","tags":["campaigns"],"summary":"Publish a funded campaign to the schedule","x-milestone":2,"x-permission":"campaign:publish","parameters":[{"$ref":"#/components/parameters/CampaignIdPath"},{"$ref":"#/components/parameters/TenantHeader"},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/TraceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransitionRequest"}}}},"responses":{"200":{"description":"Transitioned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Campaign"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"}}}},"pause":{"post":{"operationId":"pauseCampaign","tags":["campaigns"],"summary":"Pause a scheduled or serving campaign","x-milestone":2,"x-permission":"campaign:manage","parameters":[{"$ref":"#/components/parameters/CampaignIdPath"},{"$ref":"#/components/parameters/TenantHeader"},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/TraceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransitionRequest"}}}},"responses":{"200":{"description":"Transitioned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Campaign"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"}}}},"resume":{"post":{"operationId":"resumeCampaign","tags":["campaigns"],"summary":"Resume a paused campaign (SERVING, SCHEDULED or EXPIRED depending on its window)","x-milestone":2,"x-permission":"campaign:manage","parameters":[{"$ref":"#/components/parameters/CampaignIdPath"},{"$ref":"#/components/parameters/TenantHeader"},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/TraceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransitionRequest"}}}},"responses":{"200":{"description":"Transitioned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Campaign"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"}}}},"cancel":{"post":{"operationId":"cancelCampaign","tags":["campaigns"],"summary":"Cancel before serving; a funded campaign releases its reservation (REFUNDED)","x-milestone":2,"x-permission":"campaign:manage","parameters":[{"$ref":"#/components/parameters/CampaignIdPath"},{"$ref":"#/components/parameters/TenantHeader"},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/TraceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransitionRequest"}}}},"responses":{"200":{"description":"Transitioned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Campaign"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"}}}},"emergency-stop":{"post":{"operationId":"emergencyStopCampaign","tags":["campaigns"],"summary":"Emergency takedown by platform risk/admin (effective at next player policy sync; played batches retained)","x-milestone":2,"x-permission":"campaign:emergency_stop","parameters":[{"$ref":"#/components/parameters/CampaignIdPath"},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/TraceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransitionRequest"}}}},"responses":{"200":{"description":"Transitioned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Campaign"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"}}}},"issue":{"post":{"operationId":"issueInvoice","tags":["funding"],"summary":"Record the issued invoice number (finance)","x-milestone":2,"x-permission":"invoice:issue","parameters":[{"$ref":"#/components/parameters/InvoiceIdPath"},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/TraceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceIssue"}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invoice"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"}}}},"reject":{"post":{"operationId":"rejectInvoice","tags":["funding"],"summary":"Reject an invoice request (finance)","x-milestone":2,"x-permission":"invoice:issue","parameters":[{"$ref":"#/components/parameters/InvoiceIdPath"},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/TraceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReasonBody"}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invoice"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"}}}},"void":{"post":{"operationId":"voidInvoice","tags":["funding"],"summary":"Void an issued invoice (finance)","x-milestone":2,"x-permission":"invoice:issue","parameters":[{"$ref":"#/components/parameters/InvoiceIdPath"},{"$ref":"#/components/parameters/IdempotencyKey"},{"$ref":"#/components/parameters/TraceId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReasonBody"}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Invoice"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"422":{"$ref":"#/components/responses/Unprocessable"}}}}},"securitySchemes":{"cogiensOidc":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Short-lived (<= 15 min) OIDC access token issued by the Cogiens identity provider for audience\n`openad-api`. OpenAD maps (iss, sub) to its own role assignments; token-embedded roles are ignored.\n"},"deviceSignature":{"type":"apiKey","in":"header","name":"x-openad-signature","description":"Ed25519 signature by the device key (x-openad-device-key fingerprint) over\n\"OPENAD-DEVICE-V1\\n<METHOD>\\n<path?query>\\n<x-openad-timestamp>\\n<x-openad-nonce>\\n<sha256 hex of raw body>\".\nTimestamps must be within ±300 s of server time; nonces are single use (replays are rejected).\n"}},"parameters":{"TraceId":{"name":"x-trace-id","in":"header","required":false,"description":"End-to-end trace id; generated by OpenAD when absent and echoed in every response.","schema":{"type":"string","pattern":"^[A-Za-z0-9._-]{8,128}$"}},"IdempotencyKey":{"name":"idempotency-key","in":"header","required":true,"description":"Required for every state-changing request; replays return the original response.","schema":{"type":"string","minLength":8,"maxLength":200,"pattern":"^[A-Za-z0-9._:-]+$"}},"TenantHeader":{"name":"x-openad-tenant","in":"header","required":false,"description":"Tenant the caller acts in (required for tenant roles).","schema":{"type":"string","format":"uuid"}},"TenantIdPath":{"name":"tenantId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"Limit":{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},"VenueIdPath":{"name":"venueId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"ScreenIdPath":{"name":"screenId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"DeviceKey":{"name":"x-openad-device-key","in":"header","required":true,"schema":{"type":"string","pattern":"^ed25519:[0-9a-f]{32}$"}},"DeviceTimestamp":{"name":"x-openad-timestamp","in":"header","required":true,"schema":{"type":"string","pattern":"^[0-9]{13}$"}},"DeviceNonce":{"name":"x-openad-nonce","in":"header","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,64}$"}},"DeviceSignature":{"name":"x-openad-signature","in":"header","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{86}$"}},"CreativeIdPath":{"name":"creativeId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"VersionPath":{"name":"version","in":"path","required":true,"schema":{"type":"integer","minimum":1}},"CampaignIdPath":{"name":"campaignId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"InvoiceIdPath":{"name":"invoiceId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"EvidenceIdPath":{"name":"evidenceId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"SettlementIdPath":{"name":"settlementId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"WithdrawalIdPath":{"name":"withdrawalId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"AwgContractIdPath":{"name":"contractId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"AppealIdPath":{"name":"appealId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"AlertIdPath":{"name":"alertId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}},"responses":{"BadRequest":{"description":"Request failed validation","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"Unauthorized":{"description":"Missing or invalid credentials","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"Forbidden":{"description":"Authenticated but not permitted","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"NotFound":{"description":"Resource not found or not visible","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"Conflict":{"description":"Conflict (idempotency key reuse, state conflict, uniqueness)","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"ServiceUnavailable":{"description":"A required dependency (e.g. malware scanner) is unavailable","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"Unprocessable":{"description":"Business rule violation","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}},"schemas":{"Problem":{"type":"object","additionalProperties":false,"required":["type","title","status","code","trace_id"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"code":{"type":"string","pattern":"^[A-Z][A-Z0-9_]*$"},"detail":{"type":"string"},"trace_id":{"type":"string"},"errors":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["path","message"],"properties":{"path":{"type":"string"},"message":{"type":"string"}}}}}},"Health":{"type":"object","additionalProperties":false,"required":["status","service","version"],"properties":{"status":{"const":"ok"},"service":{"type":"string"},"version":{"type":"string"},"git_sha":{"type":"string"}}},"Readiness":{"type":"object","additionalProperties":false,"required":["status","checks"],"properties":{"status":{"enum":["ready","not_ready"]},"checks":{"type":"object","additionalProperties":false,"required":["database","migrations"],"properties":{"database":{"enum":["ok","error"]},"migrations":{"enum":["current","pending","drift","error"]}}}}},"Uuid":{"type":"string","format":"uuid"},"Timestamp":{"type":"string","format":"date-time"},"TenantKind":{"enum":["advertiser","contributor","venue_operator","platform"]},"TenantStatus":{"enum":["active","suspended","closed"]},"Tenant":{"type":"object","additionalProperties":false,"required":["id","kind","display_name","status","cogiens_org_ref","pilot_whitelisted","created_at","updated_at","row_version"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"kind":{"$ref":"#/components/schemas/TenantKind"},"display_name":{"type":"string","minLength":1,"maxLength":200},"status":{"$ref":"#/components/schemas/TenantStatus"},"cogiens_org_ref":{"type":["string","null"]},"pilot_whitelisted":{"type":"boolean"},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"},"row_version":{"type":"integer","minimum":1},"verification_status":{"enum":["unverified","pending","verified","rejected"]}}},"TenantCreate":{"type":"object","additionalProperties":false,"required":["kind","display_name"],"properties":{"kind":{"$ref":"#/components/schemas/TenantKind"},"display_name":{"type":"string","minLength":1,"maxLength":200},"cogiens_org_ref":{"type":"string","minLength":1,"maxLength":128},"pilot_whitelisted":{"type":"boolean"}}},"TenantStatusChange":{"type":"object","additionalProperties":false,"required":["status","reason"],"properties":{"status":{"$ref":"#/components/schemas/TenantStatus"},"reason":{"type":"string","minLength":3,"maxLength":1000},"expected_row_version":{"type":"integer","minimum":1}}},"TenantList":{"type":"object","additionalProperties":false,"required":["items","next_after"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Tenant"}},"next_after":{"type":["string","null"]}}},"Membership":{"type":"object","additionalProperties":false,"required":["tenant_id","tenant_kind","display_name","tenant_status","roles"],"properties":{"tenant_id":{"$ref":"#/components/schemas/Uuid"},"tenant_kind":{"$ref":"#/components/schemas/TenantKind"},"display_name":{"type":"string"},"tenant_status":{"$ref":"#/components/schemas/TenantStatus"},"roles":{"type":"array","items":{"type":"string"}}}},"Me":{"type":"object","additionalProperties":false,"required":["issuer","subject","active_tenant_id","roles","permissions","memberships"],"properties":{"issuer":{"type":"string"},"subject":{"type":"string"},"active_tenant_id":{"type":["string","null"],"format":"uuid"},"roles":{"type":"array","items":{"type":"string"}},"permissions":{"type":"array","items":{"type":"string"}},"memberships":{"type":"array","items":{"$ref":"#/components/schemas/Membership"}}}},"RoleAssignmentCreate":{"type":"object","additionalProperties":false,"required":["issuer","subject","role"],"properties":{"issuer":{"type":"string","minLength":1,"maxLength":300},"subject":{"type":"string","minLength":1,"maxLength":300},"tenant_id":{"type":["string","null"],"format":"uuid"},"role":{"type":"string","pattern":"^[a-z_]+$"}}},"RoleAssignment":{"type":"object","additionalProperties":false,"required":["id","issuer","subject","tenant_id","role","granted_by","granted_at"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"issuer":{"type":"string"},"subject":{"type":"string"},"tenant_id":{"type":["string","null"],"format":"uuid"},"role":{"type":"string"},"granted_by":{"type":"string"},"granted_at":{"$ref":"#/components/schemas/Timestamp"}}},"AuditEvent":{"type":"object","additionalProperties":false,"required":["chain_seq","event_uuid","tenant_id","actor_type","actor_id","action","resource_type","resource_id","reason","trace_id","data","occurred_at","prev_hash","hash"],"properties":{"chain_seq":{"type":"integer","minimum":1},"event_uuid":{"$ref":"#/components/schemas/Uuid"},"tenant_id":{"type":["string","null"],"format":"uuid"},"actor_type":{"enum":["user","device","system","service"]},"actor_id":{"type":"string"},"action":{"type":"string"},"resource_type":{"type":"string"},"resource_id":{"type":["string","null"]},"reason":{"type":["string","null"]},"trace_id":{"type":"string"},"data":{"type":"object"},"occurred_at":{"$ref":"#/components/schemas/Timestamp"},"prev_hash":{"type":"string","pattern":"^[0-9a-f]{64}$"},"hash":{"type":"string","pattern":"^[0-9a-f]{64}$"}}},"AuditEventList":{"type":"object","additionalProperties":false,"required":["items","next_before_seq"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/AuditEvent"}},"next_before_seq":{"type":["integer","null"]}}},"AuditChainVerification":{"type":"object","additionalProperties":false,"required":["ok","checked","broken_at_seq"],"properties":{"ok":{"type":"boolean"},"checked":{"type":"integer","minimum":0},"broken_at_seq":{"type":["integer","null"]}}},"Sha256":{"type":"string","pattern":"^[0-9a-f]{64}$"},"DocumentVersion":{"type":"string","pattern":"^[A-Za-z0-9._-]{1,64}$"},"ReasonBody":{"type":"object","additionalProperties":false,"required":["reason"],"properties":{"reason":{"type":"string","minLength":3,"maxLength":1000}}},"OnboardingRequest":{"type":"object","additionalProperties":false,"required":["kind","display_name"],"properties":{"kind":{"enum":["advertiser","contributor","venue_operator"]},"display_name":{"type":"string","minLength":1,"maxLength":200}}},"PlatformSigningKey":{"type":"object","additionalProperties":false,"required":["kid","alg","public_key","status"],"properties":{"kid":{"type":"string","pattern":"^[A-Za-z0-9._-]{1,64}$"},"alg":{"const":"Ed25519"},"public_key":{"type":"string","pattern":"^[A-Za-z0-9_-]{43}$"},"status":{"enum":["active","retiring"]}}},"PlatformSigningKeys":{"type":"object","additionalProperties":false,"required":["keys"],"properties":{"keys":{"type":"array","items":{"$ref":"#/components/schemas/PlatformSigningKey"}}}},"VenueType":{"enum":["private_home","retail","restaurant","office","transport","public_facility","awg_site","other"]},"Venue":{"type":"object","additionalProperties":false,"required":["id","tenant_id","display_name","venue_type","public_space","country_code","region","city","timezone","notice_status","notice_document_version","notice_evidence_sha256","notice_updated_at","status","created_at","updated_at","row_version"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"tenant_id":{"$ref":"#/components/schemas/Uuid"},"display_name":{"type":"string"},"venue_type":{"$ref":"#/components/schemas/VenueType"},"public_space":{"type":"boolean"},"country_code":{"type":"string","pattern":"^[A-Z]{2}$"},"region":{"type":["string","null"]},"city":{"type":["string","null"]},"timezone":{"type":"string"},"notice_status":{"enum":["none","posted","verified","removed"]},"notice_document_version":{"type":["string","null"]},"notice_evidence_sha256":{"type":["string","null"]},"notice_updated_at":{"type":["string","null"],"format":"date-time"},"status":{"enum":["active","suspended","closed"]},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"},"row_version":{"type":"integer","minimum":1}}},"VenueCreate":{"type":"object","additionalProperties":false,"required":["display_name","venue_type","public_space","country_code","timezone"],"properties":{"display_name":{"type":"string","minLength":1,"maxLength":200},"venue_type":{"$ref":"#/components/schemas/VenueType"},"public_space":{"type":"boolean"},"country_code":{"type":"string","pattern":"^[A-Z]{2}$"},"region":{"type":"string","minLength":1,"maxLength":100},"city":{"type":"string","minLength":1,"maxLength":100},"timezone":{"type":"string","minLength":1,"maxLength":64}}},"VenueList":{"type":"object","additionalProperties":false,"required":["items","next_after"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Venue"}},"next_after":{"type":["string","null"]}}},"VenueNoticeUpdate":{"type":"object","additionalProperties":false,"required":["notice_status"],"properties":{"notice_status":{"enum":["posted","removed"]},"document_version":{"$ref":"#/components/schemas/DocumentVersion"},"evidence_sha256":{"$ref":"#/components/schemas/Sha256"}}},"ScreenClass":{"enum":["phone","pc","tv","public_display","awg_device"]},"ScreenStatus":{"enum":["pending_activation","active","suspended","retired"]},"Screen":{"type":"object","additionalProperties":false,"required":["id","tenant_id","venue_id","display_name","screen_class","width_px","height_px","max_concurrent_viewers","camera_declared","camera_probed","status","last_heartbeat_at","capabilities_reported_at","created_at","updated_at","row_version"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"tenant_id":{"$ref":"#/components/schemas/Uuid"},"venue_id":{"$ref":"#/components/schemas/Uuid"},"display_name":{"type":"string"},"screen_class":{"$ref":"#/components/schemas/ScreenClass"},"width_px":{"type":"integer"},"height_px":{"type":"integer"},"max_concurrent_viewers":{"type":"integer"},"camera_declared":{"type":"boolean"},"camera_probed":{"enum":["unknown","unavailable","denied","prompt","granted"]},"status":{"$ref":"#/components/schemas/ScreenStatus"},"last_heartbeat_at":{"type":["string","null"],"format":"date-time"},"capabilities_reported_at":{"type":["string","null"],"format":"date-time"},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"},"row_version":{"type":"integer","minimum":1}}},"ScreenCreate":{"type":"object","additionalProperties":false,"required":["venue_id","display_name","screen_class","width_px","height_px","max_concurrent_viewers","camera_declared"],"properties":{"venue_id":{"$ref":"#/components/schemas/Uuid"},"display_name":{"type":"string","minLength":1,"maxLength":200},"screen_class":{"$ref":"#/components/schemas/ScreenClass"},"width_px":{"type":"integer","minimum":1,"maximum":16384},"height_px":{"type":"integer","minimum":1,"maximum":16384},"max_concurrent_viewers":{"type":"integer","minimum":1,"maximum":200},"camera_declared":{"type":"boolean"}}},"ScreenList":{"type":"object","additionalProperties":false,"required":["items","next_after"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Screen"}},"next_after":{"type":["string","null"]}}},"ScreenStatusChange":{"type":"object","additionalProperties":false,"required":["status","reason"],"properties":{"status":{"enum":["active","suspended","retired"]},"reason":{"type":"string","minLength":3,"maxLength":1000},"expected_row_version":{"type":"integer","minimum":1}}},"AdCategory":{"enum":["food_beverage","retail","automotive","finance","education","health","travel","entertainment","public_service","technology","home","beauty","sports","real_estate","other"]},"TimeWindow":{"type":"object","additionalProperties":false,"required":["days","start","end"],"properties":{"days":{"type":"array","minItems":1,"maxItems":7,"uniqueItems":true,"items":{"type":"integer","minimum":1,"maximum":7}},"start":{"type":"string","pattern":"^([01][0-9]|2[0-3]):[0-5][0-9]$"},"end":{"type":"string","pattern":"^([01][0-9]|2[0-4]):[0-5][0-9]$"}}},"PlaybackPreferences":{"type":"object","additionalProperties":false,"required":["allowed_categories","daily_max_seconds","time_windows","volume_max_pct","muted","display_mode","require_external_power","require_unmetered_network"],"properties":{"allowed_categories":{"type":"array","minItems":1,"uniqueItems":true,"items":{"$ref":"#/components/schemas/AdCategory"}},"daily_max_seconds":{"type":"integer","minimum":0,"maximum":86400},"time_windows":{"type":"array","maxItems":14,"items":{"$ref":"#/components/schemas/TimeWindow"}},"volume_max_pct":{"type":"integer","minimum":0,"maximum":100},"muted":{"type":"boolean"},"display_mode":{"enum":["fullscreen","region"]},"require_external_power":{"type":"boolean"},"require_unmetered_network":{"type":"boolean"}}},"PlaybackPolicyVersion":{"type":"object","additionalProperties":false,"required":["screen_id","version","policy","policy_sha256","created_by","created_at"],"properties":{"screen_id":{"$ref":"#/components/schemas/Uuid"},"version":{"type":"integer","minimum":1},"policy":{"$ref":"#/components/schemas/PlaybackPreferences"},"policy_sha256":{"$ref":"#/components/schemas/Sha256"},"created_by":{"type":"string"},"created_at":{"$ref":"#/components/schemas/Timestamp"}}},"ActivationCode":{"type":"object","additionalProperties":false,"required":["screen_id","code","expires_at"],"properties":{"screen_id":{"$ref":"#/components/schemas/Uuid"},"code":{"type":"string","pattern":"^[0-9A-HJKMNP-TV-Z]{10}$"},"expires_at":{"$ref":"#/components/schemas/Timestamp"}}},"DeviceKey":{"type":"object","additionalProperties":false,"required":["id","screen_id","fingerprint","public_key","status","activated_at","rotated_at","revoked_at","revoke_reason","supersedes_key_id"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"screen_id":{"$ref":"#/components/schemas/Uuid"},"fingerprint":{"type":"string","pattern":"^ed25519:[0-9a-f]{32}$"},"public_key":{"type":"string","pattern":"^[A-Za-z0-9_-]{43}$"},"status":{"enum":["active","rotated","revoked"]},"activated_at":{"$ref":"#/components/schemas/Timestamp"},"rotated_at":{"type":["string","null"],"format":"date-time"},"revoked_at":{"type":["string","null"],"format":"date-time"},"revoke_reason":{"type":["string","null"]},"supersedes_key_id":{"type":["string","null"],"format":"uuid"}}},"DeviceKeyList":{"type":"object","additionalProperties":false,"required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/DeviceKey"}}}},"Heartbeat":{"type":"object","additionalProperties":false,"required":["boot_id","seq","device_time","received_at","drift_ms","delivered_late","playback_state","player_version","queue_depth","cache_bytes","network","foreground"],"properties":{"boot_id":{"$ref":"#/components/schemas/Uuid"},"seq":{"type":"integer","minimum":0},"device_time":{"$ref":"#/components/schemas/Timestamp"},"received_at":{"$ref":"#/components/schemas/Timestamp"},"drift_ms":{"type":"integer"},"delivered_late":{"type":"boolean"},"playback_state":{"enum":["idle","playing","paused","buffering","stopped","error"]},"player_version":{"type":"string"},"queue_depth":{"type":"integer","minimum":0},"cache_bytes":{"type":"integer","minimum":0},"network":{"enum":["online","degraded","recovered"]},"foreground":{"type":"boolean"}}},"HeartbeatList":{"type":"object","additionalProperties":false,"required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Heartbeat"}}}},"ConsentPurpose":{"enum":["playback_participation","camera_attention","demographic_statistics","venue_public_notice"]},"ConsentCreate":{"type":"object","additionalProperties":false,"required":["purpose","target_type","target_id","decision","document_version","document_sha256"],"properties":{"purpose":{"$ref":"#/components/schemas/ConsentPurpose"},"target_type":{"enum":["screen","venue"]},"target_id":{"$ref":"#/components/schemas/Uuid"},"decision":{"enum":["granted","withdrawn"]},"document_version":{"$ref":"#/components/schemas/DocumentVersion"},"document_sha256":{"$ref":"#/components/schemas/Sha256"},"reason":{"type":"string","minLength":1,"maxLength":1000}}},"ConsentRecord":{"type":"object","additionalProperties":false,"required":["id","tenant_id","purpose","target_type","target_id","decision","document_version","document_sha256","actor_id","reason","recorded_at"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"tenant_id":{"$ref":"#/components/schemas/Uuid"},"purpose":{"$ref":"#/components/schemas/ConsentPurpose"},"target_type":{"enum":["screen","venue"]},"target_id":{"$ref":"#/components/schemas/Uuid"},"decision":{"enum":["granted","withdrawn"]},"document_version":{"type":"string"},"document_sha256":{"$ref":"#/components/schemas/Sha256"},"actor_id":{"type":"string"},"reason":{"type":["string","null"]},"recorded_at":{"$ref":"#/components/schemas/Timestamp"}}},"ConsentState":{"type":"object","additionalProperties":false,"required":["target_type","target_id","current","history"],"properties":{"target_type":{"enum":["screen","venue"]},"target_id":{"$ref":"#/components/schemas/Uuid"},"current":{"type":"array","items":{"$ref":"#/components/schemas/ConsentRecord"}},"history":{"type":"array","items":{"$ref":"#/components/schemas/ConsentRecord"}}}},"DeviceCapabilities":{"type":"object","additionalProperties":false,"required":["player_type","player_version","os","os_version","screen","camera","edge_models","webgl","webgpu","storage_quota_bytes","hardware_concurrency","touch"],"properties":{"player_type":{"enum":["web","desktop","tv","android","ios"]},"player_version":{"type":"string","minLength":1,"maxLength":40},"os":{"type":"string","minLength":1,"maxLength":40},"os_version":{"type":"string","minLength":1,"maxLength":40},"screen":{"type":"object","additionalProperties":false,"required":["width_px","height_px","pixel_ratio"],"properties":{"width_px":{"type":"integer","minimum":1,"maximum":16384},"height_px":{"type":"integer","minimum":1,"maximum":16384},"pixel_ratio":{"type":"number","minimum":0.25,"maximum":8}}},"camera":{"type":"object","additionalProperties":false,"required":["available","permission"],"properties":{"available":{"type":"boolean"},"permission":{"enum":["granted","denied","prompt","unavailable"]}}},"edge_models":{"type":"array","maxItems":10,"items":{"type":"object","additionalProperties":false,"required":["name","version"],"properties":{"name":{"type":"string","pattern":"^[a-z0-9._-]{1,64}$"},"version":{"type":"string","pattern":"^[A-Za-z0-9._+-]{1,40}$"}}}},"webgl":{"type":"boolean"},"webgpu":{"type":"boolean"},"storage_quota_bytes":{"type":"integer","minimum":0},"hardware_concurrency":{"type":"integer","minimum":1,"maximum":512},"touch":{"type":"boolean"}}},"DeviceActivation":{"type":"object","additionalProperties":false,"required":["activation_code","public_key","device_time_ms","nonce","proof","capabilities"],"properties":{"activation_code":{"type":"string","pattern":"^[0-9A-HJKMNP-TV-Z]{10}$"},"public_key":{"type":"string","pattern":"^[A-Za-z0-9_-]{43}$"},"device_time_ms":{"type":"integer","minimum":0},"nonce":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,64}$"},"proof":{"type":"string","pattern":"^[A-Za-z0-9_-]{86}$"},"capabilities":{"$ref":"#/components/schemas/DeviceCapabilities"}}},"DeviceActivationResult":{"type":"object","additionalProperties":false,"required":["screen_id","tenant_id","key_id","fingerprint","platform_signing_keys","heartbeat_interval_seconds"],"properties":{"screen_id":{"$ref":"#/components/schemas/Uuid"},"tenant_id":{"$ref":"#/components/schemas/Uuid"},"key_id":{"$ref":"#/components/schemas/Uuid"},"fingerprint":{"type":"string"},"platform_signing_keys":{"type":"array","items":{"$ref":"#/components/schemas/PlatformSigningKey"}},"heartbeat_interval_seconds":{"type":"integer","minimum":5}}},"HeartbeatItem":{"type":"object","additionalProperties":false,"required":["boot_id","seq","device_time_ms","playback_state","player_version","queue_depth","cache_bytes","network","foreground"],"properties":{"boot_id":{"$ref":"#/components/schemas/Uuid"},"seq":{"type":"integer","minimum":0,"maximum":9007199254740991},"device_time_ms":{"type":"integer","minimum":0},"playback_state":{"enum":["idle","playing","paused","buffering","stopped","error"]},"player_version":{"type":"string","minLength":1,"maxLength":40},"queue_depth":{"type":"integer","minimum":0},"cache_bytes":{"type":"integer","minimum":0},"network":{"enum":["online","degraded","recovered"]},"foreground":{"type":"boolean"}}},"HeartbeatBatch":{"type":"object","additionalProperties":false,"required":["items"],"properties":{"items":{"type":"array","minItems":1,"maxItems":500,"items":{"$ref":"#/components/schemas/HeartbeatItem"}}}},"HeartbeatBatchResult":{"type":"object","additionalProperties":false,"required":["accepted","duplicates","rejected","server_time_ms","policy_version"],"properties":{"accepted":{"type":"integer","minimum":0},"duplicates":{"type":"integer","minimum":0},"rejected":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["index","reason"],"properties":{"index":{"type":"integer","minimum":0},"reason":{"enum":["stale","future"]}}}},"server_time_ms":{"type":"integer"},"policy_version":{"$ref":"#/components/schemas/Sha256"}}},"CapabilityReportResult":{"type":"object","additionalProperties":false,"required":["recorded","capabilities_sha256","camera_probed"],"properties":{"recorded":{"type":"boolean"},"capabilities_sha256":{"$ref":"#/components/schemas/Sha256"},"camera_probed":{"enum":["unavailable","denied","prompt","granted"]}}},"DevicePolicy":{"type":"object","additionalProperties":false,"required":["screen_id","tenant_id","issued_at","expires_at","policy_version","screen_status","ads_allowed","camera_attention_allowed","demographics_allowed","camera_mode","playback","heartbeat_interval_seconds","reasons","emergency_stops"],"properties":{"screen_id":{"$ref":"#/components/schemas/Uuid"},"tenant_id":{"$ref":"#/components/schemas/Uuid"},"issued_at":{"$ref":"#/components/schemas/Timestamp"},"expires_at":{"$ref":"#/components/schemas/Timestamp"},"policy_version":{"$ref":"#/components/schemas/Sha256"},"screen_status":{"$ref":"#/components/schemas/ScreenStatus"},"ads_allowed":{"type":"boolean"},"camera_attention_allowed":{"type":"boolean"},"demographics_allowed":{"type":"boolean"},"camera_mode":{"enum":["disabled","test_only","pilot_authorized"]},"playback":{"oneOf":[{"$ref":"#/components/schemas/PlaybackPreferences"},{"type":"null"}]},"heartbeat_interval_seconds":{"type":"integer","minimum":5},"reasons":{"type":"array","items":{"type":"string","pattern":"^[a-z_]+$"}},"emergency_stops":{"type":"array","items":{"$ref":"#/components/schemas/EmergencyStopRef"}}}},"SignedDevicePolicy":{"type":"object","additionalProperties":false,"required":["policy","kid","signature"],"properties":{"policy":{"$ref":"#/components/schemas/DevicePolicy"},"kid":{"type":"string"},"signature":{"type":"string","pattern":"^[A-Za-z0-9_-]{86}$"}}},"KeyRotation":{"type":"object","additionalProperties":false,"required":["new_public_key","device_time_ms","nonce","proof"],"properties":{"new_public_key":{"type":"string","pattern":"^[A-Za-z0-9_-]{43}$"},"device_time_ms":{"type":"integer","minimum":0},"nonce":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,64}$"},"proof":{"type":"string","pattern":"^[A-Za-z0-9_-]{86}$"}}},"KeyRotationResult":{"type":"object","additionalProperties":false,"required":["key_id","fingerprint","previous_fingerprint"],"properties":{"key_id":{"$ref":"#/components/schemas/Uuid"},"fingerprint":{"type":"string","pattern":"^ed25519:[0-9a-f]{32}$"},"previous_fingerprint":{"type":"string","pattern":"^ed25519:[0-9a-f]{32}$"}}},"EmergencyStopRef":{"type":"object","additionalProperties":false,"required":["scope","campaign_id","creative_version_id","stopped_at"],"properties":{"scope":{"enum":["campaign","creative_version"]},"campaign_id":{"type":["string","null"],"format":"uuid"},"creative_version_id":{"type":["string","null"],"format":"uuid"},"stopped_at":{"$ref":"#/components/schemas/Timestamp"}}},"MinorAmount":{"type":"string","pattern":"^[0-9]{1,18}$"},"PositiveMinorAmount":{"type":"string","pattern":"^[1-9][0-9]{0,14}$"},"Currency":{"type":"string","pattern":"^[A-Z]{3}$"},"AdvertiserProfileInput":{"type":"object","additionalProperties":false,"required":["legal_name","industry"],"properties":{"legal_name":{"type":"string","minLength":1,"maxLength":200},"industry":{"$ref":"#/components/schemas/AdCategory"},"business_registration_no":{"type":"string","pattern":"^[A-Za-z0-9-]{6,32}$"},"contact_email":{"type":"string","format":"email","maxLength":200}}},"AdvertiserProfile":{"type":"object","additionalProperties":false,"required":["tenant_id","legal_name","industry","business_registration_no","contact_email","status","created_at","updated_at","row_version"],"properties":{"tenant_id":{"$ref":"#/components/schemas/Uuid"},"legal_name":{"type":"string"},"industry":{"$ref":"#/components/schemas/AdCategory"},"business_registration_no":{"type":["string","null"]},"contact_email":{"type":["string","null"]},"status":{"enum":["active","restricted"]},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"},"row_version":{"type":"integer","minimum":1}}},"RateCard":{"type":"object","additionalProperties":false,"required":["verified_play_cpm_minor","attention_second_cpm_minor","qualified_group_view_minor"],"properties":{"verified_play_cpm_minor":{"$ref":"#/components/schemas/MinorAmount"},"attention_second_cpm_minor":{"$ref":"#/components/schemas/MinorAmount"},"qualified_group_view_minor":{"$ref":"#/components/schemas/MinorAmount"}}},"ContractCreate":{"type":"object","additionalProperties":false,"required":["advertiser_tenant_id","contract_no","currency","rates","credit_limit_minor","valid_from","valid_to","signed_document_sha256"],"properties":{"advertiser_tenant_id":{"$ref":"#/components/schemas/Uuid"},"contract_no":{"type":"string","pattern":"^[A-Z0-9-]{4,40}$"},"currency":{"$ref":"#/components/schemas/Currency"},"rates":{"$ref":"#/components/schemas/RateCard"},"credit_limit_minor":{"$ref":"#/components/schemas/MinorAmount"},"valid_from":{"type":"string","format":"date"},"valid_to":{"type":"string","format":"date"},"signed_document_sha256":{"$ref":"#/components/schemas/Sha256"}}},"Contract":{"type":"object","additionalProperties":false,"required":["id","tenant_id","contract_no","currency","rates","credit_limit_minor","valid_from","valid_to","signed_document_sha256","status","created_by","created_at","updated_at","row_version"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"tenant_id":{"$ref":"#/components/schemas/Uuid"},"contract_no":{"type":"string"},"currency":{"$ref":"#/components/schemas/Currency"},"rates":{"$ref":"#/components/schemas/RateCard"},"credit_limit_minor":{"$ref":"#/components/schemas/MinorAmount"},"valid_from":{"type":"string","format":"date"},"valid_to":{"type":"string","format":"date"},"signed_document_sha256":{"$ref":"#/components/schemas/Sha256"},"status":{"enum":["draft","active","terminated"]},"created_by":{"type":"string"},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"},"row_version":{"type":"integer","minimum":1}}},"ContractStatusChange":{"type":"object","additionalProperties":false,"required":["status","reason"],"properties":{"status":{"enum":["active","terminated"]},"reason":{"type":"string","minLength":3,"maxLength":1000}}},"ContractList":{"type":"object","additionalProperties":false,"required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Contract"}}}},"TopupCreate":{"type":"object","additionalProperties":false,"required":["amount_minor","currency"],"properties":{"amount_minor":{"$ref":"#/components/schemas/PositiveMinorAmount"},"currency":{"$ref":"#/components/schemas/Currency"}}},"Payment":{"type":"object","additionalProperties":false,"required":["id","tenant_id","provider","direction","purpose","amount_minor","currency","status","provider_ref","journal_id","created_at","completed_at"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"tenant_id":{"$ref":"#/components/schemas/Uuid"},"provider":{"const":"sandbox"},"direction":{"enum":["inbound","outbound"]},"purpose":{"enum":["topup","refund_payout"]},"amount_minor":{"$ref":"#/components/schemas/MinorAmount"},"currency":{"$ref":"#/components/schemas/Currency"},"status":{"enum":["pending","succeeded","failed"]},"provider_ref":{"type":["string","null"]},"journal_id":{"type":["string","null"],"format":"uuid"},"created_at":{"$ref":"#/components/schemas/Timestamp"},"completed_at":{"type":["string","null"],"format":"date-time"}}},"PaymentList":{"type":"object","additionalProperties":false,"required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Payment"}}}},"SandboxPaymentEvent":{"type":"object","additionalProperties":false,"required":["event_id","payment_id","status","amount_minor","currency","provider_ref"],"properties":{"event_id":{"type":"string","pattern":"^evt_[A-Za-z0-9]{8,64}$"},"payment_id":{"$ref":"#/components/schemas/Uuid"},"status":{"enum":["succeeded","failed"]},"amount_minor":{"$ref":"#/components/schemas/PositiveMinorAmount"},"currency":{"$ref":"#/components/schemas/Currency"},"provider_ref":{"type":"string","minLength":1,"maxLength":100}}},"AdvertiserBalance":{"type":"object","additionalProperties":false,"required":["tenant_id","currency","prepaid_minor","reserved_minor","credit_limit_minor","credit_used_minor","available_minor"],"properties":{"tenant_id":{"$ref":"#/components/schemas/Uuid"},"currency":{"$ref":"#/components/schemas/Currency"},"prepaid_minor":{"$ref":"#/components/schemas/MinorAmount"},"reserved_minor":{"$ref":"#/components/schemas/MinorAmount"},"credit_limit_minor":{"$ref":"#/components/schemas/MinorAmount"},"credit_used_minor":{"$ref":"#/components/schemas/MinorAmount"},"available_minor":{"$ref":"#/components/schemas/MinorAmount"}}},"ScanFinding":{"type":"object","additionalProperties":false,"required":["code","severity","detail"],"properties":{"code":{"type":"string"},"severity":{"enum":["infected","reject"]},"detail":{"type":"string"}}},"ScanEngine":{"type":"object","additionalProperties":false,"required":["name","version","result"],"properties":{"name":{"type":"string"},"version":{"type":"string"},"result":{"type":"string"}}},"CreativeUpload":{"type":"object","additionalProperties":false,"required":["id","sha256","size_bytes","declared_mime","detected_mime","width_px","height_px","duration_ms","scan_status","scan_findings","scan_engines","created_at"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"sha256":{"$ref":"#/components/schemas/Sha256"},"size_bytes":{"type":"integer","minimum":1},"declared_mime":{"type":"string"},"detected_mime":{"type":"string"},"width_px":{"type":["integer","null"]},"height_px":{"type":["integer","null"]},"duration_ms":{"type":["integer","null"]},"scan_status":{"const":"clean"},"scan_findings":{"type":"array","items":{"$ref":"#/components/schemas/ScanFinding"}},"scan_engines":{"type":"array","items":{"$ref":"#/components/schemas/ScanEngine"}},"created_at":{"$ref":"#/components/schemas/Timestamp"}}},"CreativeCreate":{"type":"object","additionalProperties":false,"required":["name","category"],"properties":{"name":{"type":"string","minLength":1,"maxLength":200},"category":{"$ref":"#/components/schemas/AdCategory"}}},"Creative":{"type":"object","additionalProperties":false,"required":["id","tenant_id","name","category","status","created_at","updated_at","row_version"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"tenant_id":{"$ref":"#/components/schemas/Uuid"},"name":{"type":"string"},"category":{"$ref":"#/components/schemas/AdCategory"},"status":{"enum":["active","archived"]},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"},"row_version":{"type":"integer","minimum":1}}},"CreativeList":{"type":"object","additionalProperties":false,"required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Creative"}}}},"RightsInput":{"type":"object","additionalProperties":false,"required":["owner"],"properties":{"owner":{"type":"string","minLength":1,"maxLength":200},"license_ref":{"type":"string","minLength":1,"maxLength":120},"proof_sha256":{"$ref":"#/components/schemas/Sha256"}}},"Rights":{"type":"object","additionalProperties":false,"required":["owner","license_ref","proof_sha256"],"properties":{"owner":{"type":"string"},"license_ref":{"type":["string","null"]},"proof_sha256":{"type":["string","null"]}}},"CreativeVersionCreate":{"type":"object","additionalProperties":false,"required":["upload_id","rights"],"properties":{"upload_id":{"$ref":"#/components/schemas/Uuid"},"headline":{"type":"string","minLength":1,"maxLength":120},"landing_url":{"type":"string","minLength":1,"maxLength":2000},"rights":{"$ref":"#/components/schemas/RightsInput"}}},"LandingCheck":{"type":"object","additionalProperties":false,"required":["ok","mode","findings","http_status","final_url","checked_at"],"properties":{"ok":{"type":"boolean"},"mode":{"enum":["none","static_only","fetch"]},"findings":{"type":"array","items":{"type":"string"}},"http_status":{"type":["integer","null"]},"final_url":{"type":["string","null"]},"checked_at":{"type":["string","null"],"format":"date-time"}}},"MachineReview":{"type":"object","additionalProperties":false,"required":["decision","findings","ruleset_version"],"properties":{"decision":{"enum":["pass","needs_human","reject"]},"findings":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["code","severity","detail"],"properties":{"code":{"type":"string"},"severity":{"enum":["reject","needs_human","info"]},"detail":{"type":"string"}}}},"ruleset_version":{"type":"string"}}},"CreativeVersionStatus":{"enum":["draft","submitted","reviewing","approved","rejected","withdrawn","taken_down"]},"CreativeVersion":{"type":"object","additionalProperties":false,"required":["id","tenant_id","creative_id","version","upload_id","asset_sha256","mime","width_px","height_px","duration_ms","headline","landing_url","rights","landing_check","machine_review","status","submitted_at","decided_at","decided_by","decision_reason","taken_down_at","takedown_reason","created_by","created_at","row_version"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"tenant_id":{"$ref":"#/components/schemas/Uuid"},"creative_id":{"$ref":"#/components/schemas/Uuid"},"version":{"type":"integer","minimum":1},"upload_id":{"$ref":"#/components/schemas/Uuid"},"asset_sha256":{"$ref":"#/components/schemas/Sha256"},"mime":{"type":"string"},"width_px":{"type":["integer","null"]},"height_px":{"type":["integer","null"]},"duration_ms":{"type":["integer","null"]},"headline":{"type":["string","null"]},"landing_url":{"type":["string","null"]},"rights":{"$ref":"#/components/schemas/Rights"},"landing_check":{"$ref":"#/components/schemas/LandingCheck"},"machine_review":{"$ref":"#/components/schemas/MachineReview"},"status":{"$ref":"#/components/schemas/CreativeVersionStatus"},"submitted_at":{"type":["string","null"],"format":"date-time"},"decided_at":{"type":["string","null"],"format":"date-time"},"decided_by":{"type":["string","null"]},"decision_reason":{"type":["string","null"]},"taken_down_at":{"type":["string","null"],"format":"date-time"},"takedown_reason":{"type":["string","null"]},"created_by":{"type":"string"},"created_at":{"$ref":"#/components/schemas/Timestamp"},"row_version":{"type":"integer","minimum":1}}},"CreativeDetail":{"type":"object","additionalProperties":false,"required":["creative","versions"],"properties":{"creative":{"$ref":"#/components/schemas/Creative"},"versions":{"type":"array","items":{"$ref":"#/components/schemas/CreativeVersion"}}}},"ReviewChecklist":{"type":"object","additionalProperties":false,"required":["content_compliant","copyright_verified","landing_page_verified","industry_licence_verified"],"properties":{"content_compliant":{"type":"boolean"},"copyright_verified":{"type":"boolean"},"landing_page_verified":{"type":"boolean"},"industry_licence_verified":{"type":"boolean"}}},"ReviewDecision":{"type":"object","additionalProperties":false,"required":["decision","reason","checklist"],"properties":{"decision":{"enum":["approve","reject"]},"reason":{"type":"string","minLength":3,"maxLength":1000},"checklist":{"$ref":"#/components/schemas/ReviewChecklist"}}},"ReviewQueueCreative":{"type":"object","additionalProperties":false,"required":["creative","version"],"properties":{"creative":{"$ref":"#/components/schemas/Creative"},"version":{"$ref":"#/components/schemas/CreativeVersion"}}},"ReviewQueue":{"type":"object","additionalProperties":false,"required":["creative_versions","campaigns"],"properties":{"creative_versions":{"type":"array","items":{"$ref":"#/components/schemas/ReviewQueueCreative"}},"campaigns":{"type":"array","items":{"$ref":"#/components/schemas/Campaign"}}}},"CampaignStatus":{"enum":["DRAFT","SUBMITTED","REVIEWING","APPROVED","REJECTED","FUNDED","SCHEDULED","SERVING","PAUSED","EXPIRED","TAKEN_DOWN","CANCELLED","RECONCILED","SETTLED","REFUNDED"]},"PricingModel":{"enum":["verified_play","attention_second","qualified_group_view"]},"Targeting":{"type":"object","additionalProperties":false,"required":["countries","regions","cities","venue_types","screen_classes","public_space","dayparts"],"properties":{"countries":{"type":"array","maxItems":50,"uniqueItems":true,"items":{"type":"string","pattern":"^[A-Z]{2}$"}},"regions":{"type":"array","maxItems":50,"items":{"type":"string","minLength":1,"maxLength":100}},"cities":{"type":"array","maxItems":50,"items":{"type":"string","minLength":1,"maxLength":100}},"venue_types":{"type":"array","uniqueItems":true,"items":{"$ref":"#/components/schemas/VenueType"}},"screen_classes":{"type":"array","uniqueItems":true,"items":{"$ref":"#/components/schemas/ScreenClass"}},"public_space":{"enum":["any","public_only","private_only"]},"dayparts":{"type":"array","maxItems":14,"items":{"$ref":"#/components/schemas/TimeWindow"}}}},"FrequencyCap":{"type":"object","additionalProperties":false,"required":["max_plays_per_screen_per_hour","max_plays_per_screen_per_day"],"properties":{"max_plays_per_screen_per_hour":{"type":"integer","minimum":1,"maximum":60},"max_plays_per_screen_per_day":{"type":"integer","minimum":1,"maximum":1440}}},"CampaignCreativeRef":{"type":"object","additionalProperties":false,"required":["creative_version_id","weight"],"properties":{"creative_version_id":{"$ref":"#/components/schemas/Uuid"},"weight":{"type":"integer","minimum":1,"maximum":100}}},"CampaignInput":{"type":"object","additionalProperties":false,"required":["contract_id","name","pricing_model","budget_total_minor","daily_budget_minor","start_at","end_at","targeting","frequency_cap","creatives"],"properties":{"contract_id":{"$ref":"#/components/schemas/Uuid"},"name":{"type":"string","minLength":1,"maxLength":200},"pricing_model":{"$ref":"#/components/schemas/PricingModel"},"budget_total_minor":{"$ref":"#/components/schemas/PositiveMinorAmount"},"daily_budget_minor":{"$ref":"#/components/schemas/PositiveMinorAmount"},"start_at":{"$ref":"#/components/schemas/Timestamp"},"end_at":{"$ref":"#/components/schemas/Timestamp"},"targeting":{"$ref":"#/components/schemas/Targeting"},"frequency_cap":{"$ref":"#/components/schemas/FrequencyCap"},"creatives":{"type":"array","minItems":1,"maxItems":20,"items":{"$ref":"#/components/schemas/CampaignCreativeRef"}},"expected_row_version":{"type":"integer","minimum":1}}},"Campaign":{"type":"object","additionalProperties":false,"required":["id","tenant_id","contract_id","name","pricing_model","currency","budget_total_minor","daily_budget_minor","start_at","end_at","targeting","frequency_cap","rate_minor","reserved_minor","status","creatives","created_by","created_at","updated_at","row_version"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"tenant_id":{"$ref":"#/components/schemas/Uuid"},"contract_id":{"$ref":"#/components/schemas/Uuid"},"name":{"type":"string"},"pricing_model":{"$ref":"#/components/schemas/PricingModel"},"currency":{"$ref":"#/components/schemas/Currency"},"budget_total_minor":{"$ref":"#/components/schemas/MinorAmount"},"daily_budget_minor":{"$ref":"#/components/schemas/MinorAmount"},"start_at":{"$ref":"#/components/schemas/Timestamp"},"end_at":{"$ref":"#/components/schemas/Timestamp"},"targeting":{"$ref":"#/components/schemas/Targeting"},"frequency_cap":{"$ref":"#/components/schemas/FrequencyCap"},"rate_minor":{"type":["string","null"],"pattern":"^[0-9]{1,18}$"},"reserved_minor":{"$ref":"#/components/schemas/MinorAmount"},"status":{"$ref":"#/components/schemas/CampaignStatus"},"creatives":{"type":"array","items":{"$ref":"#/components/schemas/CampaignCreativeRef"}},"created_by":{"type":"string"},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"},"row_version":{"type":"integer","minimum":1}}},"CampaignList":{"type":"object","additionalProperties":false,"required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Campaign"}}}},"TransitionRequest":{"type":"object","additionalProperties":false,"required":["reason"],"properties":{"reason":{"type":"string","minLength":3,"maxLength":1000},"expected_row_version":{"type":"integer","minimum":1}}},"CampaignTransition":{"type":"object","additionalProperties":false,"required":["from_status","to_status","actor_id","reason","row_version","trace_id","evidence","created_at"],"properties":{"from_status":{"$ref":"#/components/schemas/CampaignStatus"},"to_status":{"$ref":"#/components/schemas/CampaignStatus"},"actor_id":{"type":"string"},"reason":{"type":"string"},"row_version":{"type":"integer","minimum":1},"trace_id":{"type":"string"},"evidence":{"type":"object"},"created_at":{"$ref":"#/components/schemas/Timestamp"}}},"CampaignTransitionList":{"type":"object","additionalProperties":false,"required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/CampaignTransition"}}}},"RefundCreate":{"type":"object","additionalProperties":false,"required":["amount_minor","currency","reason"],"properties":{"amount_minor":{"$ref":"#/components/schemas/PositiveMinorAmount"},"currency":{"$ref":"#/components/schemas/Currency"},"reason":{"type":"string","minLength":3,"maxLength":1000}}},"Refund":{"type":"object","additionalProperties":false,"required":["id","tenant_id","amount_minor","currency","reason","status","requested_by","decided_by","decided_at","decision_reason","payment_id","created_at","updated_at","row_version"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"tenant_id":{"$ref":"#/components/schemas/Uuid"},"amount_minor":{"$ref":"#/components/schemas/MinorAmount"},"currency":{"$ref":"#/components/schemas/Currency"},"reason":{"type":"string"},"status":{"enum":["requested","approved","rejected","paid","failed"]},"requested_by":{"type":"string"},"decided_by":{"type":["string","null"]},"decided_at":{"type":["string","null"],"format":"date-time"},"decision_reason":{"type":["string","null"]},"payment_id":{"type":["string","null"],"format":"uuid"},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"},"row_version":{"type":"integer","minimum":1}}},"RefundList":{"type":"object","additionalProperties":false,"required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Refund"}}}},"Decision":{"type":"object","additionalProperties":false,"required":["decision","reason"],"properties":{"decision":{"enum":["approve","reject"]},"reason":{"type":"string","minLength":3,"maxLength":1000}}},"InvoiceCreate":{"type":"object","additionalProperties":false,"required":["currency","amount_minor","tax_rate_bps","title","taxpayer_id"],"properties":{"currency":{"$ref":"#/components/schemas/Currency"},"amount_minor":{"$ref":"#/components/schemas/PositiveMinorAmount"},"tax_rate_bps":{"type":"integer","minimum":0,"maximum":2000},"title":{"type":"string","minLength":1,"maxLength":200},"taxpayer_id":{"type":"string","pattern":"^[A-Za-z0-9]{8,30}$"}}},"Invoice":{"type":"object","additionalProperties":false,"required":["id","tenant_id","currency","amount_minor","tax_rate_bps","tax_minor","title","taxpayer_id","status","invoice_number","issued_at","decision_reason","requested_by","created_at","updated_at","row_version"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"tenant_id":{"$ref":"#/components/schemas/Uuid"},"currency":{"$ref":"#/components/schemas/Currency"},"amount_minor":{"$ref":"#/components/schemas/MinorAmount"},"tax_rate_bps":{"type":"integer"},"tax_minor":{"$ref":"#/components/schemas/MinorAmount"},"title":{"type":"string"},"taxpayer_id":{"type":"string"},"status":{"enum":["requested","issued","rejected","voided"]},"invoice_number":{"type":["string","null"]},"issued_at":{"type":["string","null"],"format":"date-time"},"decision_reason":{"type":["string","null"]},"requested_by":{"type":"string"},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"},"row_version":{"type":"integer","minimum":1}}},"InvoiceList":{"type":"object","additionalProperties":false,"required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Invoice"}}}},"InvoiceIssue":{"type":"object","additionalProperties":false,"required":["invoice_number"],"properties":{"invoice_number":{"type":"string","pattern":"^[A-Za-z0-9-]{6,40}$"}}},"SchedulerRun":{"type":"object","additionalProperties":false,"required":["ran_at","advanced"],"properties":{"ran_at":{"$ref":"#/components/schemas/Timestamp"},"advanced":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["campaign_id","from_status","to_status"],"properties":{"campaign_id":{"$ref":"#/components/schemas/Uuid"},"from_status":{"$ref":"#/components/schemas/CampaignStatus"},"to_status":{"$ref":"#/components/schemas/CampaignStatus"}}}}}},"ManifestItem":{"type":"object","additionalProperties":false,"required":["campaign_id","creative_version_id","asset_sha256","asset_path","mime","width_px","height_px","duration_ms","weight","category","frequency_cap"],"properties":{"campaign_id":{"$ref":"#/components/schemas/Uuid"},"creative_version_id":{"$ref":"#/components/schemas/Uuid"},"asset_sha256":{"$ref":"#/components/schemas/Sha256"},"asset_path":{"type":"string","pattern":"^/v1/device/assets/[0-9a-f]{64}$"},"mime":{"type":"string"},"width_px":{"type":["integer","null"]},"height_px":{"type":["integer","null"]},"duration_ms":{"type":"integer","minimum":1},"weight":{"type":"integer","minimum":1,"maximum":100},"category":{"$ref":"#/components/schemas/AdCategory"},"frequency_cap":{"$ref":"#/components/schemas/FrequencyCap"}}},"ManifestRules":{"type":"object","additionalProperties":false,"required":["rules_version","detector_interval_ms","min_verified_play_ms","viewability_threshold","max_yaw_deg","max_pitch_deg","min_gaze_on_screen","min_eye_openness","min_dwell_ms","group_min","group_min_ms","demographics_confidence"],"properties":{"rules_version":{"type":"string"},"detector_interval_ms":{"type":"integer","minimum":50},"min_verified_play_ms":{"type":"integer","minimum":1},"viewability_threshold":{"type":"number","minimum":0,"maximum":1},"max_yaw_deg":{"type":"number"},"max_pitch_deg":{"type":"number"},"min_gaze_on_screen":{"type":"number","minimum":0,"maximum":1},"min_eye_openness":{"type":"number","minimum":0,"maximum":1},"min_dwell_ms":{"type":"integer","minimum":1},"group_min":{"type":"integer","minimum":2},"group_min_ms":{"type":"integer","minimum":1},"demographics_confidence":{"type":"number","minimum":0.5,"maximum":1}}},"DeliveryManifest":{"type":"object","additionalProperties":false,"required":["manifest_id","screen_id","issued_at","expires_at","offline_grace_hours","policy_version","camera_attention_allowed","demographics_allowed","max_concurrent_viewers","items","rules"],"properties":{"manifest_id":{"$ref":"#/components/schemas/Uuid"},"screen_id":{"$ref":"#/components/schemas/Uuid"},"issued_at":{"$ref":"#/components/schemas/Timestamp"},"expires_at":{"$ref":"#/components/schemas/Timestamp"},"offline_grace_hours":{"type":"integer","minimum":0,"maximum":72},"policy_version":{"$ref":"#/components/schemas/Sha256"},"camera_attention_allowed":{"type":"boolean"},"demographics_allowed":{"type":"boolean"},"max_concurrent_viewers":{"type":"integer","minimum":1},"items":{"type":"array","maxItems":200,"items":{"$ref":"#/components/schemas/ManifestItem"}},"rules":{"$ref":"#/components/schemas/ManifestRules"}}},"SignedManifest":{"type":"object","additionalProperties":false,"required":["manifest","kid","signature"],"properties":{"manifest":{"$ref":"#/components/schemas/DeliveryManifest"},"kid":{"type":"string"},"signature":{"type":"string","pattern":"^[A-Za-z0-9_-]{86}$"}}},"EvidenceGrade":{"enum":["A","B","C","U","R"]},"DemographicCounts":{"type":"object","additionalProperties":false,"required":["age_bands","gender"],"properties":{"age_bands":{"type":"object","additionalProperties":false,"required":["0-17","18-24","25-34","35-44","45-54","55-64","65+","unknown"],"properties":{"0-17":{"type":"integer","minimum":0,"maximum":100000},"18-24":{"type":"integer","minimum":0,"maximum":100000},"25-34":{"type":"integer","minimum":0,"maximum":100000},"35-44":{"type":"integer","minimum":0,"maximum":100000},"45-54":{"type":"integer","minimum":0,"maximum":100000},"55-64":{"type":"integer","minimum":0,"maximum":100000},"65+":{"type":"integer","minimum":0,"maximum":100000},"unknown":{"type":"integer","minimum":0,"maximum":100000}}},"gender":{"type":"object","additionalProperties":false,"required":["female","male","unknown"],"properties":{"female":{"type":"integer","minimum":0,"maximum":100000},"male":{"type":"integer","minimum":0,"maximum":100000},"unknown":{"type":"integer","minimum":0,"maximum":100000}}}}},"PlaybackEvidence":{"type":"object","additionalProperties":false,"required":["played_ms","viewable_ms","avg_visible_ratio","foreground_ratio","interruptions","verified_play"],"properties":{"played_ms":{"type":"integer","minimum":0,"maximum":3600000},"viewable_ms":{"type":"integer","minimum":0,"maximum":3600000},"avg_visible_ratio":{"type":"number","minimum":0,"maximum":1},"foreground_ratio":{"type":"number","minimum":0,"maximum":1},"interruptions":{"type":"integer","minimum":0,"maximum":10000},"verified_play":{"type":"boolean"}}},"FraudFlag":{"type":"object","additionalProperties":false,"required":["code","severity"],"properties":{"code":{"type":"string","pattern":"^[a-z_]{1,64}$"},"severity":{"enum":["info","suspect"]}}},"AttentionEvidence":{"type":"object","additionalProperties":false,"required":["measured","frames_analyzed","frames_viewable","present_max","present_unique","attentive_unique","attention_ms","max_simultaneous_attentive","qualified_group_view","group_attention_ms","demographics","quality_score","occlusion_ratio","fraud_flags","attention_excluded","rules_version"],"properties":{"measured":{"const":true},"frames_analyzed":{"type":"integer","minimum":0,"maximum":1000000},"frames_viewable":{"type":"integer","minimum":0,"maximum":1000000},"present_max":{"type":"integer","minimum":0,"maximum":500},"present_unique":{"type":"integer","minimum":0,"maximum":100000},"attentive_unique":{"type":"integer","minimum":0,"maximum":100000},"attention_ms":{"type":"integer","minimum":0,"maximum":1800000000},"max_simultaneous_attentive":{"type":"integer","minimum":0,"maximum":500},"qualified_group_view":{"type":"boolean"},"group_attention_ms":{"type":"integer","minimum":0,"maximum":3600000},"demographics":{"oneOf":[{"$ref":"#/components/schemas/DemographicCounts"},{"type":"null"}]},"quality_score":{"type":"number","minimum":0,"maximum":1},"occlusion_ratio":{"type":"number","minimum":0,"maximum":1},"fraud_flags":{"type":"array","maxItems":20,"items":{"$ref":"#/components/schemas/FraudFlag"}},"attention_excluded":{"type":"boolean"},"rules_version":{"type":"string","pattern":"^[a-z0-9.-]{1,64}$"}}},"ModelInfo":{"type":"object","additionalProperties":false,"required":["name","version"],"properties":{"name":{"type":"string","pattern":"^[a-z0-9._-]{1,64}$"},"version":{"type":"string","pattern":"^[A-Za-z0-9._+-]{1,40}$"}}},"EvidenceModels":{"type":"object","additionalProperties":false,"required":["detector","landmarks","demographics"],"properties":{"detector":{"oneOf":[{"$ref":"#/components/schemas/ModelInfo"},{"type":"null"}]},"landmarks":{"oneOf":[{"$ref":"#/components/schemas/ModelInfo"},{"type":"null"}]},"demographics":{"oneOf":[{"$ref":"#/components/schemas/ModelInfo"},{"type":"null"}]}}},"EvidenceDocument":{"type":"object","additionalProperties":false,"description":"Signed by the device key over RFC 8785 canonical JSON excluding `signature`. Contains statistics only — no images, crops, templates, embeddings or track identifiers.","required":["evidence_version","event_id","screen_id","key_fingerprint","boot_id","seq","manifest_id","policy_version","campaign_id","creative_version_id","asset_sha256","started_at","ended_at","playback","attention","models","player","signature"],"properties":{"evidence_version":{"const":"openad.evidence.v1"},"event_id":{"$ref":"#/components/schemas/Uuid"},"screen_id":{"$ref":"#/components/schemas/Uuid"},"key_fingerprint":{"type":"string","pattern":"^ed25519:[0-9a-f]{32}$"},"boot_id":{"$ref":"#/components/schemas/Uuid"},"seq":{"type":"integer","minimum":0,"maximum":9007199254740991},"manifest_id":{"$ref":"#/components/schemas/Uuid"},"policy_version":{"$ref":"#/components/schemas/Sha256"},"campaign_id":{"$ref":"#/components/schemas/Uuid"},"creative_version_id":{"$ref":"#/components/schemas/Uuid"},"asset_sha256":{"$ref":"#/components/schemas/Sha256"},"started_at":{"$ref":"#/components/schemas/Timestamp"},"ended_at":{"$ref":"#/components/schemas/Timestamp"},"playback":{"$ref":"#/components/schemas/PlaybackEvidence"},"attention":{"oneOf":[{"$ref":"#/components/schemas/AttentionEvidence"},{"type":"null"}]},"models":{"$ref":"#/components/schemas/EvidenceModels"},"player":{"type":"object","additionalProperties":false,"required":["type","version"],"properties":{"type":{"enum":["web","desktop","tv","android","ios"]},"version":{"type":"string","pattern":"^[A-Za-z0-9._+-]{1,40}$"}}},"signature":{"type":"string","pattern":"^[A-Za-z0-9_-]{86}$"}}},"EvidenceBatch":{"type":"object","additionalProperties":false,"required":["items"],"properties":{"items":{"type":"array","minItems":1,"maxItems":100,"items":{"$ref":"#/components/schemas/EvidenceDocument"}}}},"EvidenceBatchResult":{"type":"object","additionalProperties":false,"required":["accepted","duplicates","rejected","results"],"properties":{"accepted":{"type":"integer","minimum":0},"duplicates":{"type":"integer","minimum":0},"rejected":{"type":"integer","minimum":0},"results":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["event_id","status","grade","reason"],"properties":{"event_id":{"$ref":"#/components/schemas/Uuid"},"status":{"enum":["accepted","duplicate","rejected"]},"grade":{"oneOf":[{"$ref":"#/components/schemas/EvidenceGrade"},{"type":"null"}]},"reason":{"type":["string","null"]}}}}}},"EvidenceView":{"type":"object","additionalProperties":false,"required":["id","event_id","screen_id","campaign_id","creative_version_id","started_at","ended_at","received_at","delivered_late","grade","effective_grade","billable_verified_play","billable_attention_ms","billable_group_view","played_ms","viewable_ms","verified_play","attention_measured","present_max","present_unique","attentive_unique","attention_ms","qualified_group_view","demographics","rules_version","validation_rules_version"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"event_id":{"$ref":"#/components/schemas/Uuid"},"screen_id":{"$ref":"#/components/schemas/Uuid"},"campaign_id":{"type":["string","null"],"format":"uuid"},"creative_version_id":{"type":["string","null"],"format":"uuid"},"started_at":{"$ref":"#/components/schemas/Timestamp"},"ended_at":{"$ref":"#/components/schemas/Timestamp"},"received_at":{"$ref":"#/components/schemas/Timestamp"},"delivered_late":{"type":"boolean"},"grade":{"$ref":"#/components/schemas/EvidenceGrade"},"effective_grade":{"$ref":"#/components/schemas/EvidenceGrade"},"billable_verified_play":{"type":"boolean"},"billable_attention_ms":{"type":"integer","minimum":0},"billable_group_view":{"type":"boolean"},"played_ms":{"type":"integer","minimum":0},"viewable_ms":{"type":"integer","minimum":0},"verified_play":{"type":"boolean"},"attention_measured":{"type":"boolean"},"present_max":{"type":["integer","null"]},"present_unique":{"type":["integer","null"]},"attentive_unique":{"type":["integer","null"]},"attention_ms":{"type":["integer","null"]},"qualified_group_view":{"type":["boolean","null"]},"demographics":{"oneOf":[{"$ref":"#/components/schemas/DemographicCounts"},{"type":"null"}]},"rules_version":{"type":["string","null"]},"validation_rules_version":{"type":"string"}}},"EvidenceList":{"type":"object","additionalProperties":false,"required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/EvidenceView"}}}},"EvidenceDecisionView":{"type":"object","additionalProperties":false,"required":["source","rule","severity","detail","created_at"],"properties":{"source":{"enum":["edge","server"]},"rule":{"type":"string"},"severity":{"enum":["info","suspect","reject"]},"detail":{"type":"string"},"created_at":{"$ref":"#/components/schemas/Timestamp"}}},"EvidenceReviewView":{"type":"object","additionalProperties":false,"required":["from_grade","to_grade","reason","reviewer_id","created_at"],"properties":{"from_grade":{"$ref":"#/components/schemas/EvidenceGrade"},"to_grade":{"$ref":"#/components/schemas/EvidenceGrade"},"reason":{"type":"string"},"reviewer_id":{"type":"string"},"created_at":{"$ref":"#/components/schemas/Timestamp"}}},"EvidenceDetail":{"type":"object","additionalProperties":false,"required":["evidence","signed_document","key_fingerprint","public_key","decisions","review"],"properties":{"evidence":{"$ref":"#/components/schemas/EvidenceView"},"signed_document":{"$ref":"#/components/schemas/EvidenceDocument"},"key_fingerprint":{"type":"string","pattern":"^ed25519:[0-9a-f]{32}$"},"public_key":{"type":"string","pattern":"^[A-Za-z0-9_-]{43}$"},"decisions":{"type":"array","items":{"$ref":"#/components/schemas/EvidenceDecisionView"}},"review":{"oneOf":[{"$ref":"#/components/schemas/EvidenceReviewView"},{"type":"null"}]}}},"EvidenceReviewRequest":{"type":"object","additionalProperties":false,"required":["to_grade","reason"],"properties":{"to_grade":{"enum":["A","B","R"]},"reason":{"type":"string","minLength":3,"maxLength":1000}}},"CampaignEvidenceSummary":{"type":"object","additionalProperties":false,"required":["campaign_id","plays_by_grade","billable_verified_plays","billable_attention_ms","billable_group_views","unique_screens","attentive_viewers","demographics","generated_at"],"properties":{"campaign_id":{"$ref":"#/components/schemas/Uuid"},"plays_by_grade":{"type":"object","additionalProperties":false,"required":["A","B","C","U","R"],"properties":{"A":{"type":"integer","minimum":0},"B":{"type":"integer","minimum":0},"C":{"type":"integer","minimum":0},"U":{"type":"integer","minimum":0},"R":{"type":"integer","minimum":0}}},"billable_verified_plays":{"type":"integer","minimum":0},"billable_attention_ms":{"type":"integer","minimum":0},"billable_group_views":{"type":"integer","minimum":0},"unique_screens":{"type":"integer","minimum":0},"attentive_viewers":{"type":"integer","minimum":0},"demographics":{"$ref":"#/components/schemas/DemographicCounts"},"generated_at":{"$ref":"#/components/schemas/Timestamp"}}},"BpsShare":{"type":"integer","minimum":5000,"maximum":10000},"TaxRuleCreate":{"type":"object","additionalProperties":false,"required":["currency","rate_bps","legal_basis","effective_from"],"properties":{"currency":{"$ref":"#/components/schemas/Currency"},"rate_bps":{"type":"integer","minimum":0,"maximum":3000},"legal_basis":{"type":"string","minLength":3,"maxLength":500},"effective_from":{"$ref":"#/components/schemas/Timestamp"}}},"TaxRule":{"type":"object","additionalProperties":false,"required":["id","version","currency","rate_bps","legal_basis","effective_from","approved_by","created_at"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"version":{"type":"integer","minimum":1},"currency":{"$ref":"#/components/schemas/Currency"},"rate_bps":{"type":"integer","minimum":0,"maximum":3000},"legal_basis":{"type":"string"},"effective_from":{"$ref":"#/components/schemas/Timestamp"},"approved_by":{"type":"string"},"created_at":{"$ref":"#/components/schemas/Timestamp"}}},"TaxRuleList":{"type":"object","additionalProperties":false,"required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/TaxRule"}}}},"RevenueShareRuleCreate":{"type":"object","additionalProperties":false,"required":["contributor_share_bps","effective_from"],"properties":{"contributor_share_bps":{"$ref":"#/components/schemas/BpsShare"},"effective_from":{"$ref":"#/components/schemas/Timestamp"},"adr_ref":{"type":"string","maxLength":64}}},"RevenueShareRule":{"type":"object","additionalProperties":false,"required":["id","version","contributor_share_bps","rounding_mode","effective_from","approved_by","adr_ref","created_at"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"version":{"type":"integer","minimum":1},"contributor_share_bps":{"$ref":"#/components/schemas/BpsShare"},"rounding_mode":{"const":"CEIL_CONTRIBUTOR"},"effective_from":{"$ref":"#/components/schemas/Timestamp"},"approved_by":{"type":"string"},"adr_ref":{"type":["string","null"]},"created_at":{"$ref":"#/components/schemas/Timestamp"}}},"RevenueShareRuleList":{"type":"object","additionalProperties":false,"required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/RevenueShareRule"}}}},"BillingRunRequest":{"type":"object","additionalProperties":false,"required":["currency"],"properties":{"currency":{"$ref":"#/components/schemas/Currency"},"campaign_id":{"$ref":"#/components/schemas/Uuid"}}},"BillingBatch":{"type":"object","additionalProperties":false,"required":["id","campaign_id","advertiser_tenant_id","currency","line_count","total_minor","journal_id","billing_rules_version","created_at"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"campaign_id":{"$ref":"#/components/schemas/Uuid"},"advertiser_tenant_id":{"$ref":"#/components/schemas/Uuid"},"currency":{"$ref":"#/components/schemas/Currency"},"line_count":{"type":"integer","minimum":1},"total_minor":{"$ref":"#/components/schemas/MinorAmount"},"journal_id":{"type":["string","null"],"format":"uuid"},"billing_rules_version":{"type":"string"},"created_at":{"$ref":"#/components/schemas/Timestamp"}}},"BillingRunResult":{"type":"object","additionalProperties":false,"required":["currency","batches","lines_created","billed_minor","pending_review"],"properties":{"currency":{"$ref":"#/components/schemas/Currency"},"batches":{"type":"array","items":{"$ref":"#/components/schemas/BillingBatch"}},"lines_created":{"type":"integer","minimum":0},"billed_minor":{"$ref":"#/components/schemas/MinorAmount"},"pending_review":{"type":"integer","minimum":0}}},"BillingLine":{"type":"object","additionalProperties":false,"required":["id","batch_id","evidence_id","campaign_id","advertiser_tenant_id","contributor_tenant_id","screen_id","currency","pricing_model","rate_minor","units","units_before","charged_before_minor","charge_minor","capped","evidence_grade","evidence_started_at","settled","ivt_refunded","created_at"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"batch_id":{"$ref":"#/components/schemas/Uuid"},"evidence_id":{"$ref":"#/components/schemas/Uuid"},"campaign_id":{"$ref":"#/components/schemas/Uuid"},"advertiser_tenant_id":{"$ref":"#/components/schemas/Uuid"},"contributor_tenant_id":{"$ref":"#/components/schemas/Uuid"},"screen_id":{"$ref":"#/components/schemas/Uuid"},"currency":{"$ref":"#/components/schemas/Currency"},"pricing_model":{"$ref":"#/components/schemas/PricingModel"},"rate_minor":{"$ref":"#/components/schemas/MinorAmount"},"units":{"$ref":"#/components/schemas/MinorAmount"},"units_before":{"$ref":"#/components/schemas/MinorAmount"},"charged_before_minor":{"$ref":"#/components/schemas/MinorAmount"},"charge_minor":{"$ref":"#/components/schemas/MinorAmount"},"capped":{"type":"boolean"},"evidence_grade":{"enum":["A","B"]},"evidence_started_at":{"$ref":"#/components/schemas/Timestamp"},"settled":{"type":"boolean"},"ivt_refunded":{"type":"boolean"},"created_at":{"$ref":"#/components/schemas/Timestamp"}}},"BillingLineList":{"type":"object","additionalProperties":false,"required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/BillingLine"}}}},"IvtFinding":{"type":"object","additionalProperties":false,"required":["id","billing_line_id","evidence_id","campaign_id","advertiser_tenant_id","contributor_tenant_id","currency","amount_minor","reason","decided_by","journal_id","created_at"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"billing_line_id":{"$ref":"#/components/schemas/Uuid"},"evidence_id":{"$ref":"#/components/schemas/Uuid"},"campaign_id":{"$ref":"#/components/schemas/Uuid"},"advertiser_tenant_id":{"$ref":"#/components/schemas/Uuid"},"contributor_tenant_id":{"$ref":"#/components/schemas/Uuid"},"currency":{"$ref":"#/components/schemas/Currency"},"amount_minor":{"$ref":"#/components/schemas/MinorAmount"},"reason":{"type":"string"},"decided_by":{"type":"string"},"journal_id":{"type":["string","null"],"format":"uuid"},"created_at":{"$ref":"#/components/schemas/Timestamp"}}},"CampaignReconciliation":{"type":"object","additionalProperties":false,"required":["campaign_id","status","billed_minor","released_minor","release_journal_id","lines_created"],"properties":{"campaign_id":{"$ref":"#/components/schemas/Uuid"},"status":{"$ref":"#/components/schemas/CampaignStatus"},"billed_minor":{"$ref":"#/components/schemas/MinorAmount"},"released_minor":{"$ref":"#/components/schemas/MinorAmount"},"release_journal_id":{"type":["string","null"],"format":"uuid"},"lines_created":{"type":"integer","minimum":0}}},"SettlementCreate":{"type":"object","additionalProperties":false,"required":["currency","period_start","period_end"],"properties":{"currency":{"$ref":"#/components/schemas/Currency"},"period_start":{"$ref":"#/components/schemas/Timestamp"},"period_end":{"$ref":"#/components/schemas/Timestamp"}}},"SettlementStatus":{"enum":["CALCULATED","POSTED","REVERSED","DISCARDED"]},"Settlement":{"type":"object","additionalProperties":false,"required":["id","status","currency","period_start","period_end","rule_version","rule_share_bps","tax_rule_version","tax_rate_bps","rules_version","confirmed_media_spend_minor","confirmed_ivt_refund_minor","indirect_tax_minor","bmr_minor","contributor_pool_minor","platform_share_minor","contributor_ratio_bps","compliant","input_hash","output_hash","journal_id","reversal_journal_id","created_by","created_at","posted_at"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"status":{"$ref":"#/components/schemas/SettlementStatus"},"currency":{"$ref":"#/components/schemas/Currency"},"period_start":{"$ref":"#/components/schemas/Timestamp"},"period_end":{"$ref":"#/components/schemas/Timestamp"},"rule_version":{"type":"integer","minimum":1},"rule_share_bps":{"$ref":"#/components/schemas/BpsShare"},"tax_rule_version":{"type":["integer","null"],"minimum":1},"tax_rate_bps":{"type":["integer","null"],"minimum":0,"maximum":3000},"rules_version":{"type":["string","null"]},"confirmed_media_spend_minor":{"$ref":"#/components/schemas/MinorAmount"},"confirmed_ivt_refund_minor":{"$ref":"#/components/schemas/MinorAmount"},"indirect_tax_minor":{"$ref":"#/components/schemas/MinorAmount"},"bmr_minor":{"$ref":"#/components/schemas/MinorAmount"},"contributor_pool_minor":{"$ref":"#/components/schemas/MinorAmount"},"platform_share_minor":{"$ref":"#/components/schemas/MinorAmount"},"contributor_ratio_bps":{"type":"integer","minimum":5000,"maximum":10000},"compliant":{"const":true},"input_hash":{"type":"string","pattern":"^[0-9a-f]{64}$"},"output_hash":{"type":"string","pattern":"^[0-9a-f]{64}$"},"journal_id":{"type":["string","null"],"format":"uuid"},"reversal_journal_id":{"type":["string","null"],"format":"uuid"},"created_by":{"type":"string"},"created_at":{"$ref":"#/components/schemas/Timestamp"},"posted_at":{"type":["string","null"],"format":"date-time"}}},"SettlementAllocation":{"type":"object","additionalProperties":false,"required":["contributor_tenant_id","weight_units","amount_minor"],"properties":{"contributor_tenant_id":{"$ref":"#/components/schemas/Uuid"},"weight_units":{"$ref":"#/components/schemas/MinorAmount"},"amount_minor":{"$ref":"#/components/schemas/MinorAmount"}}},"SettlementDetail":{"type":"object","additionalProperties":false,"required":["settlement","allocations","billing_line_count","ivt_finding_ids","deferred_ivt_finding_ids"],"properties":{"settlement":{"$ref":"#/components/schemas/Settlement"},"allocations":{"type":"array","items":{"$ref":"#/components/schemas/SettlementAllocation"}},"billing_line_count":{"type":"integer","minimum":0},"ivt_finding_ids":{"type":"array","items":{"$ref":"#/components/schemas/Uuid"}},"deferred_ivt_finding_ids":{"type":"array","items":{"$ref":"#/components/schemas/Uuid"}}}},"SettlementList":{"type":"object","additionalProperties":false,"required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Settlement"}}}},"SettlementReplay":{"type":"object","additionalProperties":false,"required":["settlement_id","stored_input_hash","stored_output_hash","replayed_input_hash","replayed_output_hash","billing_lines_verified","billing_line_mismatches","matches"],"properties":{"settlement_id":{"$ref":"#/components/schemas/Uuid"},"stored_input_hash":{"type":"string","pattern":"^[0-9a-f]{64}$"},"stored_output_hash":{"type":"string","pattern":"^[0-9a-f]{64}$"},"replayed_input_hash":{"type":"string","pattern":"^[0-9a-f]{64}$"},"replayed_output_hash":{"type":"string","pattern":"^[0-9a-f]{64}$"},"billing_lines_verified":{"type":"integer","minimum":0},"billing_line_mismatches":{"type":"array","items":{"$ref":"#/components/schemas/Uuid"}},"matches":{"type":"boolean"}}},"ContributorShareReportItem":{"type":"object","additionalProperties":false,"required":["settlement_id","status","currency","period_start","period_end","rule_share_bps","bmr_minor","contributor_pool_minor","platform_share_minor","contributor_ratio_bps","compliant"],"properties":{"settlement_id":{"$ref":"#/components/schemas/Uuid"},"status":{"$ref":"#/components/schemas/SettlementStatus"},"currency":{"$ref":"#/components/schemas/Currency"},"period_start":{"$ref":"#/components/schemas/Timestamp"},"period_end":{"$ref":"#/components/schemas/Timestamp"},"rule_share_bps":{"$ref":"#/components/schemas/BpsShare"},"bmr_minor":{"$ref":"#/components/schemas/MinorAmount"},"contributor_pool_minor":{"$ref":"#/components/schemas/MinorAmount"},"platform_share_minor":{"$ref":"#/components/schemas/MinorAmount"},"contributor_ratio_bps":{"type":"integer","minimum":0,"maximum":10000},"compliant":{"type":"boolean"}}},"ContributorShareReport":{"type":"object","additionalProperties":false,"required":["items","settlements","all_compliant","minimum_ratio_bps","generated_at"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/ContributorShareReportItem"}},"settlements":{"type":"integer","minimum":0},"all_compliant":{"type":"boolean"},"minimum_ratio_bps":{"type":["integer","null"]},"generated_at":{"$ref":"#/components/schemas/Timestamp"}}},"ReconciliationRequest":{"type":"object","additionalProperties":false,"required":["currency"],"properties":{"currency":{"$ref":"#/components/schemas/Currency"}}},"ReconciliationCheck":{"type":"object","additionalProperties":false,"required":["name","passed","expected","actual","detail"],"properties":{"name":{"type":"string","pattern":"^[a-z_]+$"},"passed":{"type":"boolean"},"expected":{"type":"string"},"actual":{"type":"string"},"detail":{"type":"string"}}},"ReconciliationRun":{"type":"object","additionalProperties":false,"required":["id","currency","passed","checks","result_hash","created_by","created_at"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"currency":{"$ref":"#/components/schemas/Currency"},"passed":{"type":"boolean"},"checks":{"type":"array","items":{"$ref":"#/components/schemas/ReconciliationCheck"}},"result_hash":{"type":"string","pattern":"^[0-9a-f]{64}$"},"created_by":{"type":"string"},"created_at":{"$ref":"#/components/schemas/Timestamp"}}},"EarningsAllocation":{"type":"object","additionalProperties":false,"required":["settlement_id","status","period_start","period_end","amount_minor"],"properties":{"settlement_id":{"$ref":"#/components/schemas/Uuid"},"status":{"$ref":"#/components/schemas/SettlementStatus"},"period_start":{"$ref":"#/components/schemas/Timestamp"},"period_end":{"$ref":"#/components/schemas/Timestamp"},"amount_minor":{"$ref":"#/components/schemas/MinorAmount"}}},"Earnings":{"type":"object","additionalProperties":false,"required":["tenant_id","currency","settled_total_minor","payable_minor","withdrawal_pending_minor","withdrawn_minor","awg_offset_total_minor","water_coin_balance","allocations"],"properties":{"tenant_id":{"$ref":"#/components/schemas/Uuid"},"currency":{"$ref":"#/components/schemas/Currency"},"settled_total_minor":{"$ref":"#/components/schemas/MinorAmount"},"payable_minor":{"$ref":"#/components/schemas/MinorAmount"},"withdrawal_pending_minor":{"$ref":"#/components/schemas/MinorAmount"},"withdrawn_minor":{"$ref":"#/components/schemas/MinorAmount"},"awg_offset_total_minor":{"$ref":"#/components/schemas/MinorAmount"},"water_coin_balance":{"$ref":"#/components/schemas/MinorAmount"},"allocations":{"type":"array","items":{"$ref":"#/components/schemas/EarningsAllocation"}}}},"WithdrawalCreate":{"type":"object","additionalProperties":false,"required":["currency","amount_minor"],"properties":{"currency":{"$ref":"#/components/schemas/Currency"},"amount_minor":{"$ref":"#/components/schemas/PositiveMinorAmount"}}},"WithdrawalDecision":{"type":"object","additionalProperties":false,"required":["decision","reason"],"properties":{"decision":{"enum":["approve","reject"]},"reason":{"type":"string","minLength":3,"maxLength":1000},"sandbox_outcome":{"enum":["succeeded","failed"]}}},"Withdrawal":{"type":"object","additionalProperties":false,"required":["id","tenant_id","currency","amount_minor","provider","status","requested_by","decided_by","decision_reason","hold_journal_id","settle_journal_id","provider_ref","created_at","completed_at"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"tenant_id":{"$ref":"#/components/schemas/Uuid"},"currency":{"$ref":"#/components/schemas/Currency"},"amount_minor":{"$ref":"#/components/schemas/PositiveMinorAmount"},"provider":{"const":"sandbox"},"status":{"enum":["requested","approved","rejected","paid","failed"]},"requested_by":{"type":"string"},"decided_by":{"type":["string","null"]},"decision_reason":{"type":["string","null"]},"hold_journal_id":{"$ref":"#/components/schemas/Uuid"},"settle_journal_id":{"type":["string","null"],"format":"uuid"},"provider_ref":{"type":["string","null"]},"created_at":{"$ref":"#/components/schemas/Timestamp"},"completed_at":{"type":["string","null"],"format":"date-time"}}},"WithdrawalList":{"type":"object","additionalProperties":false,"required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Withdrawal"}}}},"PointsRuleCreate":{"type":"object","additionalProperties":false,"required":["cash_currency","cash_minor_per_unit","terms_version","effective_from"],"properties":{"cash_currency":{"$ref":"#/components/schemas/Currency"},"cash_minor_per_unit":{"$ref":"#/components/schemas/PositiveMinorAmount"},"terms_version":{"$ref":"#/components/schemas/DocumentVersion"},"effective_from":{"$ref":"#/components/schemas/Timestamp"}}},"PointsRule":{"type":"object","additionalProperties":false,"required":["id","version","unit","cash_currency","cash_minor_per_unit","transferable","cash_out_allowed","terms_version","effective_from","approved_by","created_at"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"version":{"type":"integer","minimum":1},"unit":{"const":"WTC"},"cash_currency":{"$ref":"#/components/schemas/Currency"},"cash_minor_per_unit":{"$ref":"#/components/schemas/PositiveMinorAmount"},"transferable":{"const":false},"cash_out_allowed":{"const":false},"terms_version":{"type":"string"},"effective_from":{"$ref":"#/components/schemas/Timestamp"},"approved_by":{"type":"string"},"created_at":{"$ref":"#/components/schemas/Timestamp"}}},"PointsConversionCreate":{"type":"object","additionalProperties":false,"required":["currency","cash_minor"],"properties":{"currency":{"$ref":"#/components/schemas/Currency"},"cash_minor":{"$ref":"#/components/schemas/PositiveMinorAmount"}}},"PointsConversion":{"type":"object","additionalProperties":false,"required":["id","tenant_id","rule_version","cash_currency","cash_minor","cash_remainder_minor","unit","points_units","cash_equivalent_per_unit_minor","cash_journal_id","points_journal_id","created_at"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"tenant_id":{"$ref":"#/components/schemas/Uuid"},"rule_version":{"type":"integer","minimum":1},"cash_currency":{"$ref":"#/components/schemas/Currency"},"cash_minor":{"$ref":"#/components/schemas/PositiveMinorAmount"},"cash_remainder_minor":{"$ref":"#/components/schemas/MinorAmount"},"unit":{"const":"WTC"},"points_units":{"$ref":"#/components/schemas/PositiveMinorAmount"},"cash_equivalent_per_unit_minor":{"$ref":"#/components/schemas/PositiveMinorAmount"},"cash_journal_id":{"$ref":"#/components/schemas/Uuid"},"points_journal_id":{"$ref":"#/components/schemas/Uuid"},"created_at":{"$ref":"#/components/schemas/Timestamp"}}},"PointsRedemptionCreate":{"type":"object","additionalProperties":false,"required":["tenant_id","points_units","reference"],"properties":{"tenant_id":{"$ref":"#/components/schemas/Uuid"},"points_units":{"$ref":"#/components/schemas/PositiveMinorAmount"},"reference":{"type":"string","pattern":"^[A-Za-z0-9._:-]{4,128}$"},"awg_contract_id":{"$ref":"#/components/schemas/Uuid"}}},"PointsRedemption":{"type":"object","additionalProperties":false,"required":["id","tenant_id","unit","points_units","purpose","reference","awg_contract_id","journal_id","created_at"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"tenant_id":{"$ref":"#/components/schemas/Uuid"},"unit":{"const":"WTC"},"points_units":{"$ref":"#/components/schemas/PositiveMinorAmount"},"purpose":{"const":"water_consumption"},"reference":{"type":"string"},"awg_contract_id":{"type":["string","null"],"format":"uuid"},"journal_id":{"$ref":"#/components/schemas/Uuid"},"created_at":{"$ref":"#/components/schemas/Timestamp"}}},"AwgContractCreate":{"type":"object","additionalProperties":false,"required":["tenant_id","contract_no","device_serial","currency","deposit_total_minor","signed_document_sha256","exit_rules_version"],"properties":{"tenant_id":{"$ref":"#/components/schemas/Uuid"},"contract_no":{"type":"string","pattern":"^[A-Za-z0-9._-]{4,64}$"},"device_serial":{"type":"string","pattern":"^[A-Za-z0-9._-]{4,64}$"},"currency":{"$ref":"#/components/schemas/Currency"},"deposit_total_minor":{"$ref":"#/components/schemas/PositiveMinorAmount"},"signed_document_sha256":{"type":"string","pattern":"^[0-9a-f]{64}$"},"exit_rules_version":{"$ref":"#/components/schemas/DocumentVersion"}}},"AwgContract":{"type":"object","additionalProperties":false,"required":["id","tenant_id","contract_no","device_serial","currency","deposit_total_minor","offset_total_minor","written_off_minor","outstanding_minor","exit_rules_version","status","offset_elected","election_updated_at","activated_at","completed_at","terminated_at","termination_reason","created_at","row_version"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"tenant_id":{"$ref":"#/components/schemas/Uuid"},"contract_no":{"type":"string"},"device_serial":{"type":"string"},"currency":{"$ref":"#/components/schemas/Currency"},"deposit_total_minor":{"$ref":"#/components/schemas/PositiveMinorAmount"},"offset_total_minor":{"$ref":"#/components/schemas/MinorAmount"},"written_off_minor":{"$ref":"#/components/schemas/MinorAmount"},"outstanding_minor":{"$ref":"#/components/schemas/MinorAmount"},"exit_rules_version":{"type":"string"},"status":{"enum":["draft","active","completed","terminated"]},"offset_elected":{"type":"boolean"},"election_updated_at":{"type":["string","null"],"format":"date-time"},"activated_at":{"type":["string","null"],"format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"},"terminated_at":{"type":["string","null"],"format":"date-time"},"termination_reason":{"type":["string","null"]},"created_at":{"$ref":"#/components/schemas/Timestamp"},"row_version":{"type":"integer","minimum":1}}},"AwgContractList":{"type":"object","additionalProperties":false,"required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/AwgContract"}}}},"AwgElectionRequest":{"type":"object","additionalProperties":false,"required":["elect","acknowledged_outstanding_minor","acknowledged_exit_rules_version"],"properties":{"elect":{"type":"boolean"},"acknowledged_outstanding_minor":{"$ref":"#/components/schemas/MinorAmount"},"acknowledged_exit_rules_version":{"$ref":"#/components/schemas/DocumentVersion"}}},"AwgOffsetRunRequest":{"type":"object","additionalProperties":false,"required":["currency"],"properties":{"currency":{"$ref":"#/components/schemas/Currency"}}},"AwgOffset":{"type":"object","additionalProperties":false,"required":["id","contract_id","tenant_id","amount_minor","outstanding_minor","journal_id"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"contract_id":{"$ref":"#/components/schemas/Uuid"},"tenant_id":{"$ref":"#/components/schemas/Uuid"},"amount_minor":{"$ref":"#/components/schemas/PositiveMinorAmount"},"outstanding_minor":{"$ref":"#/components/schemas/MinorAmount"},"journal_id":{"$ref":"#/components/schemas/Uuid"}}},"AwgOffsetRunResult":{"type":"object","additionalProperties":false,"required":["currency","offsets","completed_contracts"],"properties":{"currency":{"$ref":"#/components/schemas/Currency"},"offsets":{"type":"array","items":{"$ref":"#/components/schemas/AwgOffset"}},"completed_contracts":{"type":"array","items":{"$ref":"#/components/schemas/Uuid"}}}},"AppealCreate":{"type":"object","additionalProperties":false,"required":["subject_type","category","title","message"],"properties":{"subject_type":{"enum":["campaign","creative_version","evidence","billing_line","settlement","withdrawal","screen","awg_contract","other"]},"subject_id":{"$ref":"#/components/schemas/Uuid"},"category":{"enum":["review_decision","billing","earnings","evidence_grade","emergency_stop","privacy","account","other"]},"title":{"type":"string","minLength":3,"maxLength":200},"message":{"type":"string","minLength":1,"maxLength":4000}}},"AppealMessageCreate":{"type":"object","additionalProperties":false,"required":["body"],"properties":{"body":{"type":"string","minLength":1,"maxLength":4000}}},"AppealDecision":{"type":"object","additionalProperties":false,"required":["status","message"],"properties":{"status":{"enum":["in_review","resolved","rejected"]},"message":{"type":"string","minLength":1,"maxLength":4000},"resolution":{"type":"string","minLength":3,"maxLength":2000}}},"AppealMessage":{"type":"object","additionalProperties":false,"required":["id","author_type","author_id","body","created_at"],"properties":{"id":{"type":"integer","minimum":1},"author_type":{"enum":["tenant","platform"]},"author_id":{"type":"string"},"body":{"type":"string"},"created_at":{"$ref":"#/components/schemas/Timestamp"}}},"Appeal":{"type":"object","additionalProperties":false,"required":["id","tenant_id","subject_type","subject_id","category","title","status","resolution","handled_by","opened_by","sla_due_at","overdue","created_at","updated_at","closed_at","row_version","messages"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"tenant_id":{"$ref":"#/components/schemas/Uuid"},"subject_type":{"enum":["campaign","creative_version","evidence","billing_line","settlement","withdrawal","screen","awg_contract","other"]},"subject_id":{"type":["string","null"],"format":"uuid"},"category":{"enum":["review_decision","billing","earnings","evidence_grade","emergency_stop","privacy","account","other"]},"title":{"type":"string"},"status":{"enum":["open","in_review","resolved","rejected"]},"resolution":{"type":["string","null"]},"handled_by":{"type":["string","null"]},"opened_by":{"type":"string"},"sla_due_at":{"$ref":"#/components/schemas/Timestamp"},"overdue":{"type":"boolean"},"created_at":{"$ref":"#/components/schemas/Timestamp"},"updated_at":{"$ref":"#/components/schemas/Timestamp"},"closed_at":{"type":["string","null"],"format":"date-time"},"row_version":{"type":"integer","minimum":1},"messages":{"type":"array","items":{"$ref":"#/components/schemas/AppealMessage"}}}},"AppealList":{"type":"object","additionalProperties":false,"required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Appeal"}}}},"Alert":{"type":"object","additionalProperties":false,"required":["id","dedupe_key","severity","category","title","detail","tenant_id","status","occurrences","first_seen_at","last_seen_at","acknowledged_by","acknowledged_at","resolved_by","resolved_at","resolution"],"properties":{"id":{"$ref":"#/components/schemas/Uuid"},"dedupe_key":{"type":"string"},"severity":{"enum":["info","warning","critical"]},"category":{"enum":["reconciliation","contributor_share","evidence_review","device_offline","withdrawal_backlog","emergency_stop","audit_chain","outbox","appeal_sla"]},"title":{"type":"string"},"detail":{"type":"object"},"tenant_id":{"type":["string","null"],"format":"uuid"},"status":{"enum":["open","acknowledged","resolved"]},"occurrences":{"type":"integer","minimum":1},"first_seen_at":{"$ref":"#/components/schemas/Timestamp"},"last_seen_at":{"$ref":"#/components/schemas/Timestamp"},"acknowledged_by":{"type":["string","null"]},"acknowledged_at":{"type":["string","null"],"format":"date-time"},"resolved_by":{"type":["string","null"]},"resolved_at":{"type":["string","null"],"format":"date-time"},"resolution":{"type":["string","null"]}}},"AlertList":{"type":"object","additionalProperties":false,"required":["items"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Alert"}}}},"AlertResolve":{"type":"object","additionalProperties":false,"required":["resolution"],"properties":{"resolution":{"type":"string","minLength":3,"maxLength":1000}}},"AlertScanResult":{"type":"object","additionalProperties":false,"required":["raised","refreshed","auto_resolved","alerts"],"properties":{"raised":{"type":"integer","minimum":0},"refreshed":{"type":"integer","minimum":0},"auto_resolved":{"type":"integer","minimum":0},"alerts":{"type":"array","items":{"$ref":"#/components/schemas/Alert"}}}},"AuditExportManifest":{"type":"object","additionalProperties":false,"required":["format","from_seq","to_seq","count","contiguous","first_prev_hash","last_hash","chain_verified","chain_checked","export_sha256","exported_by","exported_at"],"properties":{"format":{"const":"openad.audit-export.v1"},"from_seq":{"type":["integer","null"]},"to_seq":{"type":["integer","null"]},"count":{"type":"integer","minimum":0},"contiguous":{"type":"boolean"},"first_prev_hash":{"type":["string","null"],"pattern":"^[0-9a-f]{64}$"},"last_hash":{"type":["string","null"],"pattern":"^[0-9a-f]{64}$"},"chain_verified":{"type":"boolean"},"chain_checked":{"type":"integer","minimum":0},"export_sha256":{"type":"string","pattern":"^[0-9a-f]{64}$"},"exported_by":{"type":"string"},"exported_at":{"$ref":"#/components/schemas/Timestamp"}}},"AuditExport":{"type":"object","additionalProperties":false,"required":["manifest","items"],"properties":{"manifest":{"$ref":"#/components/schemas/AuditExportManifest"},"items":{"type":"array","items":{"$ref":"#/components/schemas/AuditEvent"}}}},"OperationsOverview":{"type":"object","additionalProperties":false,"required":["generated_at","review_queue","evidence_pending_review","appeals","alerts","campaigns_by_status","screens","withdrawals_pending","latest_reconciliations","contributor_share"],"properties":{"generated_at":{"$ref":"#/components/schemas/Timestamp"},"review_queue":{"type":"object","additionalProperties":false,"required":["creative_versions","campaigns"],"properties":{"creative_versions":{"type":"integer","minimum":0},"campaigns":{"type":"integer","minimum":0}}},"evidence_pending_review":{"type":"integer","minimum":0},"appeals":{"type":"object","additionalProperties":false,"required":["open","in_review","overdue"],"properties":{"open":{"type":"integer","minimum":0},"in_review":{"type":"integer","minimum":0},"overdue":{"type":"integer","minimum":0}}},"alerts":{"type":"object","additionalProperties":false,"required":["critical","warning","info"],"properties":{"critical":{"type":"integer","minimum":0},"warning":{"type":"integer","minimum":0},"info":{"type":"integer","minimum":0}}},"campaigns_by_status":{"type":"object","additionalProperties":{"type":"integer","minimum":0}},"screens":{"type":"object","additionalProperties":false,"required":["active","offline"],"properties":{"active":{"type":"integer","minimum":0},"offline":{"type":"integer","minimum":0}}},"withdrawals_pending":{"type":"integer","minimum":0},"latest_reconciliations":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["currency","passed","created_at"],"properties":{"currency":{"$ref":"#/components/schemas/Currency"},"passed":{"type":"boolean"},"created_at":{"$ref":"#/components/schemas/Timestamp"}}}},"contributor_share":{"type":"object","additionalProperties":false,"required":["settlements","all_compliant","minimum_ratio_bps"],"properties":{"settlements":{"type":"integer","minimum":0},"all_compliant":{"type":"boolean"},"minimum_ratio_bps":{"type":["integer","null"]}}}}}}}}