Перейти к основному содержимому
API docs by Redocly

TheCatAPI (1.7.1)

Download OpenAPI specification:Download

ThatAPICompany: support@thatapicompany.com URL: https://thatapicompany.com

REST API documentation for TheCatAPI by That API Company. Guides and examples at https://docs.thecatapi.com

Pets

Create pets, upload their photos and videos, and run analyses on them.

Create a pet with optional images

Authorizations:
x-api-key
Request Body schema: multipart/form-data
required
name
string

Name of the pet

breed_id
string

Breed identifier (references breeds.id)

species_id
string

Species identifier

description
string

Description of the pet

microchip_id
string

Microchip ID

sub_id
string

Subscription or other identifier

external_owner_id
string <= 255 characters

The pet owner's ID in your own system (e.g. a Firebase uid). Many pets can share one value; filter GET /pets by it to list one owner's pets.

country
string

ISO 3166-1 alpha-2 country code for geographic and seasonal context

sex
string
Enum: "male" "female" "unknown"

Used to pick the sex-specific breed weight range in the calculators.

neuter_status
string
Enum: "neutered" "intact" "unknown"

Used to pick the neutered or intact energy factor in the calculators.

date_of_birth
string

ISO date string for date of birth. Provide this OR age_years/age_months.

age_years
number

Age in years. Used with age_months to compute date_of_birth.

age_months
number

Age in months (0-11). Used with age_years to compute date_of_birth.

body_condition_score
number [ 1 .. 9 ]

Body Condition Score (1-9 scale)

poses
string

JSON string mapping file index (0-based) to pose enum value. E.g. {"0":"front","1":"side"}

images
Array of strings <binary> [ items <binary > ]

Image files to upload (max 20)

Responses

Response samples

Content type
application/json
{
  • "id": "abc123",
  • "name": "Buddy",
  • "breed_id": "15",
  • "species_id": "2",
  • "description": "A friendly golden retriever",
  • "microchip_id": "123456789",
  • "sub_id": "sub_123",
  • "external_owner_id": "Xy7rT2kLmN9pQ4sV8wZ1aB3cD5e",
  • "country": "AU",
  • "date_of_birth": "2022-06-15",
  • "sex": "male",
  • "neuter_status": "neutered",
  • "body_condition_score": 5,
  • "body_condition_score_reasons": "Reasons for the score",
  • "body_condition_score_timestamp": "2024-01-15T12:00:00.000Z",
  • "estimated_age_months": 36,
  • "estimated_age_reasons": "Reasons for the age estimate",
  • "estimated_age_timestamp": "2024-01-15T12:00:00.000Z",
  • "genealogy_result": { },
  • "genealogy_timestamp": "2024-01-15T12:00:00.000Z",
  • "muscle_wasting_risk": true,
  • "muscle_condition_reasons": "Prominent spine and sharp scapular borders are visible, indicating severe muscle wasting.",
  • "muscle_condition_timestamp": "2024-01-15T12:00:00.000Z",
  • "estimated_weight_kg": 12.5,
  • "estimated_size_classification": "medium",
  • "estimated_weight_reasons": "Reasons for the weight estimate",
  • "estimated_weight_timestamp": "2024-01-15T12:00:00.000Z",
  • "images": [
    ],
  • "created_at": "2024-01-15T12:00:00.000Z",
  • "updated_at": "2024-01-15T12:00:00.000Z"
}

List pets for the authenticated account

Authorizations:
x-api-key
query Parameters
limit
number [ 1 .. 100 ]
Default: 10
Example: limit=10

Maximum number of records to return per page

page
number >= 0
Default: 0
Example: page=0

Zero-indexed page number to return

order
string
Default: "ASC"
Enum: "ASC" "DESC" "RANDOM"

Sort order of returned records

species_id
string
Example: species_id=1

Filter results by a specific species identifier

breed_groups
string
Example: breed_groups=Toy,Hound

Comma-separated list of breed groups to include in the response

exclude_breed_groups
string
Example: exclude_breed_groups=Mixed

Comma-separated list of breed groups to exclude from the response

lang
string
Example: lang=it

Return translated fields when available for the requested language code

breed_id
string

Filter by breed identifier

sub_id
string

Filter by sub_id

external_owner_id
string <= 255 characters

Return only pets belonging to this owner ID from your own system (exact match)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Upload additional images for an existing pet

Authorizations:
x-api-key
path Parameters
petId
required
string

Pet identifier

Request Body schema: multipart/form-data
required
age_years
number

Age in years at the time images were taken

age_months
number

Age in months (0-11) at the time images were taken

poses
string

JSON string mapping file index to pose enum. E.g. {"0":"front","2":"back"}

description
string

Description of the pet at the time of the photos

images
Array of strings <binary> [ items <binary > ]

Image files to upload (max 20)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Upload an additional video for an existing pet

Authorizations:
x-api-key
path Parameters
petId
required
string

Pet identifier

Request Body schema: multipart/form-data
required
age_years
number

Age in years at the time the video was taken

age_months
number

Age in months (0-11) at the time the video was taken

description
string

Description of the pet at the time of the video

file
string <binary>

Video file to upload

Responses

Response samples

Content type
application/json
{
  • "id": "abc123",
  • "url": "https://cdn.example.com/images/abc123.jpg",
  • "pet_id": "pet123",
  • "width": 640,
  • "height": 480,
  • "pose": "front",
  • "pet_age_months": 18,
  • "age_years": 1,
  • "age_months": 6,
  • "description": "Playing in the snow",
  • "portrait_style_id": "studio",
  • "mime_type": "image/jpeg",
  • "review_status": "clean",
  • "upload_error": false,
  • "created_at": "2024-01-15T12:00:00.000Z"
}

List available portrait styles

Authorizations:
x-api-key

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a pet by ID

Authorizations:
x-api-key
path Parameters
petId
required
string

Pet identifier

Responses

Response samples

