How Tag Combinations Work on CATAAS and How to Support the Project

Updated

On CATAAS (Cat as a Service), you combine tags by chaining them with the :tag separator in the image URL — for example /cat/orange:cute returns a random cat matching both tags. The /api/cats endpoint uses a different convention: comma-separated tags in a single tags query parameter, like ?tags=orange,cute. To support the project, the site offers a "Buy me a beer" link.

Combining tags for random cat images

The basic image endpoint accepts one or more tags directly in the path:

URL pattern What it returns
/cat A random cat, no tag filter
/cat/:tag A random cat with that tag
/cat/:tag1:tag2 A random cat matching the combined tags

The site's own example is a random orange cute cat, built by joining tags with the : separator. The practical effect is narrowing the random pool: each added tag restricts results further, so a combination that no image satisfies will not return a usable cat.

Tags plus text

You can keep the tag filter while adding a caption:

  • /cat/:tag/says/:text — a random cat with that tag saying your text.
  • /cat/says/:text — the same, without a tag filter.

Text styling is appended as query parameters, e.g. ?fontSize=:size&fontColor=:color. These combine with the advanced options below.

Querying the JSON API by tags

The JSON endpoints use commas rather than colons:

Endpoint Purpose
/api/cats?tags=tag1,tag2&skip=0&limit=10 Returns cats matching the tags, with paging via skip and limit
/api/tags Returns all available tags

Two practical notes from the site's changelog: tag search was fixed, and tags combined with a , separator were fixed — so comma separation is the supported form for the API. If you are unsure which tags exist, call /api/tags first and build combinations from real values instead of guessing.

Getting JSON from the image endpoint

/cat?json=true returns a random cat as a JSON object. The changelog adds that JSON is returned when the request contains an application/json header, so a client sending that header gets JSON without the query flag. /cat?html=true instead returns an HTML page, which the site describes as useful for Twitter or Facebook embedded rendering.

Mixing tags with filters and sizes

Tags are only one part of the query string; the advanced parameters stack on top:

  • Type: ?type=xsmall, small, medium, or square.
  • Filter: ?filter=blur, mono, negate, or custom.
  • Custom filter: ?filter=custom&brightness=:b&lightness=:l&saturation=:s&hue=:h, or RGB via &r=:red&g=:green&b=:blue.
  • Dimensions: ?width=:width or ?height=:height.

The site's combined example is /cat/gif/says/Hello?filter=mono&fontColor=orange&fontSize=20&type=square. The same pattern works with a tag path, so a tagged, captioned, filtered, square image is a single request.

Supporting the project

The page includes a "Buy me a beer 🍺" link alongside the upload and API doc links, described as a way to support the project if you like Cataas. The site does not publish pricing, tiers, or account requirements, so treat the beer link as the stated support channel rather than assuming any paid plan or free-tier guarantee. The footer credits Kevin and notes all rights reserved.

Quick reference

  • Image endpoint, multiple tags: join with :, e.g. /cat/orange:cute.
  • JSON API, multiple tags: join with ,, e.g. /api/cats?tags=orange,cute.
  • Discover valid tags: /api/tags.
  • JSON output: /cat?json=true or send an application/json header.
  • Support: use the "Buy me a beer" link on the site.