BYTETOOLS

TheCatAPI

Free cat image API with breed data, filtering and search. Works without a key for basic use; free key unlocks more. Tested curl example and live JSON.

No API key requiredCORS enabledHTTPSFree tier

Endpoint tested and returned HTTP 200 on 2026-08-19

What is the TheCatAPI?

TheCatAPI is a free API serving cat photographs along with detailed breed information. Basic random image requests work without a key, while a free API key unlocks breed filtering, larger result sets and favourites.

TheCatAPI is considerably more capable than a novelty image endpoint. Its breed database includes temperament, origin, life span, weight and behavioural ratings for energy level, affection and child-friendliness — a genuinely rich dataset behind a free tier.

The keyless tier covers random images, which is what the verified example here uses. Registering for a free key is quick and unlocks breed filtering and pagination, so it is worth doing before building anything beyond a demo.

Quick facts

Base URL
https://api.thecatapi.com/v1
Authentication
Basic image requests work with no key. A free API key, sent as the `x-api-key` header, unlocks breed filters, pagination and larger limits.
Rate limit
Keyless requests are limited and return small result sets; a free key raises the allowance substantially.
Pricing
Free tier with optional free key. Paid plans exist for high volume.
CORS
Enabled — callable directly from browser JavaScript
Official docs
Read the docs

How to use the TheCatAPI

Every request below was executed against the live API on 2026-08-19, and the response shown is the real body it returned — not an illustration.

1. Fetch a random cat image

GET https://api.thecatapi.com/v1/images/search

curl
curl 'https://api.thecatapi.com/v1/images/search'
JavaScript (fetch)
const res = await fetch("https://api.thecatapi.com/v1/images/search");
if (!res.ok) throw new Error(`Request failed: ${res.status}`);
const data = await res.json();
console.log(data);
Python (requests)
import requests

res = requests.get("https://api.thecatapi.com/v1/images/search", timeout=20)
res.raise_for_status()
print(res.json())
Response — HTTP 200
[
  {
    "id": "MTU4NDY0MQ",
    "url": "https://s3.us-west-2.amazonaws.com/cdn2.thecatapi.com/images/MTU4NDY0MQ.jpg",
    "width": 3888,
    "height": 2592
  }
]

Parameters

ParameterTypeRequiredDescription
limitintegerOptionalNumber of images. Keyless requests are capped at a small number. 1
breed_idsstringOptionalFilter by breed id — requires an API key. beng
sizestringOptionalthumb, small, med or full. small
x-api-keyheaderOptionalFree API key to unlock the full feature set. live_xxx

Response fields

idstring
Image identifier.
urlstring
Direct image URL, renderable straight into an img tag.
width / heightinteger
Native image dimensions — useful for avoiding layout shift.
breedsarray
Breed objects with temperament, origin, life span and behaviour ratings, when available.

What you can build with the TheCatAPI

  • Build a cat breed browser with photos and temperament data
  • Test responsive image handling with real, varied dimensions
  • Add pet imagery to an adoption or veterinary site
  • Practise API key header authentication with a free, low-stakes key

Common errors and how to fix them

401

Invalid API key supplied.

Fix: Send the key in the `x-api-key` header, not as a query parameter or bearer token.

Empty breeds array

Most images are not linked to a breed.

Fix: Request breed-specific images with `breed_ids`, which requires a key.

TheCatAPI — frequently asked questions

Can I use TheCatAPI without an API key?

Yes for basic random image requests, which is what the example on this page does. Breed filtering, pagination and larger result sets require a free API key.

How do I authenticate with TheCatAPI?

Send your key in the `x-api-key` HTTP header. It is not accepted as a query parameter or bearer token.

What breed information does it provide?

Temperament, origin, life span, weight, and numeric ratings for energy level, affection, intelligence and child-friendliness, among others.

Is there a dog equivalent from the same team?

Yes, TheDogAPI works identically with the same authentication scheme and a comparable breed dataset.

Tools that pair with this API

JSON Formatter

Format, beautify and minify JSON online with 2-space, 4-space or tab indentation. Sort keys alphabetically and catch syntax errors instantly — free and private.

Image Cropper

Crop images online to an exact rectangle with pixel-precise x, y, width and height inputs or aspect-ratio presets. Free, private and browser-based.

TheCatAPI is an independent third-party service and is not affiliated with ByteTools or ByteVancer. Details on this page were verified on 2026-08-19; always check the official documentation before relying on this API in production, as terms and limits can change.