{"openapi":"3.1.0","info":{"title":"Pyyan API","version":"1.0.0","summary":"A free, public, read only API over the AI index at pyyan.com.","description":"No key and no signup. Every response is JSON in a { data } envelope, lists add { meta, links }. Sorting is whitelisted per resource and an unknown sort field is a 400 rather than being quietly ignored, so a caller always gets the order they asked for or an error saying why not. Private data is not modelled here at all: subscribers and short links have no route.","contact":{"name":"Pyyan","url":"https://pyyan.com"},"license":{"name":"Free to use, attribution appreciated","url":"https://pyyan.com/api"}},"servers":[{"url":"https://pyyan.com","description":"Production"}],"tags":[{"name":"news"},{"name":"videos"},{"name":"entities"},{"name":"categories"},{"name":"people"},{"name":"makers"},{"name":"changes"},{"name":"trending"},{"name":"boxes"},{"name":"meta"}],"paths":{"/api/v1":{"get":{"tags":["meta"],"operationId":"discover","summary":"Every resource, with live row counts and the conventions they share.","responses":{"200":{"description":"Discovery document."}}}},"/api/v1/news":{"get":{"tags":["news"],"operationId":"listNews","summary":"Dated AI news, newest first.","parameters":[{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"sort","in":"query","description":"One of: date, addedAt, headline, category, weight. Prefix with - for descending.","schema":{"type":"string","enum":["date","addedAt","headline","category","weight","-date","-addedAt","-headline","-category","-weight"]}},{"name":"fields","in":"query","description":"Comma separated list of keys to return.","schema":{"type":"string"}},{"name":"q","in":"query","description":"Free text search.","schema":{"type":"string"}},{"name":"category","in":"query","description":"Models, Law, Money, Policy, Safety, Silicon, Benchmarks, Open weights.","schema":{"type":"string"}},{"name":"org","in":"query","description":"An organisation named in the story, e.g. OpenAI.","schema":{"type":"string"}},{"name":"sourcing","in":"query","description":"primary or corroborated.","schema":{"type":"string"}},{"name":"storified","in":"query","description":"Only stories that carry the five movement long form.","schema":{"type":"boolean"}},{"name":"from","in":"query","description":"ISO date, inclusive lower bound.","schema":{"type":"string"}},{"name":"to","in":"query","description":"ISO date, inclusive upper bound.","schema":{"type":"string"}}],"responses":{"200":{"description":"A page of results.","content":{"application/json":{"schema":{"type":"object","required":["data","meta","links"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/NewsItem"}},"meta":{"$ref":"#/components/schemas/ListMeta"},"links":{"$ref":"#/components/schemas/ListLinks"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"}}}},"/api/v1/news/{slug}":{"get":{"tags":["news"],"operationId":"getNews","summary":"One story.","parameters":[{"name":"slug","in":"path","required":true,"description":"The story slug.","schema":{"type":"string"}}],"responses":{"200":{"description":"One record.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/NewsItem"}}}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/videos":{"get":{"tags":["videos"],"operationId":"listVideos","summary":"Curated talks and interviews, newest first.","parameters":[{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"sort","in":"query","description":"One of: published, order, title, channel, topic. Prefix with - for descending.","schema":{"type":"string","enum":["published","order","title","channel","topic","-published","-order","-title","-channel","-topic"]}},{"name":"fields","in":"query","description":"Comma separated list of keys to return.","schema":{"type":"string"}},{"name":"q","in":"query","description":"Free text search.","schema":{"type":"string"}},{"name":"topic","in":"query","description":"Research, People, Foundations, Safety, Silicon, Models, Policy, Agentic, Benchmarks.","schema":{"type":"string"}},{"name":"channel","in":"query","description":"Exact channel name.","schema":{"type":"string"}},{"name":"person","in":"query","description":"A slug from /api/v1/people, to get what they appear in.","schema":{"type":"string"}}],"responses":{"200":{"description":"A page of results.","content":{"application/json":{"schema":{"type":"object","required":["data","meta","links"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Video"}},"meta":{"$ref":"#/components/schemas/ListMeta"},"links":{"$ref":"#/components/schemas/ListLinks"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"}}}},"/api/v1/videos/{videoId}":{"get":{"tags":["videos"],"operationId":"getVideo","summary":"One video.","parameters":[{"name":"videoId","in":"path","required":true,"description":"The YouTube video id.","schema":{"type":"string"}}],"responses":{"200":{"description":"One record.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Video"}}}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/entities":{"get":{"tags":["entities"],"operationId":"listEntities","summary":"Models, chips, clouds and tools. Every spec carries a source and a date.","parameters":[{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"sort","in":"query","description":"One of: rank, name, maker, verifiedAt, categorySlug. Prefix with - for descending.","schema":{"type":"string","enum":["rank","name","maker","verifiedAt","categorySlug","-rank","-name","-maker","-verifiedAt","-categorySlug"]}},{"name":"fields","in":"query","description":"Comma separated list of keys to return.","schema":{"type":"string"}},{"name":"q","in":"query","description":"Free text search.","schema":{"type":"string"}},{"name":"category","in":"query","description":"A slug from /api/v1/categories, e.g. language-models.","schema":{"type":"string"}},{"name":"maker","in":"query","description":"Exact maker name, e.g. Anthropic.","schema":{"type":"string"}},{"name":"status","in":"query","description":"current, deprecated, and so on.","schema":{"type":"string"}},{"name":"new","in":"query","description":"Only rows from the most recent intake.","schema":{"type":"boolean"}}],"responses":{"200":{"description":"A page of results.","content":{"application/json":{"schema":{"type":"object","required":["data","meta","links"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Entity"}},"meta":{"$ref":"#/components/schemas/ListMeta"},"links":{"$ref":"#/components/schemas/ListLinks"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"}}}},"/api/v1/entities/{slug}":{"get":{"tags":["entities"],"operationId":"getEntity","summary":"One entity.","parameters":[{"name":"slug","in":"path","required":true,"description":"The entity slug.","schema":{"type":"string"}}],"responses":{"200":{"description":"One record.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Entity"}}}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/categories":{"get":{"tags":["categories"],"operationId":"listCategories","summary":"The categories entities are filed under.","parameters":[{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"sort","in":"query","description":"One of: order, name, slug, group. Prefix with - for descending.","schema":{"type":"string","enum":["order","name","slug","group","-order","-name","-slug","-group"]}},{"name":"fields","in":"query","description":"Comma separated list of keys to return.","schema":{"type":"string"}},{"name":"q","in":"query","description":"Free text search.","schema":{"type":"string"}},{"name":"group","in":"query","description":"The menu group.","schema":{"type":"string"}}],"responses":{"200":{"description":"A page of results.","content":{"application/json":{"schema":{"type":"object","required":["data","meta","links"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Category"}},"meta":{"$ref":"#/components/schemas/ListMeta"},"links":{"$ref":"#/components/schemas/ListLinks"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"}}}},"/api/v1/categories/{slug}":{"get":{"tags":["categories"],"operationId":"getCategory","summary":"One category.","parameters":[{"name":"slug","in":"path","required":true,"description":"The category slug.","schema":{"type":"string"}}],"responses":{"200":{"description":"One record.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Category"}}}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/people":{"get":{"tags":["people"],"operationId":"listPeople","summary":"The people of AI, by tier.","parameters":[{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"sort","in":"query","description":"One of: order, name, tier, country. Prefix with - for descending.","schema":{"type":"string","enum":["order","name","tier","country","-order","-name","-tier","-country"]}},{"name":"fields","in":"query","description":"Comma separated list of keys to return.","schema":{"type":"string"}},{"name":"q","in":"query","description":"Free text search.","schema":{"type":"string"}},{"name":"tier","in":"query","description":"Founders, Research, Safety, Pioneers, Thinkers, Educators, Journalists, Fiction.","schema":{"type":"string"}},{"name":"country","in":"query","description":"Country name.","schema":{"type":"string"}}],"responses":{"200":{"description":"A page of results.","content":{"application/json":{"schema":{"type":"object","required":["data","meta","links"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Person"}},"meta":{"$ref":"#/components/schemas/ListMeta"},"links":{"$ref":"#/components/schemas/ListLinks"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"}}}},"/api/v1/people/{slug}":{"get":{"tags":["people"],"operationId":"getPerson","summary":"One person.","parameters":[{"name":"slug","in":"path","required":true,"description":"The person slug.","schema":{"type":"string"}}],"responses":{"200":{"description":"One record.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Person"}}}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/makers":{"get":{"tags":["makers"],"operationId":"listMakers","summary":"Organisations that make what the index tracks.","parameters":[{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"sort","in":"query","description":"One of: name, slug. Prefix with - for descending.","schema":{"type":"string","enum":["name","slug","-name","-slug"]}},{"name":"fields","in":"query","description":"Comma separated list of keys to return.","schema":{"type":"string"}},{"name":"q","in":"query","description":"Free text search.","schema":{"type":"string"}}],"responses":{"200":{"description":"A page of results.","content":{"application/json":{"schema":{"type":"object","required":["data","meta","links"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Maker"}},"meta":{"$ref":"#/components/schemas/ListMeta"},"links":{"$ref":"#/components/schemas/ListLinks"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"}}}},"/api/v1/changes":{"get":{"tags":["changes"],"operationId":"listChanges","summary":"The index's own changelog.","parameters":[{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"sort","in":"query","description":"One of: date, entity, maker, tag. Prefix with - for descending.","schema":{"type":"string","enum":["date","entity","maker","tag","-date","-entity","-maker","-tag"]}},{"name":"fields","in":"query","description":"Comma separated list of keys to return.","schema":{"type":"string"}},{"name":"q","in":"query","description":"Free text search.","schema":{"type":"string"}},{"name":"tag","in":"query","description":"The kind of change.","schema":{"type":"string"}}],"responses":{"200":{"description":"A page of results.","content":{"application/json":{"schema":{"type":"object","required":["data","meta","links"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Change"}},"meta":{"$ref":"#/components/schemas/ListMeta"},"links":{"$ref":"#/components/schemas/ListLinks"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"}}}},"/api/v1/trending/{source}":{"get":{"tags":["trending"],"operationId":"listTrending","summary":"What is trending on one of four sources.","description":"Each source ranks on its own metric and the numbers are not comparable across them. The X-Ranking-Basis response header names the metric.","parameters":[{"name":"source","in":"path","required":true,"schema":{"type":"string","enum":["huggingface","github","reddit","hacker-news"]}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"sort","in":"query","description":"One of: rank, name, title, stars, points, downloads, likes. Prefix with - for descending.","schema":{"type":"string","enum":["rank","name","title","stars","points","downloads","likes","-rank","-name","-title","-stars","-points","-downloads","-likes"]}},{"name":"fields","in":"query","description":"Comma separated list of keys to return.","schema":{"type":"string"}}],"responses":{"200":{"description":"A page of results.","content":{"application/json":{"schema":{"type":"object","required":["data","meta","links"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TrendingItem"}},"meta":{"$ref":"#/components/schemas/ListMeta"},"links":{"$ref":"#/components/schemas/ListLinks"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/v1/boxes":{"get":{"tags":["boxes"],"operationId":"listBoxes","summary":"Long form articles. Files rather than rows, so no paging.","responses":{"200":{"description":"Every visible box."}}}},"/api/v1/boxes/{name}":{"get":{"tags":["boxes"],"operationId":"getBox","summary":"One box.","parameters":[{"name":"name","in":"path","required":true,"description":"The box folder name.","schema":{"type":"string"}}],"responses":{"200":{"description":"One record.","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/Box"}}}}}},"404":{"$ref":"#/components/responses/NotFound"}}}}},"components":{"responses":{"BadRequest":{"description":"A parameter was wrong. The body names it and lists what is allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No record with that identifier.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["status","code","message"],"properties":{"status":{"type":"integer","examples":[400]},"code":{"type":"string","description":"Stable machine readable code.","examples":["bad_sort"]},"message":{"type":"string"},"sortable":{"type":"array","items":{"type":"string"},"description":"Present on bad_sort."}}}}},"ListMeta":{"type":"object","required":["total","count","page","limit","pages"],"properties":{"total":{"type":"integer","description":"Matching the filter, not the page."},"count":{"type":"integer","description":"In this page."},"page":{"type":"integer"},"limit":{"type":"integer"},"pages":{"type":"integer"}}},"ListLinks":{"type":"object","required":["self","next","prev"],"properties":{"self":{"type":"string","format":"uri"},"next":{"type":["string","null"],"format":"uri"},"prev":{"type":["string","null"],"format":"uri"}}},"SpecValue":{"type":"object","description":"A single specification, with where it came from and how far to trust it.","properties":{"value":{"type":["string","number","boolean"]},"source":{"type":["string","null"],"format":"uri"},"asOf":{"type":"string","description":"ISO date the value was checked."},"confidence":{"type":"string","enum":["high","medium","low"]}}},"NewsItem":{"type":"object","properties":{"slug":{"type":"string"},"date":{"type":"string"},"headline":{"type":"string"},"summary":{"type":"string"},"category":{"type":"string"},"orgs":{"type":"array","items":{"type":"string"}},"figure":{"type":"object","properties":{"value":{"type":"string"},"label":{"type":"string"}}},"sourceName":{"type":"string"},"sourceUrl":{"type":"string","format":"uri"},"source2Name":{"type":"string"},"source2Url":{"type":"string","format":"uri"},"sourcing":{"type":"string","enum":["primary","corroborated"]},"weight":{"type":"integer"},"accent":{"type":"string"},"addedAt":{"type":"string"},"story":{"type":"object","description":"The five movements, present only where a story earned the long form.","properties":{"hook":{"type":"string"},"happened":{"type":"string"},"different":{"type":"string"},"pull":{"type":"string"},"meaning":{"type":"string"},"lineage":{"type":"array","items":{"type":"object","properties":{"when":{"type":"string"},"what":{"type":"string"}}}},"chart":{"type":"object"},"video":{"type":"object"}}}}},"Video":{"type":"object","properties":{"videoId":{"type":"string"},"title":{"type":"string"},"channel":{"type":"string"},"published":{"type":"string"},"duration":{"type":"string"},"topic":{"type":"string"},"why":{"type":"string","description":"Why this one is on the list."},"people":{"type":"array","items":{"type":"string"},"description":"Slugs from /people."},"order":{"type":"integer"},"addedAt":{"type":"string"}}},"Entity":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"maker":{"type":"string"},"categorySlug":{"type":"string"},"rank":{"type":"integer"},"status":{"type":"string"},"tagline":{"type":"string"},"bestFor":{"type":"string"},"bullets":{"type":"array","items":{"type":"string"}},"headline":{"type":"object","properties":{"value":{"type":"string"},"label":{"type":"string"}}},"link":{"type":"string","format":"uri"},"specs":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/SpecValue"}},"verifiedAt":{"type":"string"},"isNew":{"type":"boolean"}}},"Category":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"blurb":{"type":"string"},"group":{"type":"string"},"order":{"type":"integer"},"rankBasis":{"type":"string"},"specFields":{"type":"array","items":{"type":"string"}}}},"Person":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"tier":{"type":"string"},"country":{"type":"string"},"headline":{"type":"string"},"bio":{"type":"string"},"born":{"type":["string","number"]},"died":{"type":["string","number"]},"tags":{"type":"array","items":{"type":"string"}},"photo":{"type":"string"},"wikipedia":{"type":"string","format":"uri"}}},"Maker":{"type":"object","properties":{"name":{"type":"string"},"slug":{"type":"string"},"url":{"type":"string","format":"uri"}}},"Change":{"type":"object","properties":{"date":{"type":"string"},"entity":{"type":"string"},"maker":{"type":"string"},"note":{"type":"string"},"tag":{"type":"string"}}},"TrendingItem":{"type":"object","description":"Shape varies by source: Hugging Face has downloads and likes, GitHub has stars, the forums have points and comments.","properties":{"rank":{"type":"integer"},"name":{"type":"string"},"title":{"type":"string"},"url":{"type":"string","format":"uri"},"author":{"type":"string"},"stars":{"type":"integer"},"downloads":{"type":"integer"},"likes":{"type":"integer"},"points":{"type":"integer"},"comments":{"type":"integer"},"publishedAt":{"type":"string"}}},"Box":{"type":"object","properties":{"name":{"type":"string"},"title":{"type":"string"},"dek":{"type":"string"},"path":{"type":"string"},"date":{"type":"string"}}}}}}