Skip to main content

Images

Search, list, and upload cat images.

Search images​

curl -H "x-api-key: YOUR-API-KEY" "https://api.thecatapi.com/v1/images/search?limit=2"

Example response:

[
  {
    "id": "KWdLHmOqc",
    "url": "https://cdn2.thecatapi.com/images/KWdLHmOqc.jpg",
    "width": 3114,
    "height": 2609,
    "breeds": []
  }
]

Useful search filters​

ParameterExampleDescription
limit10Number of images to return (1–100 with an API key).
page0Zero-based page index, see pagination.
orderRANDASC, DESC or RAND by upload date.
has_breeds1Only return images that have breed information.
breed_idsabys,bengComma-separated breed IDs to filter by.
include_breeds1Embed the full breed objects in each image.
include_categories1Embed category objects in each image.
sub_idmy-user-123Only images uploaded with this sub_id.

For example, two random Abyssinian images with breed details attached:

curl -H "x-api-key: YOUR-API-KEY" "https://api.thecatapi.com/v1/images/search?limit=2&breed_ids=abys&include_breeds=1"

Get an image by ID​

curl -H "x-api-key: YOUR-API-KEY" https://api.thecatapi.com/v1/images/KWdLHmOqc

Upload an image​

curl -X POST -H "x-api-key: YOUR-API-KEY" -F "file=@/path/cat.jpg" https://api.thecatapi.com/v1/images/upload

Synchronous Upload​

Upload an image and wait for the analysis (breed detection and categorisation) to complete before the response is returned. This endpoint lives on the dedicated upload host.

curl -X POST -H "x-api-key: YOUR-API-KEY" -F "file=@/path/cat.jpg" https://upload.thecatapi.com/v1/images/upload-sync

See Image Uploads for the full upload flow, status polling and quota checks.

Check Image Status​

Poll this endpoint to check if an uploaded image has been processed.

curl -H "x-api-key: YOUR-API-KEY" https://api.thecatapi.com/v1/images/IMAGE_ID/status

Example Status Response​

{
  "id": "my-image-123",
  "status": "clean",
  "updated_at": "2024-01-01T12:00:00.000Z"
}

List your uploaded images​

curl -H "x-api-key: YOUR-API-KEY" https://api.thecatapi.com/v1/images

Filter by sub_id​

curl -H "x-api-key: YOUR-API-KEY" "https://api.thecatapi.com/v1/images?sub_id=YOUR-SUB-ID"

Delete an uploaded image​

curl -X DELETE -H "x-api-key: YOUR-API-KEY" https://api.thecatapi.com/v1/images/IMAGE_ID

Get Image Labels​

Retrieve the AI-generated labels (breeds, categories) for one of your uploaded images.

curl -H "x-api-key: YOUR-API-KEY" https://api.thecatapi.com/v1/images/IMAGE_ID/labels