{"openapi":"3.1.0","info":{"title":"NextAds Agent API","version":"1.0.0","description":"NextAds is Hong Kong's omnichannel advertising media platform with public reference pricing. This API lets AI agents discover inventory and submit booking intents on behalf of brands. No authentication required; rate-limited per IP.","contact":{"email":"hello@nextads.io","url":"https://nextads.io/contact"},"termsOfService":"https://nextads.io/terms"},"servers":[{"url":"https://nextads.io"}],"paths":{"/api/agents/media":{"get":{"summary":"List advertising media placements","description":"Returns a JSON catalog of Hong Kong outdoor, transit, digital-screen, and online ad placements. Filterable by category, location, and reference budget.","parameters":[{"in":"query","name":"category","schema":{"type":"string","enum":["outdoor","transit","digital-screen","online"]},"description":"Filter by media category"},{"in":"query","name":"location","schema":{"type":"string"},"description":"Filter by location — accepts location slug (e.g. 'central') or Chinese title (e.g. '中環')"},{"in":"query","name":"minBudget","schema":{"type":"integer","minimum":0},"description":"Minimum reference price in HKD"},{"in":"query","name":"maxBudget","schema":{"type":"integer","minimum":0},"description":"Maximum reference price in HKD"},{"in":"query","name":"limit","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}],"responses":{"200":{"description":"Successful catalog response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MediaListResponse"}}}}}}},"/api/agents/inquire":{"post":{"summary":"Submit a booking intent on behalf of a brand","description":"Creates a lightweight enquiry record. A NextAds account manager will follow up via email within 2 business hours. This endpoint does NOT auto-confirm bookings.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InquiryRequest"}}}},"responses":{"201":{"description":"Enquiry accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InquiryResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}}}}},"/llms.txt":{"get":{"summary":"Human + AI crawler summary of NextAds","description":"Hand-curated summary following the llms.txt convention. Contains company description, differentiators, booking flow, SLAs, service area, industries served, and the full media catalog.","responses":{"200":{"description":"text/plain summary"}}}}},"components":{"schemas":{"MediaListResponse":{"type":"object","properties":{"meta":{"type":"object","properties":{"generatedAt":{"type":"string","format":"date-time"},"source":{"type":"string"},"siteUrl":{"type":"string","format":"uri"},"docs":{"type":"string","format":"uri"},"termsOfUse":{"type":"string","format":"uri"},"note":{"type":"string"}}},"count":{"type":"integer"},"items":{"type":"array","items":{"$ref":"#/components/schemas/MediaItem"}}}},"MediaItem":{"type":"object","properties":{"slug":{"type":"string"},"title":{"type":"object","properties":{"zh":{"type":"string"},"en":{"type":"string","nullable":true}}},"category":{"type":"object","nullable":true,"properties":{"id":{"type":"string"},"title":{"type":"object"}}},"locations":{"type":"array","items":{"type":"object"}},"address":{"type":"string","nullable":true},"priceReference":{"type":"object","nullable":true,"properties":{"currency":{"type":"string","example":"HKD"},"low":{"type":"number"},"high":{"type":"number"},"unit":{"type":"string","example":"/month"}}},"url":{"type":"string","format":"uri"},"bookingUrl":{"type":"string","format":"uri"}}},"InquiryRequest":{"type":"object","required":["brandName","contactName","contactEmail","message"],"properties":{"mediaSlug":{"type":"string"},"category":{"type":"string","enum":["outdoor","transit","digital-screen","online"]},"budgetHKD":{"type":"number"},"startDate":{"type":"string","format":"date-time"},"endDate":{"type":"string","format":"date-time"},"brandName":{"type":"string"},"contactName":{"type":"string"},"contactEmail":{"type":"string","format":"email"},"contactPhone":{"type":"string"},"message":{"type":"string","minLength":10},"agentContext":{"type":"string","description":"Describe the AI agent calling this endpoint (name + version). Used for transparency & abuse detection."}}},"InquiryResponse":{"type":"object","properties":{"referenceNo":{"type":"string","example":"AGT-L1A2B3-XYZ12"},"status":{"type":"string","example":"received"},"nextStep":{"type":"string"},"contact":{"type":"object","properties":{"whatsapp":{"type":"string"},"email":{"type":"string"}}},"linkToBrowse":{"type":"string","format":"uri"}}},"ValidationError":{"type":"object","properties":{"error":{"type":"string"},"issues":{"type":"array"},"docs":{"type":"string"}}}}}}