Content type
application/json
{
  • "id": "abc123",
  • "name": "Buddy",
  • "breed_id": "15",
  • "species_id": "2",
  • "description": "A friendly golden retriever",
  • "microchip_id": "123456789",
  • "sub_id": "sub_123",
  • "external_owner_id": "Xy7rT2kLmN9pQ4sV8wZ1aB3cD5e",
  • "country": "AU",
  • "date_of_birth": "2022-06-15",
  • "sex": "male",
  • "neuter_status": "neutered",
  • "body_condition_score": 5,
  • "body_condition_score_reasons": "Reasons for the score",
  • "body_condition_score_timestamp": "2024-01-15T12:00:00.000Z",
  • "estimated_age_months": 36,
  • "estimated_age_reasons": "Reasons for the age estimate",
  • "estimated_age_timestamp": "2024-01-15T12:00:00.000Z",
  • "genealogy_result": { },
  • "genealogy_timestamp": "2024-01-15T12:00:00.000Z",
  • "muscle_wasting_risk": true,
  • "muscle_condition_reasons": "Prominent spine and sharp scapular borders are visible, indicating severe muscle wasting.",
  • "muscle_condition_timestamp": "2024-01-15T12:00:00.000Z",
  • "estimated_weight_kg": 12.5,
  • "estimated_size_classification": "medium",
  • "estimated_weight_reasons": "Reasons for the weight estimate",
  • "estimated_weight_timestamp": "2024-01-15T12:00:00.000Z",
  • "images": [
    ],
  • "created_at": "2024-01-15T12:00:00.000Z",
  • "updated_at": "2024-01-15T12:00:00.000Z"
}

Update pet metadata

Authorizations:
x-api-key
path Parameters
petId
required
string

Pet identifier

Request Body schema: application/json
required
name
string

Name of the pet

breed_id
string

Breed identifier

species_id
string

Species identifier

description
string

Description of the pet

microchip_id
string

Microchip ID

sub_id
string

Subscription or other identifier

external_owner_id
string <= 255 characters

The pet owner's ID in your own system (e.g. a Firebase uid). Many pets can share one value; filter GET /pets by it to list one owner's pets. Send an empty string to clear it.

country
string

ISO 3166-1 alpha-2 country code for geographic and seasonal context

sex
string
Enum: "male" "female" "unknown"

Used to pick the sex-specific breed weight range in the calculators.

neuter_status
string
Enum: "neutered" "intact" "unknown"

Used to pick the neutered or intact energy factor in the calculators.

date_of_birth
string

ISO date for date of birth

age_years
number

Age in years

age_months
number

Age in months (0-11)

body_condition_score
number [ 1 .. 9 ]

Body Condition Score (1-9 scale)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "breed_id": "string",
  • "species_id": "string",
  • "description": "string",
  • "microchip_id": "string",
  • "sub_id": "string",
  • "external_owner_id": "string",
  • "country": "AU",
  • "sex": "female",
  • "neuter_status": "neutered",
  • "date_of_birth": "2022-06-15",
  • "age_years": 3,
  • "age_months": 6,
  • "body_condition_score": 5
}

Response samples

Content type
application/json
{
  • "id": "abc123",
  • "name": "Buddy",
  • "breed_id": "15",
  • "species_id": "2",
  • "description": "A friendly golden retriever",
  • "microchip_id": "123456789",
  • "sub_id": "sub_123",
  • "external_owner_id": "Xy7rT2kLmN9pQ4sV8wZ1aB3cD5e",
  • "country": "AU",
  • "date_of_birth": "2022-06-15",
  • "sex": "male",
  • "neuter_status": "neutered",
  • "body_condition_score": 5,
  • "body_condition_score_reasons": "Reasons for the score",
  • "body_condition_score_timestamp": "2024-01-15T12:00:00.000Z",
  • "estimated_age_months": 36,
  • "estimated_age_reasons": "Reasons for the age estimate",
  • "estimated_age_timestamp": "2024-01-15T12:00:00.000Z",
  • "genealogy_result": { },
  • "genealogy_timestamp": "2024-01-15T12:00:00.000Z",
  • "muscle_wasting_risk": true,
  • "muscle_condition_reasons": "Prominent spine and sharp scapular borders are visible, indicating severe muscle wasting.",
  • "muscle_condition_timestamp": "2024-01-15T12:00:00.000Z",
  • "estimated_weight_kg": 12.5,
  • "estimated_size_classification": "medium",
  • "estimated_weight_reasons": "Reasons for the weight estimate",
  • "estimated_weight_timestamp": "2024-01-15T12:00:00.000Z",
  • "images": [
    ],
  • "created_at": "2024-01-15T12:00:00.000Z",
  • "updated_at": "2024-01-15T12:00:00.000Z"
}

Delete a pet

Authorizations:
x-api-key
path Parameters
petId
required
string

Pet identifier

Responses

Get only the AI generated portraits for a pet

Authorizations:
x-api-key
path Parameters
petId
required
string

Pet identifier

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Analyse the body condition score (BCS) for a pet based on their images

Authorizations:
x-api-key
path Parameters
petId
required
string

Pet identifier

query Parameters
lang
string
Example: lang=en-GB

Two-letter language code for translated content

season
string
Example: season=winter

Explicit season override (winter, spring, summer, autumn)

country
string
Example: country=AU

ISO country code override

compare_version
string
Example: compare_version=v1

A previously generated prompt version to include alongside the current result (e.g. v1). Only returns if a cached result exists for that version.

request_review
boolean
Example: request_review=true

Send this result to a vet even if the model is confident. Results with low confidence go to a vet automatically.

Responses

Response samples

Content type
application/json
{
  • "score": 5,
  • "reasons": "The ribs are easily felt without excess fat covering. The waist is easily observed behind ribs when viewed from above.",
  • "condition_flags": [
    ],
  • "breed_predispositions": [
    ],
  • "confidence": 4,
  • "confidence_reason": "All key anatomical landmarks clearly visible across multiple images.",
  • "prompt_version": "v1",
  • "generated_at": "2024-01-15T12:00:00.000Z",
  • "comparison": {
    },
  • "review": {
    }
}

Estimate the age of a pet based on their images

Authorizations:
x-api-key
path Parameters
petId
required
string

Pet identifier

query Parameters
lang
string

Two-letter language code for translated content

Responses

Response samples

Content type
application/json
{
  • "age_months": 36,
  • "reasons": "Teeth show mild tartar accumulation typical of a 3 year old. Coat is still vibrant with no typical signs of greying around the muzzle. Eyes are clear.",
  • "plausible_range": "12-18 months",
  • "life_stage": "Adult",
  • "generated_at": "2024-01-15T12:00:00.000Z"
}

Analyze genealogy/breed from all pet images

Authorizations:
x-api-key
path Parameters
petId
required
string

Pet identifier

query Parameters
lang
string

Two-letter language code for translated content

Responses

Evaluate Muscle Condition from all pet images as a wasting risk flag

Authorizations:
x-api-key
path Parameters
petId
required
string

Pet identifier

query Parameters
lang
string

Two-letter language code for translated content

Responses

Response samples

