{"openapi":"3.0.3","info":{"title":"Adlocaite API","version":"1.0.0","description":"Public API for screens and offers. Import into Postman and set an API key (publisher or organization) as the Bearer token.","x-postman-meta":{"currentHelper":"bearerAuth","helperAttributes":{"bearerAuth":{"token":"{{PUBLISHER_API_KEY}}"}}}},"servers":[{"url":"https://staging.api.adlocaite.com/functions/v1/api","description":"Staging","variables":{"environment":{"default":"staging","description":"API environment"}}}],"x-postman-variables":[{"key":"PUBLISHER_API_KEY","value":"pub_xxxx","description":"Your Publisher API Key from Adlocaite Dashboard","type":"string"},{"key":"SCREEN_ID","value":"","description":"Screen UUID for testing","type":"string"},{"key":"EXTERNAL_ID","value":"","description":"External Screen ID for testing","type":"string"},{"key":"OFFER_ID","value":"","description":"Offer ID for response testing","type":"string"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API_KEY","description":"Bearer token authentication using publisher API key (pub_...) or organization API key (org_...)"}},"examples":{"bearerTokenExample":{"summary":"Bearer Token Example","value":"{{PUBLISHER_API_KEY}}"}},"schemas":{"OfferResponseBody":{"type":"object","properties":{"action":{"type":"string","enum":["accept","reject"]},"accepted_price_cents":{"type":"number"},"rejection_reason":{"type":"string"}},"required":["action"]}}},"security":[{"bearerAuth":[]}],"paths":{"/screens/{screenId}/cacheable-assets":{"get":{"summary":"Get cacheable assets for a screen","parameters":[{"name":"screenId","in":"path","required":true,"schema":{"type":"string"}},{"name":"min_bid_cents","in":"query","required":false,"schema":{"type":"integer","format":"int32"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"404":{"description":"Screen not found"},"500":{"description":"Server error"}}}},"/screens/external-id/{externalId}/cacheable-assets":{"get":{"summary":"Get cacheable assets for an external id","parameters":[{"name":"externalId","in":"path","required":true,"schema":{"type":"string"}},{"name":"min_bid_cents","in":"query","required":false,"schema":{"type":"integer","format":"int32"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"404":{"description":"Not found"},"500":{"description":"Server error"}}}},"/offers/request/{screenId}":{"get":{"summary":"Request an offer for a screen","parameters":[{"name":"screenId","in":"path","required":true,"schema":{"type":"string"}},{"name":"min_bid_cents","in":"query","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"demo","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"vast","in":"query","required":false,"schema":{"type":"boolean"},"description":"Include VAST XML in response when true"}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"404":{"description":"No matches / not found"},"422":{"description":"No sufficient bids"},"500":{"description":"Server error"}}}},"/offers/request/external-id/{externalId}":{"get":{"summary":"Request an offer for an external id","parameters":[{"name":"externalId","in":"path","required":true,"schema":{"type":"string"}},{"name":"min_bid_cents","in":"query","required":false,"schema":{"type":"integer","format":"int32"}},{"name":"demo","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"vast","in":"query","required":false,"schema":{"type":"boolean"},"description":"Include VAST XML in response when true"}],"responses":{"200":{"description":"OK"},"401":{"description":"Unauthorized"},"404":{"description":"No matches / not found"},"422":{"description":"No sufficient bids"},"500":{"description":"Server error"}}}},"/tools/ai-insert":{"post":{"summary":"AI Insert: replace the ad space in a scene photo with a new motif","description":"Perspective-correct AI image synthesis. Accepts a publisher API key (pub_...) or an organization API key (org_...); billing charges the corresponding account balance per generation. Result URLs expire after 3 hours.","tags":["AI Creative Tools"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"},"description":"Optional client-supplied key for retry-safety. Reusing a key after a completed request with the same tool/variants/prompt returns 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["baseImage","insertImage"],"properties":{"baseImage":{"type":"string","description":"Scene photo as URL, Base64, or Data URI (JPEG, PNG, WebP, GIF; max 10 MB)"},"insertImage":{"type":"string","description":"New motif as URL, Base64, or Data URI (JPEG, PNG, WebP, GIF; max 10 MB)"},"aspectRatio":{"type":"string","enum":["1:1","16:9","9:16","4:3","3:4","3:2","2:3","4:5","5:4","21:9"],"default":"16:9"},"prompt":{"type":"string","maxLength":2000,"description":"Optional scene modification instructions (surcharge applies)"},"variants":{"type":"integer","minimum":1,"maximum":3,"default":1,"description":"Number of variants (surcharge per additional variant)"}}}}}},"responses":{"200":{"description":"Generated images with expiry timestamps and billing info"},"400":{"description":"Invalid parameters"},"401":{"description":"Unauthorized"},"409":{"description":"Idempotency-Key was already used for a completed request"},"422":{"description":"Insufficient account balance"},"502":{"description":"Generation failed upstream; nothing was charged"},"503":{"description":"Feature not available in this environment"}}}},"/tools/ai-resize":{"post":{"summary":"AI Resize: reformat an image to a new aspect ratio","description":"Extends or recomposes an existing still image to the target dimensions. Accepts a publisher API key (pub_...) or an organization API key (org_...); billing charges the corresponding account balance per operation. Result URLs expire after 3 hours.","tags":["AI Creative Tools"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"},"description":"Optional client-supplied key for retry-safety. Reusing a key after a completed request with the same tool/variants/prompt returns 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["sourceImage","targetWidth","targetHeight"],"properties":{"sourceImage":{"type":"string","description":"Source image as URL, Base64, or Data URI (JPEG, PNG, WebP, GIF; max 10 MB)"},"targetWidth":{"type":"integer","minimum":64,"maximum":8192},"targetHeight":{"type":"integer","minimum":64,"maximum":8192},"mode":{"type":"string","enum":["extend","recompose"],"default":"extend"},"prompt":{"type":"string","maxLength":2000,"description":"Optional modification instructions (surcharge applies)"},"variants":{"type":"integer","minimum":1,"maximum":3,"default":1,"description":"Number of variants (surcharge per additional variant)"}}}}}},"responses":{"200":{"description":"Reformatted images with expiry timestamps and billing info"},"400":{"description":"Invalid parameters"},"401":{"description":"Unauthorized"},"409":{"description":"Idempotency-Key was already used for a completed request"},"422":{"description":"Insufficient account balance"},"502":{"description":"Generation failed upstream; nothing was charged"},"503":{"description":"Feature not available in this environment"}}}},"/offers/response/{offerId}":{"post":{"summary":"Accept or reject an offer","parameters":[{"name":"offerId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OfferResponseBody"}}}},"responses":{"200":{"description":"OK"},"400":{"description":"Bad request"},"401":{"description":"Unauthorized"},"404":{"description":"Offer not found"},"500":{"description":"Server error"}}}}}}