{"openapi":"3.1.0","info":{"title":"Built On public API","version":"1.1.0","description":"Read-only data on real websites discovered on new domain extensions. No key needed; 60 requests/minute per visitor. Please credit \"Built On\" with a link."},"servers":[{"url":"https://builton.fyi/api/public/v1"}],"paths":{"/sites":{"get":{"operationId":"list-sites","summary":"List sites","description":"Returns published sites, best first. Combine filters freely. Follow next_cursor (or the Link header) to page through results.","tags":["Sites"],"parameters":[{"name":"q","in":"query","required":false,"description":"Search title, domain, description, brand and vertical","schema":{"type":"string"},"example":"coffee"},{"name":"extension","in":"query","required":false,"description":"Domain extension, e.g. studio","schema":{"type":"string"},"example":"studio"},{"name":"vertical","in":"query","required":false,"description":"Vertical name","schema":{"type":"string","enum":["Technology & Software","Business & Services","Shopping & Retail","Food & Drink","Health & Wellness","Travel & Hospitality","Arts & Design","Media & Entertainment","Education","Finance","Real Estate","Sports & Fitness","Nonprofit & Community","Events","Personal & Portfolio","Other"]}},{"name":"language","in":"query","required":false,"description":"ISO language code","schema":{"type":"string"},"example":"en"},{"name":"min_score","in":"query","required":false,"description":"Minimum Showcase Score 0-100","schema":{"type":"integer"},"example":"70"},{"name":"major_brand","in":"query","required":false,"description":"Only major brands","schema":{"type":"boolean"}},{"name":"featured","in":"query","required":false,"description":"Only editor-featured sites","schema":{"type":"boolean"}},{"name":"since","in":"query","required":false,"description":"Joined the showcase on or after this ISO date","schema":{"type":"string"}},{"name":"updated_since","in":"query","required":false,"description":"Changed on or after this ISO date","schema":{"type":"string"}},{"name":"sort","in":"query","required":false,"description":"score, newest (recently discovered), popular (traffic rank), updated (oldest change first — stable for syncing)","schema":{"type":"string","enum":["score","newest","popular","updated"],"default":"score"}},{"name":"limit","in":"query","required":false,"description":"Page size, 1-100","schema":{"type":"integer","default":"20"},"example":"5"},{"name":"cursor","in":"query","required":false,"description":"Opaque cursor from meta.next_cursor","schema":{"type":"string"}},{"name":"offset","in":"query","required":false,"description":"Items to skip (prefer cursor)","schema":{"type":"integer","default":"0"}},{"name":"fields","in":"query","required":false,"description":"Comma list of fields to return: domain, url, extension, title, description, vertical, language, screenshot_url, showcase_url, featured, origin, brand, score, dates","schema":{"type":"string"},"example":"domain,title,score"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","description":"Sites on this page","properties":{"domain":{"description":"string — Registered domain, e.g. crisp.chat"},"url":{"description":"string — Link to the live website"},"extension":{"description":"string — Domain extension without the dot"},"title":{"description":"string — Site title"},"description":{"description":"string | null — One-line summary written by our reviewer"},"vertical":{"description":"string — One of the fixed verticals"},"language":{"description":"string | null — ISO 639-1 language code"},"screenshot_url":{"description":"string | null — 1920x1200 PNG homepage screenshot, cached 24h, CORS-enabled"},"showcase_url":{"description":"string — The site's page on Built On"},"featured":{"description":"boolean — Hand-picked by our editors"},"origin":{"description":"\"new\" | \"established\" — Recently registered domain, or an older proven one"},"brand":{"type":"object","description":"Brand information","properties":{"is_major_brand":{"description":"boolean — A widely known organisation"},"name":{"description":"string | null — Brand or product name"}}},"score":{"type":"object","description":"Showcase Score","properties":{"value":{"description":"integer | null — 0-100 weighted score"},"band":{"description":"string — Exceptional (80+), Strong (60+), Promising (40+), Emerging, Unscored"},"breakdown":{"description":"object — brand, popularity, authority, marketing, content, design, age — each 0-100 or null when unknown"}}},"dates":{"type":"object","description":"ISO 8601 timestamps","properties":{"discovered_at":{"description":"string — When we first found the domain"},"published_at":{"description":"string | null — When it joined the showcase"},"registered_at":{"description":"string | null — Registration date from RDAP"},"last_confirmed_live_at":{"description":"string | null — Last time we confirmed the site was up"},"last_crawled_at":{"description":"string | null — Last full check (single-site endpoint only)"},"updated_at":{"description":"string — Last time any field changed"}}}}},"meta":{"type":"object","description":"Paging","properties":{"total":{"description":"integer — Matching sites"},"limit":{"description":"integer — Page size used"},"next_cursor":{"description":"string | null — Pass as cursor to get the next page"},"next":{"description":"string | null — Full URL of the next page (also in the Link header)"}}}}},"example":{"data":[{"domain":"crisp.chat","url":"https://crisp.chat","extension":"chat","title":"Crisp","description":"An AI-powered customer support platform combining shared inboxes, live chat and a knowledge base.","vertical":"Technology & Software","language":"en","screenshot_url":"https://builton.fyi/api/public/shots/crisp.chat","showcase_url":"https://builton.fyi/sites/crisp.chat","featured":false,"origin":"established","brand":{"is_major_brand":false,"name":"Crisp"},"score":{"value":88,"band":"Exceptional","breakdown":{"brand":95,"popularity":85,"authority":null,"marketing":80,"content":92,"design":90,"age":100}},"dates":{"discovered_at":"2026-10-23T00:00:00Z","published_at":"2026-10-23T12:04:00Z","registered_at":"2015-03-02T00:00:00Z","last_confirmed_live_at":"2026-10-30T08:00:00Z","last_crawled_at":null,"updated_at":"2026-10-30T08:00:00Z"}}],"meta":{"total":1240,"limit":1,"next_cursor":"eyJvIjoxfQ","next":"https://builton.fyi/api/public/v1/sites?limit=1&cursor=eyJvIjoxfQ"}}}}},"304":{"description":"Not modified (If-None-Match matched)"},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/sites/{domain}":{"get":{"operationId":"get-site","summary":"Get a site","description":"Returns a single published site, including when it was last crawled. 404 if the site isn't showcased.","tags":["Sites"],"parameters":[{"name":"domain","in":"path","required":true,"description":"The domain","schema":{"type":"string"},"example":"crisp.chat"},{"name":"fields","in":"query","required":false,"description":"Comma list of fields to return: domain, url, extension, title, description, vertical, language, screenshot_url, showcase_url, featured, origin, brand, score, dates","schema":{"type":"string"},"example":"domain,title,score"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","description":"The site","properties":{"domain":{"description":"string — Registered domain, e.g. crisp.chat"},"url":{"description":"string — Link to the live website"},"extension":{"description":"string — Domain extension without the dot"},"title":{"description":"string — Site title"},"description":{"description":"string | null — One-line summary written by our reviewer"},"vertical":{"description":"string — One of the fixed verticals"},"language":{"description":"string | null — ISO 639-1 language code"},"screenshot_url":{"description":"string | null — 1920x1200 PNG homepage screenshot, cached 24h, CORS-enabled"},"showcase_url":{"description":"string — The site's page on Built On"},"featured":{"description":"boolean — Hand-picked by our editors"},"origin":{"description":"\"new\" | \"established\" — Recently registered domain, or an older proven one"},"brand":{"type":"object","description":"Brand information","properties":{"is_major_brand":{"description":"boolean — A widely known organisation"},"name":{"description":"string | null — Brand or product name"}}},"score":{"type":"object","description":"Showcase Score","properties":{"value":{"description":"integer | null — 0-100 weighted score"},"band":{"description":"string — Exceptional (80+), Strong (60+), Promising (40+), Emerging, Unscored"},"breakdown":{"description":"object — brand, popularity, authority, marketing, content, design, age — each 0-100 or null when unknown"}}},"dates":{"type":"object","description":"ISO 8601 timestamps","properties":{"discovered_at":{"description":"string — When we first found the domain"},"published_at":{"description":"string | null — When it joined the showcase"},"registered_at":{"description":"string | null — Registration date from RDAP"},"last_confirmed_live_at":{"description":"string | null — Last time we confirmed the site was up"},"last_crawled_at":{"description":"string | null — Last full check (single-site endpoint only)"},"updated_at":{"description":"string — Last time any field changed"}}}}}}},"example":{"data":{"domain":"crisp.chat","url":"https://crisp.chat","extension":"chat","title":"Crisp","description":"An AI-powered customer support platform combining shared inboxes, live chat and a knowledge base.","vertical":"Technology & Software","language":"en","screenshot_url":"https://builton.fyi/api/public/shots/crisp.chat","showcase_url":"https://builton.fyi/sites/crisp.chat","featured":false,"origin":"established","brand":{"is_major_brand":false,"name":"Crisp"},"score":{"value":88,"band":"Exceptional","breakdown":{"brand":95,"popularity":85,"authority":null,"marketing":80,"content":92,"design":90,"age":100}},"dates":{"discovered_at":"2026-10-23T00:00:00Z","published_at":"2026-10-23T12:04:00Z","registered_at":"2015-03-02T00:00:00Z","last_confirmed_live_at":"2026-10-30T08:00:00Z","last_crawled_at":"2026-10-29T22:10:00Z","updated_at":"2026-10-30T08:00:00Z"}}}}}},"304":{"description":"Not modified (If-None-Match matched)"},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/highlights":{"get":{"operationId":"highlights","summary":"Highlights","description":"Site of the day, sites discovered this week, featured sites and major brands — everything needed to rebuild the home page sections.","tags":["Sites"],"parameters":[{"name":"language","in":"query","required":false,"description":"Language for site of the day and this week (all for every language)","schema":{"type":"string","default":"en"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","description":"Sets","properties":{"site_of_the_day":{"description":"Site | null — Rotates daily among sites scoring 80+"},"discovered_this_week":{"description":"Site[] — Best of the last 7 days"},"featured":{"description":"Site[] — Editor picks"},"major_brands":{"description":"Site[] — Top major brands by score"}}}}},"example":{"data":{"site_of_the_day":{"domain":"crisp.chat","url":"https://crisp.chat","extension":"chat","title":"Crisp","description":"An AI-powered customer support platform combining shared inboxes, live chat and a knowledge base.","vertical":"Technology & Software","language":"en","screenshot_url":"https://builton.fyi/api/public/shots/crisp.chat","showcase_url":"https://builton.fyi/sites/crisp.chat","featured":false,"origin":"established","brand":{"is_major_brand":false,"name":"Crisp"},"score":{"value":88,"band":"Exceptional","breakdown":{"brand":95,"popularity":85,"authority":null,"marketing":80,"content":92,"design":90,"age":100}},"dates":{"discovered_at":"2026-10-23T00:00:00Z","published_at":"2026-10-23T12:04:00Z","registered_at":"2015-03-02T00:00:00Z","last_confirmed_live_at":"2026-10-30T08:00:00Z","last_crawled_at":null,"updated_at":"2026-10-30T08:00:00Z"}},"discovered_this_week":[{"domain":"crisp.chat","url":"https://crisp.chat","extension":"chat","title":"Crisp","description":"An AI-powered customer support platform combining shared inboxes, live chat and a knowledge base.","vertical":"Technology & Software","language":"en","screenshot_url":"https://builton.fyi/api/public/shots/crisp.chat","showcase_url":"https://builton.fyi/sites/crisp.chat","featured":false,"origin":"established","brand":{"is_major_brand":false,"name":"Crisp"},"score":{"value":88,"band":"Exceptional","breakdown":{"brand":95,"popularity":85,"authority":null,"marketing":80,"content":92,"design":90,"age":100}},"dates":{"discovered_at":"2026-10-23T00:00:00Z","published_at":"2026-10-23T12:04:00Z","registered_at":"2015-03-02T00:00:00Z","last_confirmed_live_at":"2026-10-30T08:00:00Z","last_crawled_at":null,"updated_at":"2026-10-30T08:00:00Z"}}],"featured":[],"major_brands":[]}}}}},"304":{"description":"Not modified (If-None-Match matched)"},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/extensions":{"get":{"operationId":"list-extensions","summary":"List extensions","description":"Every extension with at least one showcased site, largest first.","tags":["Catalog"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"object[] — extension, count"},"meta.total_sites":{"description":"integer — All showcased sites"}}},"example":{"data":[{"extension":"studio","count":212},{"extension":"chat","count":98}],"meta":{"total_sites":1240}}}}},"304":{"description":"Not modified (If-None-Match matched)"},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/verticals":{"get":{"operationId":"list-verticals","summary":"List verticals","description":"Every vertical with its URL slug and number of showcased sites.","tags":["Catalog"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"object[] — vertical, slug, count"},"meta.total_sites":{"description":"integer — All showcased sites"}}},"example":{"data":[{"vertical":"Technology & Software","slug":"technology-software","count":340}],"meta":{"total_sites":1240}}}}},"304":{"description":"Not modified (If-None-Match matched)"},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/summary":{"get":{"operationId":"summary","summary":"Summary","description":"Totals, weekly discoveries, and breakdowns by extension, vertical, language and origin — the data behind the trends page.","tags":["Catalog"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"description":"object — total, weeks [week, count], extensions, verticals, languages, origins"}}},"example":{"data":{"total":1240,"weeks":[["2026-10-19",210]],"extensions":[["studio",212]],"verticals":[["Technology & Software",340]],"languages":[["en",900]],"origins":[["established",700]]}}}}},"304":{"description":"Not modified (If-None-Match matched)"},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/changes":{"get":{"operationId":"list-changes","summary":"List changes","description":"Every site added, updated or removed since a date, oldest first. Store the last next_cursor and poll it to stay current; delete sites marked removed.","tags":["Sync"],"parameters":[{"name":"since","in":"query","required":true,"description":"ISO date to start from","schema":{"type":"string"},"example":"2026-10-29T00:00:00Z"},{"name":"limit","in":"query","required":false,"description":"1-100","schema":{"type":"integer","default":"100"}},{"name":"cursor","in":"query","required":false,"description":"Cursor from the previous page","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","description":"Changes","properties":{"domain":{"description":"string — The domain"},"change":{"description":"\"added\" | \"updated\" | \"removed\" — What happened"},"updated_at":{"description":"string — When"}}},"meta":{"type":"object","description":"Paging","properties":{"total":{"description":"integer — Matching sites"},"limit":{"description":"integer — Page size used"},"next_cursor":{"description":"string | null — Pass as cursor to get the next page"},"next":{"description":"string | null — Full URL of the next page (also in the Link header)"}}}}},"example":{"data":[{"domain":"crisp.chat","change":"updated","updated_at":"2026-10-30T08:00:00Z"}],"meta":{"limit":100,"next_cursor":null,"next":null}}}}},"304":{"description":"Not modified (If-None-Match matched)"},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/health":{"get":{"operationId":"health","summary":"Health","description":"Returns ok and when showcase data last changed. Not rate limited for uptime monitors beyond fair use.","tags":["Status"],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"description":"string — ok"},"last_data_update":{"description":"string | null — Most recent site change"},"version":{"description":"string — API version"}}},"example":{"status":"ok","version":"1.1.0","last_data_update":"2026-10-30T08:00:00Z"}}}},"304":{"description":"Not modified (If-None-Match matched)"},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"status":{"type":"integer"}}}}}}}}