Content type
application/json
{
  • "wasting_risk_flag": true,
  • "reasons": "Prominent spine and sharp scapular borders are visible, indicating severe muscle wasting.",
  • "generated_at": "2024-01-15T12:00:00.000Z"
}

Estimate weight and size for a pet based on photos

Authorizations:
x-api-key
path Parameters
petId
required
string

Pet identifier

query Parameters
lang
string
Example: lang=en-GB

Two-letter language code for translated content

season
string
Example: season=winter

Explicit season override (winter, spring, summer, autumn)

country
string
Example: country=AU

ISO country code override

Responses

Response samples

Content type
application/json
{
  • "weight_kg": 12.5,
  • "size_classification": "medium",
  • "reasons": "Based on the proportions relative to common household objects and the apparent bone structure typical of a beagle mix, the pet appears to be in the medium weight range.",
  • "generated_at": "2024-01-15T12:00:00.000Z"
}

Get personalised health tips for a pet based on their images and health scores

Returns a blend of breed-standard seeded tips (filtered by primary breed) and AI-generated personalised tips from Gemini. Results are cached per pet per request signature and invalidated when new images are uploaded. Requires at least one image to be uploaded to the pet. Running genealogy, body-condition-score, and muscle-condition-score first will produce more personalised AI tips.

Authorizations:
x-api-key
path Parameters
petId
required
string

Pet identifier

query Parameters
lang
string
Example: lang=en

Two-letter language code for translated content

include_seeded
boolean
Default: true

Include breed-standard seeded tips (default: true)

include_sources
boolean
Default: false

Include source URLs on breed-standard tips (default: false)

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "generated_at": "2026-04-29T10:00:00.000Z"
}

Generate an AI portrait for a pet

Authorizations:
x-api-key
path Parameters
petId
required
string

Pet identifier

Request Body schema: application/json
required
style
required
string

The style of portrait to generate (e.g., studio, pack_leader, birthday_party)

model
string

The codename of the model to use for generation (e.g., rembrandt, picasso, da-vinci, van-gogh, warhol)

image_ids
Array of strings

Optional list of specific image IDs to use as references. Must belong to the same pet.

Responses

Request samples

Content type
application/json
{
  • "style": "studio",
  • "model": "rembrandt",
  • "image_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "abc123",
  • "url": "https://cdn.example.com/images/abc123.jpg",
  • "pet_id": "pet123",
  • "width": 640,
  • "height": 480,
  • "pose": "front",
  • "pet_age_months": 18,
  • "age_years": 1,
  • "age_months": 6,
  • "description": "Playing in the snow",
  • "portrait_style_id": "studio",
  • "mime_type": "image/jpeg",
  • "review_status": "clean",
  • "upload_error": false,
  • "created_at": "2024-01-15T12:00:00.000Z"
}

List vet reviews of this pet's body condition scores, newest first

Authorizations:
x-api-key
path Parameters
petId
required
string

Pet identifier

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Record a vet visit, with its clinical notes and measurements

One call writes the visit, its items and its observations in a single transaction. Reposting the same external_id for the same source_system updates that visit rather than creating a second one, so retries are safe.

Authorizations:
x-api-key
path Parameters
petId
required
string

Pet identifier

Request Body schema: application/json
required
occurred_at
required
string

When the visit happened. Required, never defaulted, rejected if in the future or before the pet was born.

occurred_at_precision
string
Enum: "exact" "day" "month" "year"

Defaults to exact for a full timestamp, day for a date-only value.

ended_at
string
timezone
string

IANA zone

visit_type
string
Enum: "consultation" "vaccination" "surgery" "emergency" "follow_up" "lab_only" "other"
reason
string

Presenting complaint, verbatim.

summary
string
clinic_name
string
clinic_external_id
string
clinician_name
string
source
string
Enum: "api" "pms_api" "clinic_portal" "owner_upload" "document_extraction" "migration"
source_system
string
external_id
string

Your own id for this visit. Reposting the same one returns the existing visit rather than creating a second, so retries are safe.

status
string
Enum: "draft" "complete" "amended"
consent_status
string
Enum: "obtained" "not_obtained" "not_required" "not_recorded"
consent_reference
string
verification_status
string
Enum: "unverified" "vet_verified" "disputed"

Whether a vet has confirmed this record. This is the caller's assertion about their own data, not a claim we validate, so treat it as provenance rather than proof.

verified_by
string

Who verified it, when verification_status says one did.

Array of objects (CreateClinicalItemDto)

Notes and other dated records, written in the same transaction as the visit.

Array of objects (CreateObservationDto)

Measurements taken at this visit.

Responses

Request samples

Content type
application/json
{
  • "occurred_at": "2026-09-05T09:30:00Z",
  • "occurred_at_precision": "exact",
  • "ended_at": "string",
  • "timezone": "Europe/London",
  • "visit_type": "consultation",
  • "reason": "string",
  • "summary": "string",
  • "clinic_name": "Wolfe Vets, Harrogate",
  • "clinic_external_id": "string",
  • "clinician_name": "Karyn Kanowski",
  • "source": "api",
  • "source_system": "happier_vet_portal",
  • "external_id": "string",
  • "status": "draft",
  • "consent_status": "obtained",
  • "consent_reference": "string",
  • "verification_status": "unverified",
  • "verified_by": "Karyn Kanowski",
  • "items": [
    ],
  • "observations": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "pet_id": "string",
  • "occurred_at": "2019-08-24T14:15:22Z",
  • "occurred_at_precision": "string",
  • "ended_at": "2019-08-24T14:15:22Z",
  • "timezone": "string",
  • "visit_type": "string",
  • "reason": "string",
  • "summary": "string",
  • "clinic_name": "string",
  • "clinician_name": "string",
  • "source": "string",
  • "source_system": "string",
  • "external_id": "string",
  • "status": "string",
  • "consent_status": "string",
  • "verification_status": "string",
  • "verified_by": "string",
  • "verified_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "items": [
    ],
  • "observations": [
    ]
}

List a pet's visits, most recent first

Authorizations:
x-api-key
path Parameters
petId
required
string

Pet identifier

query Parameters
limit
number [ 1 .. 100 ]
Default: 10
Example: limit=10

Maximum number of records to return per page

page
number >= 0
Default: 0
Example: page=0

Zero-indexed page number to return

order
string
Default: "ASC"
Enum: "ASC" "DESC" "RANDOM"

Sort order of returned records

species_id
string
Example: species_id=1

Filter results by a specific species identifier

breed_groups
string
Example: breed_groups=Toy,Hound

Comma-separated list of breed groups to include in the response

