The Pyyan API

Start here

One request tells you what exists. The root lists every resource with its live row count, so nothing below has to be memorised.

curl https://pyyan.com/api/v1

There is an OpenAPI 3.1 document at /api/v1/openapi.json. Paste that URL into Swagger, Postman, Bruno or an agent framework and it will generate a client for you.

The shape of every response

One record comes back as { data }. A list adds meta and links, so paging never means building URLs by hand.

{
  "data": [ { "slug": "nvidia-buys-hugging-face", "date": "2026-09-03", ... } ],
  "meta":  { "total": 35, "count": 20, "page": 1, "limit": 20, "pages": 2 },
  "links": { "self": "...", "next": "...?page=2&limit=20", "prev": null }
}

total counts everything matching your filter, not what is on this page. count is what came back. An X-Total-Count header carries the same number for anyone who would rather read a header.

Parameters every list understands

page, limit

Paging. limit defaults to 20 and stops at 100.

sort

A field name, or -field for descending. Only whitelisted fields are accepted. An unknown one is a 400 that lists the fields you can use, rather than being quietly ignored: silently returning data in an order nobody asked for is worse than an error, because there is no way to notice it.

fields

Comma separated keys to return, when you want a slug and a date rather than a whole story.

q

Free text search, case insensitive, on the fields listed for each resource.

Errors

Every failure is JSON with a stable machine code and a sentence for a person.

curl "https://pyyan.com/api/v1/news?sort=nonsense"

{
  "error": {
    "status": 400,
    "code": "bad_sort",
    "message": "Cannot sort by \"nonsense\".",
    "sortable": ["date", "addedAt", "headline", "category", "weight"]
  }
}

Codes in use: bad_sort, bad_limit, bad_page, no_search, not_found, unknown_source, internal_error.

Resources

Worked examples

# the five most recent stories, slugs and headlines only
curl "https://pyyan.com/api/v1/news?limit=5&fields=slug,date,headline"

# every language model, cheapest input first is not sortable, so sort by rank
curl "https://pyyan.com/api/v1/entities?category=language-models&limit=100"

# what Fei-Fei Li appears in
curl "https://pyyan.com/api/v1/videos?person=fei-fei-li"

# safety stories from September
curl "https://pyyan.com/api/v1/news?category=Safety&from=2026-09-01"

# what is trending on Hugging Face right now
curl "https://pyyan.com/api/v1/trending/huggingface?limit=10"

What is not here

Subscribers and short links have no route. There is no generic collection passthrough in this API: every resource is a file that names its own collection, its own sortable fields and its own filters, so a private collection cannot be reached by guessing a URL. Mongo's _id never leaves either, because it would become part of the contract the moment somebody stored one.

It is read only. There is no POST, PUT or DELETE on any of this, and no key to lose.

If you are an AI agent

There is an MCP server at /api/mcp covering the same data, with nine tools, two resources and two prompts. Point a client at it and it will discover the rest itself, which is less work than reading this page.

Terms, briefly

Free to use, including commercially. Attribution to pyyan.com is appreciated and not required. Caching is welcome and responses carry sensible cache headers, so please do cache rather than polling. If you are going to make a lot of requests, say hello first rather than finding out where the limit is.

Every figure in the index carries its own source and the date it was checked. If something is wrong, the source is right there in the response and corrections are welcome.