Documentation
Documentation
https://developers.thecatapi.com/
GettingStarted
https://developers.thecatapi.com/view-account/ylX4blBYT9FaoVd6OhvR?report=bOoeBGLXVHoGjXfjeHLFo5lFU
OpenAPI Specification
openapi: 3.0.3
info:
title: The Cat Breeds Votes 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: Votes
description: Cast and manage votes on cat images.
paths:
/votes:
get:
operationId: listVotes
summary: List Votes
description: Retrieve all votes cast by the authenticated user.
tags:
- Votes
parameters:
- name: limit
in: query
required: false
schema:
type: integer
default: 100
maximum: 100
- name: page
in: query
required: false
schema:
type: integer
default: 0
- name: sub_id
in: query
required: false
description: Filter by sub-account identifier.
schema:
type: string
responses:
'200':
description: List of votes.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Vote'
post:
operationId: createVote
summary: Create Vote
description: Cast an upvote (1) or downvote (0) on a cat image.
tags:
- Votes
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- image_id
- value
properties:
image_id:
type: string
description: ID of the image to vote on.
value:
type: integer
enum:
- 0
- 1
description: Vote value — 1 for upvote, 0 for downvote.
sub_id:
type: string
description: Optional sub-account identifier.
responses:
'200':
description: Vote recorded successfully.
content:
application/json:
schema:
type: object
properties:
message:
type: string
id:
type: integer
'400':
description: Bad request.
/votes/{vote_id}:
get:
operationId: getVote
summary: Get Vote
description: Retrieve a specific vote by its ID.
tags:
- Votes
parameters:
- name: vote_id
in: path
required: true
schema:
type: integer
responses:
'200':
description: Vote details.
content:
application/json:
schema:
$ref: '#/components/schemas/Vote'
delete:
operationId: deleteVote
summary: Delete Vote
description: Remove a vote cast by the authenticated user.
tags:
- Votes
parameters:
- name: vote_id
in: path
required: true
schema:
type: integer
responses:
'200':
description: Vote deleted successfully.
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
Vote:
type: object
description: A vote cast on an image by a user.
properties:
id:
type: integer
description: Unique identifier of the vote.
user_id:
type: string
description: ID of the user who cast this vote.
image_id:
type: string
description: ID of the voted image.
value:
type: integer
enum:
- 0
- 1
description: Vote value — 1 for upvote, 0 for downvote.
sub_id:
type: string
description: Sub-account identifier.
created_at:
type: string
format: date-time
description: Timestamp when the vote was cast.
country_code:
type: string
description: ISO country code of the voter.
image:
$ref: '#/components/schemas/Image'
required:
- id
- image_id
- value
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