exclude_breed_groups
string
Example: exclude_breed_groups=Mixed

Comma-separated list of breed groups to exclude from the response

lang
string
Example: lang=it

Return translated fields when available for the requested language code

from
string
Example: from=2026-01-01T00:00:00Z

Only visits that occurred on or after this time.

to
string

Only visits that occurred on or before this time.

visit_type
string
Enum: "consultation" "vaccination" "surgery" "emergency" "follow_up" "lab_only" "other"

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a single visit with its notes and measurements

Authorizations:
x-api-key
path Parameters
petId
required
string

Pet identifier

visitId
required
string

Visit identifier

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "pet_id": "string",
  • "occurred_at": "2019-08-24T14:15:22Z",
  • "occurred_at_precision": "string",
  • "ended_at": "2019-08-24T14:15:22Z",
  • "timezone": "string",
  • "visit_type": "string",
  • "reason": "string",
  • "summary": "string",
  • "clinic_name": "string",
  • "clinician_name": "string",
  • "source": "string",
  • "source_system": "string",
  • "external_id": "string",
  • "status": "string",
  • "consent_status": "string",
  • "verification_status": "string",
  • "verified_by": "string",
  • "verified_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "items": [
    ],
  • "observations": [
    ]
}

Record a pet's exercise band, weight or body condition score

For inputs collected outside a vet visit. exercise_band is the actual daily exercise (lt_30, 30_60 or gt_60 minutes). The calculators read the latest value of each.

Authorizations:
x-api-key
path Parameters
petId
required
string

Pet identifier

Request Body schema: application/json
required
observation_type
required
string
Enum: "exercise_band" "weight" "bcs"
value_text
string

For exercise_band: lt_30, 30_60 or gt_60 minutes a day of actual exercise, not intended.

value_numeric
number

For weight (kg) or bcs.

unit
string
Enum: "kg" "score"

kg for weight, score for bcs.

scale
string

Required for bcs: '9' for a 1-9 score.

observed_at
string

When it was observed. Defaults to now. Rejected if in the future.

method
string
Enum: "owner_report" "scale" "vet_manual_count"

Defaults to owner_report.

Responses

Request samples

Content type
application/json
{
  • "observation_type": "exercise_band",
  • "value_text": "30_60",
  • "value_numeric": 24.5,
  • "unit": "kg",
  • "scale": "9",
  • "observed_at": "string",
  • "method": "owner_report"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "pet_id": "string",
  • "observation_type": "weight",
  • "value_text": "string",
  • "value_numeric": 0,
  • "unit": "string",
  • "scale": "string",
  • "observed_at": "2019-08-24T14:15:22Z",
  • "method": "string"
}

Calculators

Daily calories and weight-loss plans from a weight, a breed or a pet.

Daily energy requirement (RER and MER) for a weight, breed or pet

RER = 70 x kg^0.75; MER = RER x a life stage factor (AAHA 2021 Nutrition and Weight Management Guidelines). For adult dogs the factor follows actual daily exercise in three bands; those factors are provisional. Send food energy to get portions in cups, cans or grams. Calories are per day. Results are estimates to discuss with a vet.

Authorizations:
x-api-key
Request Body schema: application/json
required
pet_id
string

A pet on your account. Its latest weight, BCS, exercise band, age and breed are used for anything you don't send.

breed_id
string

A breed, for its standard weight range when no weight or pet is given.

weight_kg
number

Current weight in kg.

species
string
Enum: "dog" "cat"

Defaults to the pet's or breed's species, then this API's.

life_stage
string
Enum: "growth" "adult" "senior"

growth for puppies and kittens. Derived from age when not sent (under 12 months is growth).

age_months
number

Age in months. Needed for a growing dog.

sex
string
Enum: "male" "female" "unknown"

Picks the sex-specific breed weight range.

bcs
number

Body condition score, 1-9.

neuter_status
string
Enum: "neutered" "intact" "unknown"

Unknown spans both neutered and intact ranges.

exercise_band
string
Enum: "lt_30" "30_60" "gt_60"

Actual daily exercise, not intended: under 30, 30 to 60, or over 60 minutes. Adult dogs only. Without it, adult dogs get a result for each band.

input_policy
string
Default: "any"
Enum: "any" "measured_only"

measured_only refuses inputs estimated from photos. Clinician tools and insurers will usually want it.

lang
string

Language for message text. en-GB only today.

reproductive
string
Default: "none"
Enum: "none" "gestation" "lactation"
factor_choice
string
Default: "mid"
Enum: "low" "mid" "high"
kcal_per_cup
number

Food energy per cup, for portions in cups.

kcal_per_can
number

Food energy per can, for portions in cans.

kcal_per_kg
number

Food energy per kg, for portions in grams.

Responses

Request samples

Content type
application/json
{
  • "pet_id": "string",
  • "breed_id": "string",
  • "weight_kg": 20,
  • "species": "dog",
  • "life_stage": "growth",
  • "age_months": 30,
  • "sex": "male",
  • "bcs": 6,
  • "neuter_status": "neutered",
  • "exercise_band": "lt_30",
  • "input_policy": "any",
  • "lang": "en-GB",
  • "reproductive": "none",
  • "factor_choice": "low",
  • "kcal_per_cup": 350,
  • "kcal_per_can": 380,
  • "kcal_per_kg": 3700
}

Weight-loss plan: daily kcal at ideal weight, staged by body condition band

Ideal weight from a vet-entered value, a weight recorded at BCS 5, the BCS (each point above 5 is about 10% overweight, AAHA 2014) or the breed range. Feeds RER at ideal weight x 1.0 for dogs and x 0.8 for cats (AAHA 2021). Staged mode steps one band at a time; durations and rechecks follow AAHA 2014 (1-2% a week for dogs, 0.5-2% for cats). Every response has a status. BCS 1-2 (very_lean) returns an urgent vet referral and no numbers; BCS 3 (below_ideal) returns a feeding target for ideal weight with a routine vet check; BCS 4-5 (at_ideal) returns the maintenance target.

Authorizations:
x-api-key
Request Body schema: application/json
required
pet_id
string

A pet on your account. Its latest weight, BCS, exercise band, age and breed are used for anything you don't send.

breed_id
string

A breed, for its standard weight range when no weight or pet is given.

weight_kg
number

Current weight in kg.

species
string
Enum: "dog" "cat"

Defaults to the pet's or breed's species, then this API's.

life_stage
string
Enum: "growth" "adult" "senior"

growth for puppies and kittens. Derived from age when not sent (under 12 months is growth).

age_months
number

