cataas.com

OpenAPI-generated API documentation is reference documentation that is produced automatically from an OpenAPI description file rather than written by hand. You write (or generate) a machine-readable specification of your API — endpoints, parameters, request bodies, responses, schemas, and auth — and a documentation tool reads that file and renders a browsable, often interactive reference site. The spec becomes the single source of truth; the docs become a build artifact.

This differs from manually written docs in one fundamental way: with hand-written docs, the prose is the source of truth and the API is described separately. With spec-driven docs, the API description is the source, and every page, table, and code sample is derived from it.

How the workflow actually runs

A typical spec-driven documentation pipeline has five stages:

1. Author or generate the spec. You either write an OpenAPI document by hand (YAML or JSON), or generate it from code annotations, framework metadata, or a design-first editor. Design-first means the spec is written before implementation; code-first means it is extracted from existing code.
2. Validate and lint. The spec is checked against the OpenAPI schema and against style rules — consistent naming, required descriptions, no undocumented 4xx responses, no orphaned schemas.
3. Bundle and transform. Multi-file specs are combined, $ref pointers are resolved, and the document is optionally split into per-tag or per-version outputs.
4. Render. A documentation tool converts the spec into HTML: an endpoint list, a sidebar of operations, parameter tables, response schemas, and a "try it" console.
5. Publish and version. The rendered site is deployed, and each API version gets its own snapshot so consumers can read docs matching the version they call.

Steps 2 through 5 are usually automated in CI. If the spec fails validation, the docs build fails — which is the point.

Spec-driven vs. hand-written documentation

The practical conclusion most teams reach: generate the reference, write the guides. Reference material is repetitive and mechanical, which is exactly what generation is good at. Conceptual explanations, migration notes, and tutorials carry judgment that a spec cannot express.

What you get out of the box

Generated reference pages commonly include:

• An operation list grouped by tag or path, with HTTP method and path.
• Parameter tables showing name, location (path, query, header, cookie), type, required flag, and description.
• Request and response schemas rendered as expandable trees, including nested objects and arrays.
• Authentication details pulled from the securitySchemes section.
• Interactive request consoles that let a reader send a real call from the browser.
• Generated code samples in several languages, derived from the same schemas.
• Multiple output formats, such as a static site, a single HTML file, or a mock server.

Because all of these come from one document, changing a field name in the spec updates the parameter table, the schema tree, and every code sample at once.

Where spec-driven documentation breaks down

Generation is not free. The trade-offs are real:

Spec quality becomes documentation quality. A field with no description produces a table row with an empty cell. A vague summary produces a vague heading. Tools can enforce presence of descriptions via linting, but they cannot enforce that the description is useful.

Customization has limits. If you need a page that does not map to an OpenAPI concept — a conceptual overview, a pricing explanation, a comparison of two endpoints — you write it outside the generator and link to it.

Not everything is expressible. Webhooks, streaming responses, long-polling behavior, and complex multi-step flows are awkward or impossible to describe fully in OpenAPI. Those need prose.

The spec can go stale. If the spec is maintained separately from the implementation, it drifts just like hand-written docs. The mitigation is to generate the spec from code, or to test the implementation against the spec in CI.

Interactive consoles need care. A "try it" button that hits a production API with real credentials is a security and rate-limit problem. Point it at a sandbox, or disable it.

Deciding whether to adopt it

Adopt spec-driven reference documentation if most of these are true:

• Your API has more than a handful of endpoints, or changes frequently.
• You ship client SDKs or code samples in more than one language.
• Multiple teams consume the API and need a consistent, always-current reference.
• You already have, or are willing to maintain, an OpenAPI description.

Stay with hand-written docs, or a hybrid, if:

• Your API is small and stable, and the reference fits on one page.
• Your documentation is mostly conceptual and contains little endpoint-level detail.
• You cannot commit to keeping the spec in sync with the implementation.

A reasonable middle path: generate the reference from the spec, and hand-write the getting-started guide, authentication walkthrough, and error-handling page. Link the two directions so readers can move from concept to endpoint and back.

A minimal starting checklist

1. Produce one valid OpenAPI document for a single API version.
2. Add a linter with rules for descriptions, operation IDs, and error responses.
3. Wire the docs build into CI so a failing spec fails the build.
4. Render the reference and review it as a reader, not as the author.
5. Write the two or three conceptual pages the generator cannot produce.
6. Version the published docs alongside the API version.

The core idea is simple: describe the API once, in a format both machines and humans can read, and let the reference documentation fall out of that description. Everything else — tooling, hosting, interactivity — is a detail on top of that decision.

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

CATAAS (Cat as a Service) is a REST API that returns cat images and GIFs on demand. You call a URL such as /cat and get a random cat back; you can add tags, overlaid text, filters, and size parameters to control what you get. It is useful when you need placeholder cat imagery for a demo, a test fixture, a chat bot, or a fun embed, and you want it without hosting images yourself. The site describes itself as "a REST API to spread peace and love (or not) thanks to cats."

What you can request

The API is organized around a small set of URL patterns. The table below reflects the endpoints listed in the site's documentation.

Tags can be combined using the :tag separator, so a single request can narrow results to more than one tag.

Advanced options

Beyond tags and text, the documentation lists query parameters that change the image itself:

