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 19 Aug 2026

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 19 Aug 2026, 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

Parameter	Type	Required	Description
`limit`	integer	Optional	Number of images. Keyless requests are capped at a small number. `1`
`breed_ids`	string	Optional	Filter by breed id — requires an API key. `beng`
`size`	string	Optional	thumb, small, med or full. `small`
`x-api-key`	header	Optional	Free 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.

Alternatives to TheCatAPI

If TheCatAPI does not fit, these animal apis cover similar ground. Every one was called before publishing, and each links to its own reference page with a working curl command and the response it returned.

API	What it does	Auth	CORS	Last verified
Cat Facts	Free cat facts API with no key. Random feline facts as JSON, with pagination and length filtering. CORS enabled. Tested curl example and live response.	No key	Yes	19 Aug 2026
Dog CEO	Free dog image API with no key: 20,000+ photos across 100+ breeds and sub-breeds, random or filtered. CORS enabled. Tested curl example and live JSON.	No key	Yes	19 Aug 2026
RandomFox	Free fox image API with no key. Returns a random fox photo URL as JSON. CORS enabled, minimal payload. Tested curl example and live response included.	No key	Yes	19 Aug 2026
TinyFox	Free animal image API with no key: dozens of species behind one endpoint, returning either the image itself or a JSON path you can build a URL from. Tested example included.	No key	No	21 Aug 2026
WoRMS	Free WoRMS REST API with no key: authoritative marine species names, full taxonomic hierarchy and synonym resolution for over 240,000 accepted species. Tested example included.	No key	Yes	21 Aug 2026
Cataas (Cat as a Service)	Free cat image API with no key: random cats, tag filtering, text overlays and on-the-fly resizing, as an image or as JSON metadata. Tested example included.	No key	Yes	21 Aug 2026

All Animal APIs

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