# Ad System HTTP API v1 — reference requests
# Use a REST Client compatible editor. Replace placeholders with your own local values.
# Do not send static sample playback evidence as proof of a real view.

@baseUrl = http://127.0.0.1:3000/v1
@publicAppId = app_demo
@installationId = replace-with-a-stable-installation-id
@clientToken = replace-with-client-token
@appKey = replace-with-server-key-on-your-business-backend-only
@sessionId = replace-with-session-id
@rewardId = replace-with-reward-id
@grantId = replace-with-grant-id
@requestKey = replace-with-one-stable-key-per-load-attempt

### Health
GET {{baseUrl}}/health

### Anonymous identity (client_claim applications only)
POST {{baseUrl}}/client/anonymous-sessions
Content-Type: application/json

{"appId":"{{publicAppId}}","installationId":"{{installationId}}"}

### Current application configuration
GET {{baseUrl}}/client/config
Authorization: Bearer {{clientToken}}

### Load an advertisement; retries must keep both this key and the request body
POST {{baseUrl}}/client/ad-sessions
Authorization: Bearer {{clientToken}}
Idempotency-Key: {{requestKey}}
Content-Type: application/json

{"placementCode":"daily_bonus"}

### Start only when the actual advertisement is ready to be shown
POST {{baseUrl}}/client/ad-sessions/{{sessionId}}/start
Authorization: Bearer {{clientToken}}
Content-Type: application/json

{}

### Query authoritative state
GET {{baseUrl}}/client/ad-sessions/{{sessionId}}
Authorization: Bearer {{clientToken}}

### Event envelope example: paused/hidden state, does not earn viewing credit
# Real renderers supply cumulative measured visibleSeconds, increasing sequence
# and stable eventId values across retries. Never reuse this static record as evidence.
POST {{baseUrl}}/client/ad-sessions/{{sessionId}}/events
Authorization: Bearer {{clientToken}}
Content-Type: application/json

{"events":[{"eventId":"replace-with-stable-event-id","type":"heartbeat","sequence":1,"visible":false,"visibleSeconds":0,"positionSeconds":0}]}

### List up to the latest 100 rewards for this client identity
GET {{baseUrl}}/client/rewards
Authorization: Bearer {{clientToken}}

### Claim only after ELIGIBLE, only for client_claim mode
# The server deduplicates by rewardId; this header is not used as the claim ledger key.
POST {{baseUrl}}/client/rewards/{{rewardId}}/claim
Authorization: Bearer {{clientToken}}
Idempotency-Key: claim:{{rewardId}}
Content-Type: application/json

{}

### Report local application; this is not trusted business fulfillment
POST {{baseUrl}}/client/rewards/{{rewardId}}/reported-applied
Authorization: Bearer {{clientToken}}
Content-Type: application/json

{}

### Business backend only: token for an authenticated user
POST {{baseUrl}}/server/client-tokens
X-App-Key: {{appKey}}
Content-Type: application/json

{"subjectId":"your-authenticated-user-id"}

### Business backend only: single-use reward intent
POST {{baseUrl}}/server/reward-intents
X-App-Key: {{appKey}}
Content-Type: application/json

{"subjectId":"your-authenticated-user-id","placementCode":"daily_bonus","businessKey":"your-business-event-id"}

### Server reward synchronization; use returned nextCursor in subsequent requests
GET {{baseUrl}}/server/rewards
X-App-Key: {{appKey}}

### Consume a server_pull reward and obtain its stable grant
POST {{baseUrl}}/server/rewards/{{rewardId}}/consume
X-App-Key: {{appKey}}
Content-Type: application/json

{}

### Acknowledge ONLY after the business asset transaction has committed
POST {{baseUrl}}/server/rewards/{{rewardId}}/acknowledge
X-App-Key: {{appKey}}
Content-Type: application/json

{"grantId":"{{grantId}}"}
