{"openapi":"3.1.0","info":{"title":"Product Billboards public API","version":"1.0.0","summary":"Read-only access to the billboard catalog, its verified traffic and its founder AMA threads.","description":"Public, unauthenticated, read-only.\n\nRate limit: 60 requests per minute per IP, bursting to 120. Over the limit the API returns 429 with a Retry-After header. No key, no quota, no sign-up.\n\nAuth guide: https://productbillboards.com/auth.md\nAgent skills: https://productbillboards.com/.well-known/agent-skills/index.json\nMCP server card: https://productbillboards.com/.well-known/mcp/server-card.json","contact":{"name":"Product Billboards support","email":"hey@productbillboards.com","url":"https://productbillboards.com/contact"},"license":{"name":"Content licence","url":"https://productbillboards.com/terms"},"termsOfService":"https://productbillboards.com/terms"},"servers":[{"url":"https://productbillboards.com","description":"Production"}],"security":[],"tags":[{"name":"catalog","description":"Billboards, categories and their verified engagement."},{"name":"v1","description":"The versioned read API. One listing shape across every endpoint."}],"paths":{"/api/feed":{"get":{"operationId":"listBillboards","summary":"List billboards","description":"List billboards from the Product Billboards feed, newest ranking first. Each entry carries the product name, tagline, website, category, country, 7-day verified visitor count and founder AMA reply rate. Use it to answer \"what products are on Product Billboards\", to browse a category, or to find products from one country. Returns one page of up to 24 billboards; pass `page` to go further.","tags":["catalog"],"parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":200,"default":0},"description":"Zero-based page of results."},{"name":"mode","in":"query","required":false,"schema":{"type":"string","enum":["ranked","random"],"default":"ranked"},"description":"Organic daily ranking, or a shuffle."},{"name":"categories","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated category slugs; matches any."},{"name":"country","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":2},"description":"ISO 3166-1 alpha-2 country code."}],"responses":{"200":{"description":"One page of billboards.","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"listing":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"tagline":{"type":"string","nullable":true},"website_url":{"type":"string","format":"uri"},"country_code":{"type":"string","nullable":true},"category":{"type":"object","nullable":true,"properties":{"slug":{"type":"string"},"name":{"type":"string"}}}}},"score":{"type":"object","nullable":true,"description":"Verified engagement over a rolling 7-day window.","properties":{"unique_visitors_7d":{"type":"integer"},"avg_dwell_seconds":{"type":"number"},"reply_rate":{"type":"number","description":"Share of AMA questions the founder has answered, 0-1."},"weighted_score":{"type":"number"}}},"sponsored":{"type":"boolean","description":"True for the single paid 24-hour slot in the feed - position #4 on the home feed, #3 in a category feed. Every other position is organic and cannot be bought."},"rank":{"type":"integer","nullable":true}}}}}}}}},"406":{"description":"The Accept header asks for something this API cannot produce."},"429":{"description":"Rate limited. Retry after the interval in the Retry-After header."}},"x-payment-info":{"pricing":"free","price":{"amount":"0","currency":"USD","unit":"request"},"paymentRequired":false,"notes":"Public read endpoint. No payment, key or account. Paid products on this site are listings and sponsor slots, bought by people at /pricing."}}},"/api/categories":{"get":{"operationId":"listCategories","summary":"List categories","description":"List every product category on Product Billboards with its slug and display name. Call it before list_billboards when you need a valid `categories` value.","tags":["catalog"],"responses":{"200":{"description":"Every category, with slug and display name.","content":{"application/json":{"schema":{"type":"object","properties":{"categories":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"}}}}}}}}}},"x-payment-info":{"pricing":"free","price":{"amount":"0","currency":"USD","unit":"request"},"paymentRequired":false}}},"/listing/{id}/llms.txt":{"get":{"operationId":"getBillboard","summary":"Get one billboard as Markdown","description":"Fetch one billboard in full as Markdown: product details, verified 7-day traffic, the founder AMA thread with its answers, and the product release story timeline. Needs the billboard id, which list_billboards returns. Use it when a question is about one specific product rather than the catalog.","tags":["catalog"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Billboard id from listBillboards."}],"responses":{"200":{"description":"The billboard, its AMA thread and its release stories.","content":{"text/plain":{"schema":{"type":"string"}}}},"404":{"description":"No billboard with that id."}},"x-payment-info":{"pricing":"free","price":{"amount":"0","currency":"USD","unit":"request"},"paymentRequired":false}}},"/v1/listings":{"get":{"operationId":"v1ListListings","summary":"List billboards (v1)","description":"The ranked board. Organic order is measured engagement; sponsored entries are flagged and never displace an earned position.","tags":["v1"],"parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":200,"default":0}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"category","in":"query","required":false,"schema":{"type":"string"},"description":"Category slug."},{"name":"week","in":"query","required":false,"schema":{"type":"string","pattern":"^\\d{4}-W\\d{2}$"},"description":"ISO week of submission, e.g. 2026-W37."},{"name":"country","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":2}}],"responses":{"200":{"description":"One page of billboards.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingPage"}}}},"429":{"description":"Rate limit exceeded."}}}},"/v1/listings/{id}":{"get":{"operationId":"v1GetListing","summary":"Get one billboard (v1)","tags":["v1"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The billboard.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Listing"}}}}}},"400":{"description":"Not a listing id."},"404":{"description":"No billboard with that id."}}}},"/v1/leaderboard":{"get":{"operationId":"v1GetLeaderboard","summary":"Top billboards by measured engagement","description":"Organic only. Sponsored placements are excluded, and spend never affects rank.","tags":["v1"],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":10}},{"name":"week","in":"query","required":false,"schema":{"type":"string"},"description":"An ISO week key, or \"current\" for the open week."}],"responses":{"200":{"description":"The leaderboard.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingPage"}}}}}}},"/v1/categories":{"get":{"operationId":"v1ListCategories","summary":"List categories","tags":["v1"],"responses":{"200":{"description":"Every category."}}}},"/v1/search":{"get":{"operationId":"v1Search","summary":"Search billboards","description":"Substring match over name, tagline and category. Results keep the board's ranking rather than a separate relevance score.","tags":["v1"],"parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":2,"maxLength":100}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":25}}],"responses":{"200":{"description":"Matching billboards.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingPage"}}}},"400":{"description":"Query too short."}}}},"/api/ai":{"get":{"operationId":"getAiSnapshot","summary":"Bounded snapshot for an assistant","description":"One self-describing response: what the site is, how ranking works, this week's board and recent top performers. Intended to be read in a single call rather than paged through.","tags":["v1"],"responses":{"200":{"description":"The snapshot."}}}}},"components":{"schemas":{"Listing":{"type":"object","required":["id","name","url","engagement"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"tagline":{"type":["string","null"]},"url":{"type":"string","format":"uri","description":"The founder's own site."},"category":{"type":["string","null"]},"country":{"type":["string","null"],"description":"ISO 3166-1 alpha-2."},"listedAt":{"type":["string","null"],"format":"date-time"},"week":{"type":["string","null"],"description":"ISO week of submission, e.g. 2026-W37."},"rank":{"type":["integer","null"]},"sponsored":{"type":"boolean","description":"Paid placement. Never affects organic rank."},"links":{"type":"object","properties":{"self":{"type":"string","format":"uri"},"web":{"type":"string","format":"uri"},"markdown":{"type":"string","format":"uri"}}},"engagement":{"oneOf":[{"type":"object","required":["status","minimumHitsForPublicFigures"],"properties":{"status":{"const":"collecting"},"minimumHitsForPublicFigures":{"type":"integer"}}},{"type":"object","required":["status","uniqueVisitors7d","averageDwellSeconds","replyRate"],"properties":{"status":{"const":"published"},"uniqueVisitors7d":{"type":"integer"},"averageDwellSeconds":{"type":"number"},"replyRate":{"type":"number"}}}]}}},"ListingPage":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Listing"}},"page":{"type":"integer"},"limit":{"type":"integer"}}}}},"x-rate-limit":{"requestsPerMinute":60,"burst":120,"statement":"60 requests per minute per IP, bursting to 120. Over the limit the API returns 429 with a Retry-After header. No key, no quota, no sign-up."}}