• Type: /cat?type=:type accepts xsmall, small, medium, or square.
• Filter: /cat?filter=:filter accepts blur, mono, negate, or custom.
• Custom filter values: with filter=custom, you can pass brightness, lightness, saturation, and hue, or pass r, g, and b values.
• Dimensions: /cat?width=:width or /cat?height=:height sets a custom size.
• HTML output: /cat?html=true returns the cat inside an HTML page, which the docs note is useful for Twitter or Facebook embedded rendering.
• JSON output: /cat?json=true returns a random cat as a JSON object.

Parameters can be combined. The documentation's own combo example is /cat/gif/says/Hello?filter=mono&fontColor=orange&fontSize=20&type=square.

Getting JSON data and tags

Two endpoints return data rather than an image:

• /api/cats?tags=tag1,tag2&skip=0&limit=10 returns a list of cats, with tag filtering and paging via skip and limit.
• /api/tags returns all available tags.

According to the site's changelog notes, JSON is returned when the request contains an application/json header, and tag search plus comma-separated tag combinations were fixed in the current major version. The API documentation is linked from the site as "API doc."

Things to know before you build on it

• The homepage counter read "Have 0 cats for now" at the time of the captured page, so the available image pool may be limited or in flux; check /api/tags and /api/cats before relying on specific tags.
• The site lists a "Buy me a beer" support link but no pricing page or payment details, so treat cost and usage limits as unspecified rather than free-for-any-volume.
• The footer reads "© 2026 - Made with ❤️ by Kevin - all rights reserved," which is worth checking if you plan to redistribute the images rather than just display them.

For a quick start, request /cat to confirm the service responds, then add ?json=true if your client expects structured data, or move to /api/cats when you need a list rather than a single random image.

You can filter and customize CATAAS cat images with query parameters on the /cat endpoint: type sets the image shape (xsmall, small, medium, square), filter applies blur, mono, negate, or custom effects, width/height resize the image, and filter=custom accepts brightness, lightness, saturation, hue, or RGB values. All of these can be combined with tag paths and the says text endpoint, so a single request can return, for example, a square, monochrome, resized cat saying "Hello."

The parameters at a glance

These are documented as query parameters on /cat, so they attach after a ? and are joined with &.

Step-by-step: build a customized request

1. Start from the base endpoint. A plain GET /cat returns a random cat.
2. Add a shape if you need one. GET /cat?type=square returns a square cat; the other documented values are xsmall, small, and medium.
3. Add a filter. GET /cat?filter=mono returns a monochrome cat. The presets are blur, mono, and negate.
4. Or tune the filter yourself. GET /cat?filter=custom&brightness=:brightness&lightness=:lightness&saturation=:saturation&hue=:hue adjusts those four properties, while GET /cat?filter=custom&r=:red&g=:green&b=:blue applies an RGB filter.
5. Resize. GET /cat?width=:width or GET /cat?height=:height returns the cat at your chosen dimension.
6. Combine everything. The documentation's own combo example is /cat/gif/says/Hello?filter=mono&fontColor=orange&fontSize=20&type=square, which mixes a GIF, overlay text, a filter, text styling, and an image type in one request.

Expected result: the response is the image itself, unless you ask for another format (see below). Verify it worked by checking that the returned image shows the shape, filter, and size you requested; if a parameter seems ignored, confirm the spelling and that it is attached to /cat with ? and &.

Combining filters with tags and text

Filters are query parameters, so they stack on top of the path-based features:

• Tags: /cat/:tag returns a random cat with that tag, and multiple tags can be combined with the :tag separator (the docs show "Random orange cute cat" as the example). Add filters after the path, e.g. /cat/:tag?filter=blur.
• Text overlay: /cat/says/:text returns a cat saying your text, and /cat/:tag/says/:text combines a tag with text. Text styling is also available via fontSize and fontColor, as in /cat/says/:text?fontSize=:size&fontColor=:color.
• Everything at once: a tag path, says, and query filters can all appear in one URL, following the combo pattern above.

Choosing between presets and custom filters

• Use a preset (blur, mono, negate) when you want a predictable, one-word effect and don't need fine control — it keeps URLs short and readable.
• Use filter=custom when you need a specific look: the brightness/lightness/saturation/hue route for perceptual adjustments, or the r/g/b route for color-channel control. Note that the two custom forms are documented separately, so pick one per request rather than assuming they merge.
• Use type vs. width/height depending on intent: type selects a documented image variant, while width/height gives you an explicit dimension. If you need an exact pixel size, the width/height parameters are the direct route.

Getting JSON instead of an image

If your client needs metadata rather than the binary image, the docs describe two options: /cat?json=true returns a random cat as a JSON object, and the newer behavior returns JSON when the request contains an application/json header. For browsing the collection, /api/cats?tags=tag1,tag2&skip=0&limit=10 returns cats filtered by tags with pagination, and /api/tags returns all available tags — useful for discovering valid tag values before building filtered image URLs.

Common snags

• Tag search behavior changed: the site notes a fix for tags search and for tags combined with a , separator, so if you relied on older tag syntax, check the current API doc.
• Mixing parameters: keep the ?/& structure intact when combining filter, type, and text options; a malformed query is the most likely reason a customization silently doesn't apply.
• JSON vs. image: decide up front whether you want the image or the JSON object, since json=true or the JSON header changes the response type.

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:

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:

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.