The Cat API

api.thecatapi.com · Developer Tools

Developer Tools API Key Free Tier Animals Images Developer Tools

Random cat images, facts, and breed data. Upload and vote on cat photos. Free API key gives higher rate limits and upload access.

Authentication

API Key authentication Free API key at thecatapi.com. Pass as x-api-key header. Without a key: limited to public endpoints.

Sample Requests

GET Random cat image

Get a random cat image.

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

Hover any highlighted part to learn what it does

curl -X GET "https://api.thecatapi.com/v1/images/search"

import requests
response = requests.get(
    "https://api.thecatapi.com/v1/images/search",
)
print(response.json())

const url = 'https://api.thecatapi.com/v1/images/search';

const response = await fetch(url); 
const data = await response.json();
console.log(data);

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	targetURL := "https://api.thecatapi.com/v1/images/search"
	req, _ := http.NewRequest("GET", targetURL, nil)

	client := &http.Client{}
	resp, _ := client.Do(req)
	defer resp.Body.Close()
	body, _ := io.ReadAll(resp.Body)
	fmt.Println(string(body))
}

require "net/http"
require "json"

uri = URI("https://api.thecatapi.com/v1/images/search")

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = uri.scheme == "https"

req = Net::HTTP::Get.new(uri)

res = http.request(req)
puts JSON.parse(res.body)

<?php
$url = "https://api.thecatapi.com/v1/images/search";
$opts = ["http" => [
    "method" => "GET",
]];
$ctx = stream_context_create($opts);
$res = file_get_contents($url, false, $ctx);
print_r(json_decode($res, true));

GET Random image by breed

Get Bengal cat images.

https://api.thecatapi.com/v1/images/search?limit=3&breed_ids=beng

Hover any highlighted part to learn what it does

Headers — extra info sent with the request

x-api-key

YOUR_KEY

curl -X GET "https://api.thecatapi.com/v1/images/search?limit=3&breed_ids=beng" \
  -H "x-api-key: YOUR_KEY"

import requests
params = {
    "limit": "3",
    "breed_ids": "beng"
}
headers = {
    "x-api-key": "YOUR_KEY"
}
response = requests.get(
    "https://api.thecatapi.com/v1/images/search",
    params=params,
    headers=headers,
)
print(response.json())

const url = new URL('https://api.thecatapi.com/v1/images/search');
url.searchParams.set('limit', '3');
url.searchParams.set('breed_ids', 'beng');

const response = await fetch(url, {
  headers: {
    'x-api-key': 'YOUR_KEY'
  },
}); 
const data = await response.json();
console.log(data);

package main

import (
	"fmt"
	"io"
	"net/http"
	"net/url"
)

func main() {
	baseURL, _ := url.Parse("https://api.thecatapi.com/v1/images/search")
	q := baseURL.Query()
	q.Set("limit", "3")
	q.Set("breed_ids", "beng")
	baseURL.RawQuery = q.Encode()
	targetURL := baseURL.String()
	req, _ := http.NewRequest("GET", targetURL, nil)
	req.Header.Set("x-api-key", "YOUR_KEY")

	client := &http.Client{}
	resp, _ := client.Do(req)
	defer resp.Body.Close()
	body, _ := io.ReadAll(resp.Body)
	fmt.Println(string(body))
}

require "net/http"
require "json"

uri = URI("https://api.thecatapi.com/v1/images/search")
uri.query = URI.encode_www_form({
  "limit" => "3",
  "breed_ids" => "beng"
})

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = uri.scheme == "https"

req = Net::HTTP::Get.new(uri)
req["x-api-key"] = "YOUR_KEY"

res = http.request(req)
puts JSON.parse(res.body)

<?php
$url = "https://api.thecatapi.com/v1/images/search?" . http_build_query([
    "limit" => "3",
    "breed_ids" => "beng"
]);
$opts = ["http" => [
    "method" => "GET",
    "header" => implode("\r\n", [
        "x-api-key: YOUR_KEY"
    ]),
]];
$ctx = stream_context_create($opts);
$res = file_get_contents($url, false, $ctx);
print_r(json_decode($res, true));

Postman Setup Guide

Get Postman ↗

Works without a key for basic requests
Get a free key at thecatapi.com for higher limits
Random: GET https://api.thecatapi.com/v1/images/search
By breed: ?breed_ids=abys (Abyssinian)
Breeds list: GET /breeds

What can you build with The Cat API?

The Cat API is a Developer Tools API. Developers commonly use developer tools APIs for:

automating code review and quality checks
integrating CI/CD pipelines and build systems
managing feature flags and A/B tests
monitoring errors and application performance
generating and validating test data

API Key authentication. You'll receive a key after signing up. Send it with every request — in a header or query parameter. Keep it out of client-side code and never commit it to version control. The Cat API is free to use up to a usage limit, making it a low-risk choice to experiment with.

New to APIs? Read our beginner's guide

Open documentation ↗