{"openapi":"3.1.0","info":{"title":"AdReads Agent Preview API","version":"1.1.0","description":"A public, read-only preview for finding podcast sponsor ad reads. Responses are capped at 10 concise records and do not support pagination or bulk export.","contact":{"email":"hello@quicklets.ai"}},"servers":[{"url":"https://www.adreads.ai"}],"externalDocs":{"description":"AdReads guidance for agents","url":"https://www.adreads.ai/llms.txt"},"paths":{"/api/v1/reads":{"get":{"operationId":"searchAdReads","summary":"Search the public AdReads preview","description":"Returns at most 10 citation-ready ad-read previews. Open each canonicalUrl for the public detail page. Pagination parameters are intentionally unsupported.","parameters":[{"name":"q","in":"query","description":"Keyword search across sponsors, podcasts, episodes, offers, promo codes, and transcript text.","schema":{"type":"string","maxLength":200}},{"name":"sponsor","in":"query","description":"Sponsor slug or stable ID.","schema":{"type":"string","maxLength":160}},{"name":"podcast","in":"query","description":"Podcast slug or stable ID.","schema":{"type":"string","maxLength":160}},{"name":"date","in":"query","description":"Only reads detected in the last 7 or 30 days.","schema":{"type":"string","enum":["7","30"]}},{"name":"placement","in":"query","description":"One or more placements. Repeat this parameter to request multiple values.","schema":{"type":"array","items":{"type":"string","enum":["PRE_ROLL","MID_ROLL","POST_ROLL","UNKNOWN"]}},"style":"form","explode":true},{"name":"sponsorCategory","in":"query","description":"Normalized sponsor category.","schema":{"type":"string","maxLength":160}},{"name":"podcastCategory","in":"query","description":"Normalized podcast category.","schema":{"type":"string","maxLength":160}},{"name":"readType","in":"query","description":"How the ad was read.","schema":{"type":"string","enum":["HOST_READ","ANNOUNCER_READ","MIXED","UNKNOWN"]}},{"name":"adObjective","in":"query","description":"Primary campaign objective inferred for the ad creative.","schema":{"type":"string","enum":["DIRECT_RESPONSE","BRAND_AWARENESS","TUNE_IN","UNKNOWN"]}},{"name":"offerType","in":"query","description":"Normalized offer type.","schema":{"type":"string","maxLength":160}},{"name":"code","in":"query","description":"Require a promo code to be present or absent.","schema":{"type":"string","enum":["present","absent"]}},{"name":"url","in":"query","description":"Require a landing URL to be present or absent.","schema":{"type":"string","enum":["present","absent"]}},{"name":"minDuration","in":"query","description":"Minimum ad duration in seconds.","schema":{"type":"number","minimum":0}},{"name":"maxDuration","in":"query","description":"Maximum ad duration in seconds.","schema":{"type":"number","minimum":0}},{"name":"appleRankMax","in":"query","description":"Maximum Apple Podcasts rank for the podcast.","schema":{"type":"number","minimum":0}},{"name":"sort","in":"query","description":"Result ordering.","schema":{"type":"string","enum":["newest","episode_recent","duration_long","duration_short","apple_rank"],"default":"newest"}}],"responses":{"200":{"description":"A bounded set of matching ad-read previews.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentSearchResponse"}}}},"400":{"description":"Unsupported or invalid query parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"AgentSearchResponse":{"type":"object","required":["schemaVersion","total","returned","hasMore","results","notice","upgradeUrl"],"properties":{"schemaVersion":{"type":"string","const":"1"},"total":{"type":"integer","minimum":0},"returned":{"type":"integer","minimum":0,"maximum":10},"hasMore":{"type":"boolean"},"results":{"type":"array","maxItems":10,"items":{"$ref":"#/components/schemas/AdReadPreview"}},"notice":{"type":"string"},"upgradeUrl":{"type":"string","format":"uri"}}},"AdReadPreview":{"type":"object","required":["id","canonicalUrl","sponsor","podcast","episode","detectedAt","placement","readType","adObjective","estimatedCurrentPlacementValue","excerpt"],"properties":{"id":{"type":"string"},"canonicalUrl":{"type":"string","format":"uri"},"sponsor":{"$ref":"#/components/schemas/NamedEntity"},"podcast":{"$ref":"#/components/schemas/TitledEntity"},"episode":{"$ref":"#/components/schemas/Episode"},"detectedAt":{"type":"string","format":"date-time"},"placement":{"type":"string","enum":["PRE_ROLL","MID_ROLL","POST_ROLL","UNKNOWN"]},"readType":{"type":"string","enum":["HOST_READ","ANNOUNCER_READ","MIXED","UNKNOWN"]},"adObjective":{"type":"string","enum":["DIRECT_RESPONSE","BRAND_AWARENESS","TUNE_IN","UNKNOWN"]},"estimatedCurrentPlacementValue":{"anyOf":[{"$ref":"#/components/schemas/EstimatedCurrentPlacementValue"},{"type":"null"}]},"durationSeconds":{"type":"number","minimum":0},"promoCode":{"type":"string"},"offer":{"type":"string"},"excerpt":{"type":"string","maxLength":321}}},"EstimatedCurrentPlacementValue":{"type":"object","required":["currency","low","mid","high","confidence","modelVersion","modelAsOf","basis","methodologyUrl","meaning"],"properties":{"currency":{"type":"string","const":"USD"},"low":{"type":"number","minimum":0},"mid":{"type":"number","minimum":0},"high":{"type":"number","minimum":0},"confidence":{"type":"string","const":"LOW"},"modelVersion":{"type":"string"},"modelAsOf":{"type":"string","pattern":"^[0-9]{4}-[0-9]{2}$"},"basis":{"$ref":"#/components/schemas/PlacementValueBasis"},"methodologyUrl":{"type":"string","format":"uri"},"meaning":{"type":"string","const":"Directional current value of a comparable single-episode placement; not reported advertiser spend or a historical invoice."}}},"PlacementValueBasis":{"type":"object","required":["popularityRank","popularityTier","audienceRange","cpmRange","placementMultiplier"],"properties":{"popularityRank":{"type":"number","minimum":1},"popularityTier":{"type":"string"},"audienceRange":{"$ref":"#/components/schemas/DirectionalRange"},"cpmRange":{"$ref":"#/components/schemas/DirectionalRange"},"placementMultiplier":{"type":"number","minimum":0}}},"DirectionalRange":{"type":"object","required":["low","mid","high"],"properties":{"low":{"type":"number","minimum":0},"mid":{"type":"number","minimum":0},"high":{"type":"number","minimum":0}}},"NamedEntity":{"type":"object","required":["name","slug","url"],"properties":{"name":{"type":"string"},"slug":{"type":"string"},"url":{"type":"string","format":"uri"}}},"TitledEntity":{"type":"object","required":["title","slug","url"],"properties":{"title":{"type":"string"},"slug":{"type":"string"},"url":{"type":"string","format":"uri"}}},"Episode":{"type":"object","required":["title"],"properties":{"title":{"type":"string"},"publishedAt":{"type":"string","format":"date-time"},"sourceUrl":{"type":"string","format":"uri"}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}}