How to Get JSON Data or an HTML Page from CATAAS

To get machine-readable data from CATAAS, use /cat?json=true for a single random cat, /api/cats?tags=...&skip=0&limit=10 for a batch list, and /api/tags for all available tags. To get a ready-to-embed HTML page instead, use /cat?html=true. One behavior worth knowing: the site notes that JSON is returned when the request contains an application/json header, so if you rely on header-based negotiation, set that header explicitly.

Single random cat as JSON

Request:

GET https://cataas.com/cat?json=true

Expected result: a JSON object describing one random cat instead of the image binary. This is the simplest way to get a cat reference you can then render yourself, for example by building an image URL from the returned identifier.

You can combine this with the other /cat options, since the documentation shows a combined example:

GET https://cataas.com/cat/gif/says/Hello?filter=mono&fontColor=orange&fontSize=20&type=square

The same query parameters (type, filter, width, height, fontSize, fontColor) apply to the random-cat endpoint, so ?json=true can sit alongside them when you want metadata plus a customized image.

Single random cat as an HTML page

Request:

GET https://cataas.com/cat?html=true

Expected result: a random cat wrapped in an HTML page. The documentation describes this as useful for Twitter or Facebook embedded rendering — in other words, a page you can point an embed or iframe at rather than an image URL.

Batch queries: list cats by tag

Request pattern:

GET https://cataas.com/api/cats?tags=tag1,tag2&skip=0&limit=10

Expected result: a list of cats matching the tags. Use skip with a fixed limit to page through results — for example skip=0&limit=10, then skip=10&limit=10.

Note the separator difference: the batch endpoint uses a comma (,) between tags, while the random-cat path uses a colon (:tag) to combine tags, as in /cat/orange:cute. The site's changelog specifically mentions fixing tag search and tags combined with the comma separator, so comma is the documented form for /api/cats.

Discover valid tags

Request:

GET https://cataas.com/api/tags

Expected result: all tags currently available. Call this before building a tag-filtered query so you don't page through empty results with a tag that doesn't exist.

Practical notes

• The homepage counter reads "Have 0 cats for now," which reflects the live count at load time; don't hardcode an expected total. Always rely on the limit/skip response rather than assuming a collection size.
• If a JSON request comes back as something unexpected, check whether you sent the application/json header — the site states JSON is returned when the request contains it.
• For a single image with custom text, /cat/says/:text plus fontSize and fontColor covers most captioning needs; add ?json=true only when you need the object rather than the image.

Quick reference