Search, upload, retrieve, and delete cat images.
openapi: 3.0.3
info:
title: The Cat Breeds Images API
description: The Cat API is an open, free, read and write API all about cats. Access thousands of cat images, vote on favorites, manage collections, explore breed information, and upload your own cat images. Requires a free API key for write operations.
version: 1.0.0
contact:
name: The Cat API Support
url: https://thecatapi.com/
license:
name: Free Tier Available
url: https://thecatapi.com/pricing
servers:
- url: https://api.thecatapi.com/v1
description: The Cat API Production Server
security:
- ApiKeyHeader: []
tags:
- name: Images
description: Search, upload, retrieve, and delete cat images.
paths:
/images/search:
get:
operationId: searchImages
summary: Search Cat Images
description: Search and retrieve cat images with optional filters for breed, category, size, format, and pagination. Returns random results by default.
tags:
- Images
parameters:
- name: limit
in: query
required: false
description: Number of results to return (1–100).
schema:
type: integer
minimum: 1
maximum: 100
default: 1
- name: page
in: query
required: false
description: Page number for paginated results.
schema:
type: integer
default: 0
- name: order
in: query
required: false
description: Order of results.
schema:
type: string
enum:
- RANDOM
- ASC
- DESC
default: RANDOM
- name: breed_ids
in: query
required: false
description: Comma-separated breed IDs to filter images.
schema:
type: string
example: beng,abys
- name: category_ids
in: query
required: false
description: Comma-separated category IDs to filter images.
schema:
type: string
- name: size
in: query
required: false
description: Preferred image size.
schema:
type: string
enum:
- small
- med
- full
- thumb
- name: mime_types
in: query
required: false
description: Comma-separated MIME types to filter by (jpg, png, gif).
schema:
type: string
example: jpg,gif
- name: has_breeds
in: query
required: false
description: Filter to only images that have breed information.
schema:
type: integer
enum:
- 0
- 1
responses:
'200':
description: Array of cat images matching the search criteria.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Image'
'400':
description: Bad request.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized — invalid or missing API key.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/images/upload:
post:
operationId: uploadImage
summary: Upload Cat Image
description: Upload a cat image. Requires a valid API key. Supported formats are JPEG, PNG, and GIF.
tags:
- Images
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
properties:
file:
type: string
format: binary
description: The image file to upload.
sub_id:
type: string
description: Optional sub-account identifier.
responses:
'201':
description: Image uploaded successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Image'
'400':
description: Bad request — unsupported file type or validation error.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/images:
get:
operationId: getUploadedImages
summary: Get Uploaded Images
description: Retrieve images uploaded by the authenticated user.
tags:
- Images
parameters:
- name: limit
in: query
required: false
schema:
type: integer
default: 10
maximum: 100
- name: page
in: query
required: false
schema:
type: integer
default: 0
- name: order
in: query
required: false
schema:
type: string
enum:
- ASC
- DESC
default: ASC
responses:
'200':
description: List of uploaded images.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Image'
/images/{image_id}:
get:
operationId: getImage
summary: Get Image
description: Retrieve a specific image by its ID.
tags:
- Images
parameters:
- name: image_id
in: path
required: true
description: Unique identifier of the image.
schema:
type: string
responses:
'200':
description: Image details.
content:
application/json:
schema:
$ref: '#/components/schemas/Image'
'404':
description: Image not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
delete:
operationId: deleteImage
summary: Delete Image
description: Delete an uploaded image. Only works on images uploaded by the authenticated user.
tags:
- Images
parameters:
- name: image_id
in: path
required: true
schema:
type: string
responses:
'204':
description: Image deleted successfully.
'404':
description: Image not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
components:
schemas:
Category:
type: object
description: An image category tag.
properties:
id:
type: integer
description: Unique identifier of the category.
name:
type: string
description: Name of the category.
required:
- id
- name
Image:
type: object
description: A cat image with metadata.
properties:
id:
type: string
description: Unique identifier of the image.
url:
type: string
format: uri
description: Full URL of the image.
width:
type: integer
description: Width of the image in pixels.
height:
type: integer
description: Height of the image in pixels.
breeds:
type: array
description: Breed information associated with this image.
items:
$ref: '#/components/schemas/Breed'
categories:
type: array
items:
$ref: '#/components/schemas/Category'
required:
- id
- url
Error:
type: object
properties:
status:
type: integer
description: HTTP status code.
message:
type: string
description: Error message.
Breed:
type: object
description: Information about a cat breed.
properties:
id:
type: string
description: Unique breed identifier (e.g., beng, abys).
name:
type: string
description: Name of the breed.
cfa_url:
type: string
format: uri
description: Cat Fanciers' Association profile URL.
vetstreet_url:
type: string
format: uri
vcahospitals_url:
type: string
format: uri
temperament:
type: string
description: Comma-separated list of temperament traits.
origin:
type: string
description: Country of origin.
country_codes:
type: string
description: ISO country code(s) for the breed's origin.
description:
type: string
description: Narrative description of the breed.
life_span:
type: string
description: Expected lifespan range (e.g., "12-15").
indoor:
type: integer
enum:
- 0
- 1
lap:
type: integer
enum:
- 0
- 1
adaptability:
type: integer
minimum: 1
maximum: 5
affection_level:
type: integer
minimum: 1
maximum: 5
child_friendly:
type: integer
minimum: 1
maximum: 5
dog_friendly:
type: integer
minimum: 1
maximum: 5
energy_level:
type: integer
minimum: 1
maximum: 5
grooming:
type: integer
minimum: 1
maximum: 5
health_issues:
type: integer
minimum: 1
maximum: 5
intelligence:
type: integer
minimum: 1
maximum: 5
shedding_level:
type: integer
minimum: 1
maximum: 5
social_needs:
type: integer
minimum: 1
maximum: 5
stranger_friendly:
type: integer
minimum: 1
maximum: 5
vocalisation:
type: integer
minimum: 1
maximum: 5
wikipedia_url:
type: string
format: uri
image:
$ref: '#/components/schemas/Image'
required:
- id
- name
securitySchemes:
ApiKeyHeader:
type: apiKey
in: header
name: x-api-key
description: API key obtained by registering at https://thecatapi.com/signup