Age in months. Needed for a growing dog.

sex
string
Enum: "male" "female" "unknown"

Picks the sex-specific breed weight range.

bcs
number

Body condition score, 1-9.

neuter_status
string
Enum: "neutered" "intact" "unknown"

Unknown spans both neutered and intact ranges.

exercise_band
string
Enum: "lt_30" "30_60" "gt_60"

Actual daily exercise, not intended: under 30, 30 to 60, or over 60 minutes. Adult dogs only. Without it, adult dogs get a result for each band.

input_policy
string
Default: "any"
Enum: "any" "measured_only"

measured_only refuses inputs estimated from photos. Clinician tools and insurers will usually want it.

lang
string

Language for message text. en-GB only today.

ideal_weight_kg
number

Vet-entered ideal weight in kg. Wins over BCS and breed.

mode
string
Default: "staged"
Enum: "staged" "direct"

staged steps down one body condition band at a time; direct feeds for ideal weight straight away.

Responses

Request samples

Content type
application/json
{
  • "pet_id": "string",
  • "breed_id": "string",
  • "weight_kg": 20,
  • "species": "dog",
  • "life_stage": "growth",
  • "age_months": 30,
  • "sex": "male",
  • "bcs": 6,
  • "neuter_status": "neutered",
  • "exercise_band": "lt_30",
  • "input_policy": "any",
  • "lang": "en-GB",
  • "ideal_weight_kg": 30,
  • "mode": "staged"
}

Breeds

Breed data: characteristics, weights, groups and registered colours.

List the registered colour/pattern variants for a breed

Returns the palette of colour/pattern variants valid for this breed - breed-specific variants (e.g. Birman colourpoints) plus any that apply species-wide.

Authorizations:
x-api-key
path Parameters
id
required
string
Example: birm

Identifier of the breed

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Search breeds by name

Authorizations:
x-api-key
query Parameters
limit
number [ 1 .. 100 ]
Default: 10
Example: limit=10

Maximum number of results to return (default 10)

page
number >= 0
Default: 0
Example: page=0

Zero-based page index

order
string
Default: "ASC"
Enum: "ASC" "DESC" "RANDOM"

Sort order of returned records

species_id
string
Example: species_id=1

Filter breeds by species identifier

breed_groups
string
Example: breed_groups=Toy,Hound

Comma-separated list of breed groups to include (case-insensitive)

exclude_breed_groups
string
Example: exclude_breed_groups=Mixed

Comma-separated list of breed groups to exclude (case-insensitive)

lang
string
Example: lang=en

Two-letter language code for translated content

q
string [ 1 .. 30 ] characters
Example: q=sib

Partial name to match

venom_code
string

Filter by VeNoM code. Matches any VeNoM entry belonging to the breed, not just its primary one (a breed can have multiple, e.g. colour/coat variants).

extinct
boolean

Filter by extinction status. If omitted, results are not filtered by extinction status.

Responses

Response samples

Content type
application/json
[
  • { }
]

List breeds

Authorizations:
x-api-key
query Parameters
limit
number [ 1 .. 1000 ]
Default: 1000
Example: limit=1000

Maximum number of results to return (default 1000)

page
number >= 0
Default: 0
Example: page=0

Zero-based page index

order
string
Enum: "ASC" "DESC" "RANDOM"

Sort order of the results

species_id
string
Example: species_id=1

Filter breeds by species identifier

breed_groups
string
Example: breed_groups=Toy,Hound

Comma-separated list of breed groups to include (case-insensitive)

exclude_breed_groups
string
Example: exclude_breed_groups=Mixed

Comma-separated list of breed groups to exclude (case-insensitive)

lang
string
Example: lang=en

Two-letter language code for translated content

extinct
boolean
Default: false

Filter by extinction status (true for extinct, false for living). Defaults to false.

venom_code
string

Filter by VeNoM code. Matches any VeNoM entry belonging to the breed, not just its primary one (a breed can have multiple, e.g. colour/coat variants).

Responses

Response samples

Content type
application/json
[
  • { }
]

List available breed groups

Authorizations:
x-api-key
query Parameters
species_id
string

Filter breed groups by species identifier

Responses

Response samples

Content type
application/json
[
  • "string"
]

Retrieve a breed by identifier

Authorizations:
x-api-key
path Parameters
id
required
string
Example: 115

Breed identifier

query Parameters
lang
string
Example: lang=en

Two-letter language code for translated content

Responses

Response samples

Content type
application/json
{ }

Images

Search public images, upload your own and check their processing.

Retrieve an image by id

Authorizations:
x-api-key
path Parameters
id
required
string
Example: abc123

Identifier of the image

Responses

Response samples

Content type
application/json
{
  • "species_id": "1",
  • "id": "abc123",
  • "url": "https://cdn.example.com/images/abc123.jpg",
  • "width": 640,
  • "height": 480,
  • "sub_id": "natural",
  • "breeds": [
    ],
  • "categories": [
    ],
  • "colours": [
    ],
  • "tags": [
    ],
  • "age_months": 14,
  • "unsafe_reasons": [
    ],
  • "created_at": "2023-10-20T12:34:56.000Z",
  • "credit_name": "aden@thatapicompany.com",
  • "credit_url": "https://example.com/photo/123",
  • "review": {
    },
  • "childImages": [
    ]
}

Delete an uploaded image

Authorizations:
x-api-key
path Parameters
id
required
string
Example: abc12345

Identifier of the image

Responses

Get the latest breed identification labels for an image

Authorizations:
x-api-key
path Parameters
id
required
string
Example: abc123

Identifier of the image

Responses

Upload an image

Uploads an image for processing. This is an opaque asynchronous operation. The response includes a links.status URL which SHOULD be polled to check the progress of the image analysis and optimization.

Authorizations:
x-api-key
Request Body schema:
required

Image upload payload. Provide either a binary file or a base64 encoded string.

file
string <binary>

Binary image file when uploading using multipart/form-data

type
required
string
Enum: "base64" "FILE"

Type of upload being performed

image
string

Base64 encoded image data when uploading without a file

height
number

Optional resize height in pixels

width
number

Optional resize width in pixels

sub_id
string

Optional sub identifier associated with the image

Responses

Request samples

Content type
No sample

Response samples

