Cat API — GET /v1/images/search

limit

Controls how many images come back in a single response. The default is 1. The maximum is 25. If you want more than one image, you need an API key.

When to use it: Any time you need more than a single cat — loading a grid, pre-fetching a batch, or building something that needs variety on the same page load.

order

Controls whether results come back in a stable, predictable sequence or in a random shuffle each time.

• RANDOM (default) — different images every call. Good for widgets, splash screens, anything where novelty is the point. Pagination doesn't work in this mode.
• ASC / DESC — results come back in a consistent order based on when the images were added to the API. Use either of these when you want to page through a stable result set — e.g. a gallery where users can go forward and back without seeing repeats.

page

When you're using order=ASC or order=DESC, you can step through the full result set in chunks using page. It's zero-indexed, so the first page is page=0, the second is page=1, and so on.

When to use it: Pagination. If you're fetching 10 images at a time and want the next 10, increment the page number. See Section 09 for a worked example.

Note: This parameter does nothing when order=RANDOM. The API ignores it silently.

breed_ids

Pass one or more breed IDs to get back images of only those breeds. IDs are short strings like beng for Bengal or abys for Abyssinian. Separate multiple IDs with a comma.

When to use it: When your app is about a specific breed, or when a user has selected a breed from a list and you're fetching images to match. To get the full list of valid breed IDs, call GET /v1/breeds.

Requires an API key. Without one, this parameter is silently ignored and you'll get a random image with no filtering applied.

category_ids

Similar to breed_ids, but for categories. Categories are broader groupings — things like "hats" or "boxes" — rather than breed-specific. Pass one or more category IDs as a comma-separated list. Call GET /v1/categories for the full list.

Requires an API key.

has_breeds

By default, the API returns whatever images it finds — not all of them have breed data attached. Set has_breeds=1 to filter out any image that doesn't come with a breeds object in the response.

When to use it: Whenever you want to display breed information alongside the image — name, description, temperament, origin. Without this filter, the breeds array may come back empty even when you're not filtering by a specific breed.

mime_types

The Cat API serves JPGs, PNGs, and GIFs. By default you'll get a mix of all three. Pass one or more types to restrict what comes back.

When to use it: If your UI can't handle GIFs, or you specifically want animated images, or you're compressing images downstream and need a consistent format.

size

The API stores images in multiple size variants. This parameter tells it which one to give you. med is a good default for most display contexts. Use thumb for compact grids or lists, and full when you need the original resolution.

format

By default the API responds with JSON — a structured data object containing the image URL, dimensions, and any breed or category info. Setting format=src changes the response entirely: instead of JSON, you get back the raw image file itself.

When to use it: When you want to point an <img> tag directly at the API endpoint without any JavaScript. The endpoint URL becomes the image source. All other parameters still apply, so you can still filter by breed, type, or size.

Every image in the response includes these fields.

When a breed is attached to an image, each item in the breeds array contains the following. Most images have either zero or one breed — multiple is uncommon.

When you use order=ASC or order=DESC, the API includes an extra HTTP response header alongside the JSON body.

Pagination lets you fetch large result sets in manageable chunks instead of all at once. Here's how it works in practice.

Say you want to show all Bengal cat images, 10 at a time. Your first request looks like this:

?breed_ids=beng&order=ASC&limit=10&page=0

The response body gives you 10 images. The pagination-count response header tells you, say, 87 — meaning there are 87 Bengal images in total. That means 9 pages (⌈87 ÷ 10⌉ = 9). To get the next batch, increment page:

?breed_ids=beng&order=ASC&limit=10&page=1  # images 11–20
?breed_ids=beng&order=ASC&limit=10&page=2  # images 21–30
# ...and so on

Rate limits on the Cat API are monthly, not per-second. You won't get throttled for making rapid requests — but you will run out of allowance if you make too many calls across the month.

• Free tier: 10,000 requests per month
• Premium tier: 100,000 requests per month

If you're building something in development and burning through requests quickly, cache the responses locally. Fetching the same breed's images over and over during testing is a quick way to hit your limit before anything is even deployed.

The API doesn't error when you pass filtering parameters without a key — it just ignores them and returns a random image. This is the most common source of confusion when first using the API.

If you're getting random results when you expected filtered ones, and everything looks right in your code, the problem is almost always a missing or invalid x-api-key header. Check these in order:

• Is the header present at all in the request?
• Is it named x-api-key in lowercase?
• Is the value your actual key from the dashboard, not a placeholder?
• Is the environment variable or config file actually being read by your code?