Content type
application/json
{
  • "species_id": "1",
  • "id": "abc123",
  • "url": "https://cdn.example.com/images/abc123.jpg",
  • "width": 640,
  • "height": 480,
  • "sub_id": "natural",
  • "breeds": [
    ],
  • "categories": [
    ],
  • "colours": [
    ],
  • "tags": [
    ],
  • "age_months": 14,
  • "unsafe_reasons": [
    ],
  • "created_at": "2023-10-20T12:34:56.000Z",
  • "credit_name": "aden@thatapicompany.com",
  • "credit_url": "https://example.com/photo/123",
  • "review": {
    },
  • "childImages": [
    ]
}

Get the processing status of an uploaded image

Returns the current processing status of the image. Clients should poll this endpoint until the status changes from to_be_reviewed to clean or unsafe, then labelled.

Authorizations:
x-api-key
path Parameters
id
required
string
Example: abc12345

Identifier of the image

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "status": "to_be_reviewed",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Upload an image and wait for analysis to complete

This endpoint uploads an image and waits for analysis to complete before returning the result. The response includes the analysis status and any detected tags.

Authorizations:
x-api-key
Request Body schema:
required

Image upload payload. Provide either a binary file or a base64 encoded string.

file
string <binary>

Binary image file when uploading using multipart/form-data

type
required
string
Enum: "base64" "FILE"

Type of upload being performed

image
string

Base64 encoded image data when uploading without a file

height
number

Optional resize height in pixels

width
number

Optional resize width in pixels

sub_id
string

Optional sub identifier associated with the image

auto_crop
boolean
Default: true

Automatically crop and detect multiple animals within the image. This will create a child image for each in the response.

Responses

Request samples

Content type
No sample

Response samples

Content type
application/json
{
  • "species_id": "1",
  • "id": "abc123",
  • "url": "https://cdn.example.com/images/abc123.jpg",
  • "width": 640,
  • "height": 480,
  • "sub_id": "natural",
  • "breeds": [
    ],
  • "categories": [
    ],
  • "colours": [
    ],
  • "tags": [
    ],
  • "age_months": 14,
  • "unsafe_reasons": [
    ],
  • "created_at": "2023-10-20T12:34:56.000Z",
  • "credit_name": "aden@thatapicompany.com",
  • "credit_url": "https://example.com/photo/123",
  • "review": {
    },
  • "childImages": [
    ]
}

Request an image to be made public

Authorizations:
x-api-key
path Parameters
imageId
required
string

Image ID

Request Body schema: application/json
required
request_message
string <= 500 characters

Optional message to the admin explaining why this image should be public

Responses

Request samples

Content type
application/json
{
  • "request_message": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "image_id": "string",
  • "account_id": "string",
  • "status": "pending",
  • "request_message": "string",
  • "admin_message": "string",
  • "actioned_by_email": "string",
  • "actioned_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "image": { }
}

Cancel a pending public request

Authorizations:
x-api-key
path Parameters
imageId
required
string

Image ID

Responses

Get the public request status for an image

Authorizations:
x-api-key
path Parameters
imageId
required
string

Image ID

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "image_id": "string",
  • "account_id": "string",
  • "status": "pending",
  • "request_message": "string",
  • "admin_message": "string",
  • "actioned_by_email": "string",
  • "actioned_at": "2019-08-24T14:15:22Z",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "image": { }
}

Health Tips

Vet-reviewed health tips by breed.

Get a list of health tips

Retrieve health tips with optional filtering by breed or species, and pagination support.

Authorizations:
x-api-key
query Parameters
limit
number [ 1 .. 100 ]
Example: limit=10

Number of health tips to return

offset
number >= 0
Example: offset=0

Number of health tips to skip for pagination

breed_id
string
Example: breed_id=abys

Filter health tips by breed ID

species_id
string
Example: species_id=dog

Filter health tips by species ID

include_sources
boolean
Example: include_sources=false

Include sources in the response

lang
string
Example: lang=en

Two-letter language code for translated content

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get health tips for a specific breed

Retrieve all health tips for a specific breed with pagination support.

Authorizations:
x-api-key
path Parameters
breedId
required
string
Example: 115

The breed identifier

query Parameters
limit
number
Example: limit=10

Number of health tips to return (1-100)

offset
number
Example: offset=0

Number of health tips to skip

include_sources
boolean
Example: include_sources=false

Include sources in the response

lang
string
Example: lang=en

Two-letter language code for translated content

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a health tip by ID

Retrieve a specific health tip by its unique identifier.

Authorizations:
x-api-key
path Parameters
id
required
string
Example: 1

The health tip ID

query Parameters
include_sources
boolean
Example: include_sources=false

Include sources in the response

lang
string
Example: lang=en

Two-letter language code for translated content

Responses

Response samples

Content type
application/json
{
  • "id": "aB3xY9mK12",
  • "title": "string",
  • "category": "string",
  • "description": "string",
  • "sources": [
    ],
  • "species_id": 1
}

Facts

Fact-checked breed and species facts.

Get a list of facts

Retrieve facts with optional filtering by breed or species, and pagination support.

Authorizations:
x-api-key
query Parameters
limit
number [ 1 .. 100 ]
Example: limit=10

Number of facts to return

offset
number >= 0
Example: offset=0

Number of facts to skip for pagination

breed_id
string
Example: breed_id=abys

Filter facts by breed ID

species_id
string
Example: species_id=dog

Filter facts by species ID

category
string
Example: category=fun

Filter facts by category (e.g. fun)

include_sources
boolean
Example: include_sources=false

Include source URLs in the response

lang
string
Example: lang=en

Two-letter language code for translated content

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a random fact

Retrieve a completely random fact from all available facts.

Authorizations:
x-api-key
query Parameters
include_sources
boolean
Example: include_sources=false

Include source URLs in the response

lang
string
Example: lang=en

Two-letter language code for translated content

Responses

Response samples

Content type
application/json
{
  • "id": "aB3xY9mK12",
  • "title": "The German Shepherd's 'Flying Trot'",
  • "fact": "The German Shepherd is known for its efficient 'flying trot,' a gait where all four feet are momentarily off the ground, allowing for exceptional speed and endurance. This gait, favored in herding and police work, is a result of specific angulation in their hindquarters, enabling them to cover vast distances with minimal energy expenditure. The correct angulation is vital for breed standard and working ability.",
  • "source_urls": [],
  • "slug": "the-german-shepherds-flying-trot",
  • "category": "fun",
  • "species_id": 1
}

Get facts by breed

Retrieve all facts for a specific breed with pagination support.

Authorizations:
x-api-key
path Parameters
breedId
required
string
Example: 115

The breed identifier

query Parameters
limit
number
Example: limit=10

Number of facts to return (1-100)

offset
number
Example: offset=0

Number of facts to skip

include_sources
boolean
Example: include_sources=false

Include source URLs in the response

lang
string
Example: lang=en

Two-letter language code for translated content

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a random fact for a specific breed

Retrieve a random fact for the specified breed.

Authorizations:
x-api-key
path Parameters
breedId
required
string
Example: 115

The breed identifier

query Parameters
include_sources
boolean
Example: include_sources=false

Include source URLs in the response

lang
string
Example: lang=en

Two-letter language code for translated content

Responses

Response samples

Content type
application/json
{
  • "id": "aB3xY9mK12",
  • "title": "The German Shepherd's 'Flying Trot'",
  • "fact": "The German Shepherd is known for its efficient 'flying trot,' a gait where all four feet are momentarily off the ground, allowing for exceptional speed and endurance. This gait, favored in herding and police work, is a result of specific angulation in their hindquarters, enabling them to cover vast distances with minimal energy expenditure. The correct angulation is vital for breed standard and working ability.",
  • "source_urls": [],
  • "slug": "the-german-shepherds-flying-trot",
  • "category": "fun",
  • "species_id": 1
}

Get a random fact for a specific species

Retrieve a random fact for the specified species.

Authorizations:
x-api-key
path Parameters
speciesId
required
string
Example: 2

The species identifier

query Parameters
include_sources
boolean
Example: include_sources=false

Include source URLs in the response

lang
string
Example: lang=en

Two-letter language code for translated content

Responses

Response samples

Content type
application/json
{
  • "id": "aB3xY9mK12",
  • "title": "The German Shepherd's 'Flying Trot'",
  • "fact": "The German Shepherd is known for its efficient 'flying trot,' a gait where all four feet are momentarily off the ground, allowing for exceptional speed and endurance. This gait, favored in herding and police work, is a result of specific angulation in their hindquarters, enabling them to cover vast distances with minimal energy expenditure. The correct angulation is vital for breed standard and working ability.",
  • "source_urls": [],
  • "slug": "the-german-shepherds-flying-trot",
  • "category": "fun",
  • "species_id": 1
}

Get a fact by ID

Retrieve a specific fact by its unique identifier.

Authorizations:
x-api-key
path Parameters
id
required
string
Example: 1

The fact ID

query Parameters
include_sources
boolean
Example: include_sources=false

Include source URLs in the response

lang
string
Example: lang=en

Two-letter language code for translated content

Responses

Response samples

Content type
application/json
{
  • "id": "aB3xY9mK12",
  • "title": "The German Shepherd's 'Flying Trot'",
  • "fact": "The German Shepherd is known for its efficient 'flying trot,' a gait where all four feet are momentarily off the ground, allowing for exceptional speed and endurance. This gait, favored in herding and police work, is a result of specific angulation in their hindquarters, enabling them to cover vast distances with minimal energy expenditure. The correct angulation is vital for breed standard and working ability.",
  • "source_urls": [],
  • "slug": "the-german-shepherds-flying-trot",
  • "category": "fun",
  • "species_id": 1
}

Breed Bans

Breed legislation by country and by breed.

List countries with breed legislation

Authorizations:
x-api-key
query Parameters
species_id
string

Filter by species identifier

animal_type
string

Filter by animal type: dog or cat

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get breed bans and legislation by country

Returns all breed bans, restrictions, and characteristic-based legislation for a country. If the country does not have national-level legislation, returns jurisdiction-level (state/city/canton) laws instead.

Authorizations:
x-api-key
query Parameters
limit
number [ 1 .. 100 ]
Default: 10
Example: limit=10

Maximum number of records to return per page

page
number >= 0
Default: 0
Example: page=0

Zero-indexed page number to return

order
string
Default: "ASC"
Enum: "ASC" "DESC" "RANDOM"

Sort order of returned records

species_id
string
Example: species_id=2

Filter by species identifier

breed_groups
string
Example: breed_groups=Toy,Hound

Comma-separated list of breed groups to include in the response

exclude_breed_groups
string
Example: exclude_breed_groups=Mixed

Comma-separated list of breed groups to exclude from the response

lang
string
Example: lang=it

Return translated fields when available for the requested language code

country
required
string
Example: country=AU

ISO 3166-1 alpha-2 country code

legislation_type
string
Example: legislation_type=breed_specific

Filter: breed_specific, characteristic_based, behavior_based, hybrid

approach
string
Example: approach=ban

Filter: ban, restriction, permit, approved_list

jurisdiction
string
Example: jurisdiction=Victoria

Filter to a specific jurisdiction within the country

Responses

Response samples

Content type
application/json
{
  • "country": { },
  • "legislation": [
    ],
  • "jurisdictions": [
    ]
}

Get all bans for a specific breed globally

Returns every country and jurisdiction where this breed is banned, restricted, or requires a permit.

Authorizations:
x-api-key
path Parameters
breedId
required
string
Example: 15

Canonical breed identifier

query Parameters
species_id
string
Example: species_id=2

Filter by species identifier

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Webhooks

Get results pushed to your server when they are ready.

Create a new webhook endpoint

Authorizations:
x-api-key
Request Body schema: application/json
required
url
required
string

The URL to deliver webhooks to

description
string

Description of what this endpoint is for

enabled_events
required
Array of strings

List of event types to subscribe to

Responses

Request samples

Content type
application/json
{}

List all webhook endpoints

Authorizations:
x-api-key

Responses

Response samples

Content type
application/json
[]

List available webhook topics

Authorizations:
x-api-key

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get a specific webhook endpoint

Authorizations:
x-api-key
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "123e4567-e89b-12d3-a456-426614174000",
  • "url": "https://example.com/webhook",
  • "enabled_events": [
    ],
  • "description": "Production Webhook",
  • "status": "enabled",
  • "created_at": "2023-01-01T00:00:00Z"
}

Delete a webhook endpoint

Authorizations:
x-api-key
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "success": true
}

Issue a new signing secret for this endpoint. The old one stops working immediately.

Authorizations:
x-api-key
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "123e4567-e89b-12d3-a456-426614174000",
  • "signing_secret": "whsec_3f1c..."
}

Accounts

Your quota, enabled features and analysis capabilities.

Get enabled feature flags for the current account

Authorizations:
x-api-key

Responses

Response samples

Content type
application/json
[
  • "string"
]

Get current upload quota usage and remaining limit

Authorizations:
x-api-key

Responses

Response samples

Content type
application/json
{
  • "quota": 10,
  • "usage": 3,
  • "remaining": 7
}

List the analysis capabilities on this account and whether each is switched on

Authorizations:
x-api-key

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Switch a capability off (or back on) for this account. Off makes its endpoints return 403.

Authorizations:
x-api-key
path Parameters
capabilityId
required
string
Example: portraits
Request Body schema: application/json
required
enabled
required
boolean

Responses

Request samples

Content type
application/json
{
  • "enabled": false
}

Response samples

Content type
application/json
{
  • "id": "portraits",
  • "name": "Pet portraits",
  • "description": "Stylised artwork generated from the pet's photos.",
  • "endpoints": [
    ],
  • "enabled": false,
  • "updated_at": "2026-09-30T02:00:00.000Z"
}

Votes

Votes on images.

List votes for the authenticated user

Authorizations:
x-api-key
query Parameters
limit
number [ 1 .. 100 ]
Default: 10
Example: limit=10

Maximum number of results to return (default 10)

page
number >= 0
Default: 0
Example: page=0

Zero-based page index

order
string
Default: "ASC"
Enum: "ASC" "DESC" "RANDOM"

Sort order of returned records

species_id
string
Example: species_id=1

Filter results by a specific species identifier

breed_groups
string
Example: breed_groups=Toy,Hound

Comma-separated list of breed groups to include in the response

exclude_breed_groups
string
Example: exclude_breed_groups=Mixed

Comma-separated list of breed groups to exclude from the response

lang
string
Example: lang=it

Return translated fields when available for the requested language code

sub_id
string

Filter by sub identifier

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a vote

Authorizations:
x-api-key
Request Body schema: application/json
required
image_id
required
string

Identifier of the image to vote on

sub_id
string

Optional sub identifier

value
required
number

Vote value (1 for upvote, -1 for downvote)

country_code
string

Country code

ip_address
string

IP Address

Responses

Request samples

Content type
application/json
{
  • "image_id": "abc123",
  • "sub_id": "my-user-123",
  • "value": 1,
  • "country_code": "US",
  • "ip_address": "string"
}

Response samples

Content type
application/json
{
  • "id": 1120951,
  • "image_id": "asf2",
  • "sub_id": "my-user-1234",
  • "created_at": "2023-10-28T17:29:28.000Z",
  • "value": 1,
  • "country_code": "AU",
  • "image": {
    }
}

Get a vote by ID

Authorizations:
x-api-key
path Parameters
vote_id
required
number

Responses

Response samples

Content type
application/json
{
  • "id": 1120951,
  • "image_id": "asf2",
  • "sub_id": "my-user-1234",
  • "created_at": "2023-10-28T17:29:28.000Z",
  • "value": 1,
  • "country_code": "AU",
  • "image": {
    }
}

Favourites

Saved favourite images.

List favourites for the authenticated user

Authorizations:
x-api-key
query Parameters
limit
number [ 1 .. 100 ]
Default: 10
Example: limit=10

Maximum number of results to return (default 10)

page
number >= 0
Default: 0
Example: page=0

Zero-based page index

order
string
Enum: "ASC" "DESC" "RANDOM"

Sort order of the results

species_id
string
Example: species_id=1

Filter results by a specific species identifier

breed_groups
string
Example: breed_groups=Toy,Hound

Comma-separated list of breed groups to include in the response

exclude_breed_groups
string
Example: exclude_breed_groups=Mixed

Comma-separated list of breed groups to exclude from the response

lang
string
Example: lang=it

Return translated fields when available for the requested language code

account_id
string
Example: account_id=account-123

Filter favourites by account identifier

image_id
string
Example: image_id=abc123

Filter by image identifier

sub_id
string
Example: sub_id=my-list

Filter by sub identifier

is_deleted
boolean
Default: false
Example: is_deleted=false

Include deleted favourites

attach_image
boolean
Default: false
Example: attach_image=true

Include image details in the response

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create a favourite for the authenticated user

Authorizations:
x-api-key
Request Body schema: application/json
required

Favourite payload

image_id
required
string

Identifier of the image to favourite

sub_id
string

Optional sub identifier to group favourites

client_ip_address
string

Client IP address used for auditing

ip_address
string

IP Address

country_code
string

ISO Alpha-2 country code derived from the request

Responses

Request samples

Content type
application/json
{
  • "image_id": "abc123",
  • "sub_id": "my-list",
  • "client_ip_address": "192.0.2.1",
  • "ip_address": "127.0.0.1",
  • "country_code": "US"
}

Response samples

Content type
application/json
{
  • "id": 232413577,
  • "image_id": "asf2",
  • "sub_id": "my-user-1234",
  • "created_at": "2023-10-28T17:39:28.000Z",
  • "image": {
    }
}

Retrieve a favourite by identifier

Authorizations:
x-api-key
path Parameters
id
required
string
Example: 1

Favourite identifier

Responses

Response samples

Content type
application/json
{
  • "id": 232413577,
  • "image_id": "asf2",
  • "sub_id": "my-user-1234",
  • "created_at": "2023-10-28T17:39:28.000Z",
  • "image": {
    }
}

Delete a favourite

Authorizations:
x-api-key
path Parameters
id
required
string
Example: 1

Favourite identifier

Responses

Response samples

Content type
application/json
{
  • "message": "SUCCESS"
}

Categories

Image categories.

Retrieve a category by identifier

Authorizations:
x-api-key
path Parameters
id
required
string
Example: 1

Identifier of the category

Responses

Response samples

Content type
application/json
{
  • "name": "Hats",
  • "species_id": "1",
  • "id": "5"
}

List categories

Authorizations:
x-api-key
query Parameters
limit
number [ 1 .. 100 ]
Default: 10
Example: limit=10

Maximum number of results to return (default 10)

page
number >= 0
Default: 0
Example: page=0

Zero-based page index

order
string
Enum: "ASC" "DESC" "RANDOM"

Sort order of the results

species_id
string
Example: species_id=1

Filter categories by species identifier

breed_groups
string
Example: breed_groups=Toy,Hound

Comma-separated list of breed groups to include in the response

exclude_breed_groups
string
Example: exclude_breed_groups=Mixed

Comma-separated list of breed groups to exclude from the response

lang
string
Example: lang=it

Return translated fields when available for the requested language code

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Sub IDs

The sub_id values your users have used, with counts.

Get detailed list of sub_ids used in the account along with counts representing usage activity

Authorizations:
x-api-key
query Parameters
limit
number

Limit the number of results returned (default 1000)

page
number

Page number for pagination (default 0)

start_date
string

Filter by start date (ISO 8601 string)

end_date
string

Filter by end date (ISO 8601 string)

Responses

Response samples

Content type
application/json
[
  • {
    }
]