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

TheDogAPI (1.6.4)

Download OpenAPI specification:Download

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

REST API documentation for the TheDogAPI created by ThatAPICompany. Documentation and tutorials available at https://docs.thedogapi.com

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

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",
  • "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",
  • "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",
  • "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",
  • "species_id": 1
}

Votes

List votes for the authenticated user

Authorizations:
None
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:
None
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": {
    }
}

Accounts

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
}

Get account overview stats (Admin only)

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

Responses

Breed Bans

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
[
  • {
    }
]

Pets

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

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.

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",
  • "date_of_birth": "2022-06-15",
  • "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",
  • "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

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
[
  • {
    }
]

List available portrait styles

Authorizations:
x-api-key

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Retrieve 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",
  • "date_of_birth": "2022-06-15",
  • "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",
  • "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

date_of_birth
string

ISO date for date of birth

age_years
number

Age in years

age_months
number

Age in months (0-11)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "breed_id": "string",
  • "species_id": "string",
  • "description": "string",
  • "microchip_id": "string",
  • "sub_id": "string",
  • "date_of_birth": "2022-06-15",
  • "age_years": 3,
  • "age_months": 6
}

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",
  • "date_of_birth": "2022-06-15",
  • "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",
  • "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

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

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

Pet identifier

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.",
  • "generated_at": "2024-01-15T12:00:00.000Z"
}

Estimate the age of a pet based on their images

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

Pet identifier

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.",
  • "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

Responses

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

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

Pet identifier

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"
}

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)

Responses

Request samples

Content type
application/json
{
  • "style": "studio"
}

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",
  • "created_at": "2024-01-15T12:00:00.000Z"
}

Breeds

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

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.

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
{ }

Favourites

List favourites for the authenticated user

Authorizations:
x-api-keyNone
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-keyNone
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-keyNone
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-keyNone
path Parameters
id
required
string
Example: 1

Favourite identifier

Responses

Response samples

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

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
[
  • {
    }
]

Health Tips

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 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",
  • "description": "string",
  • "sources": [
    ],
  • "species_id": 1
}

Images

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,
  • "breeds": [
    ],
  • "categories": [
    ],
  • "unsafe_reasons": [
    ]
}

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,
  • "breeds": [
    ],
  • "categories": [
    ],
  • "unsafe_reasons": [
    ]
}

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

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,
  • "breeds": [
    ],
  • "categories": [
    ],
  • "unsafe_reasons": [
    ]
}

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": { }
}

Sub Ids

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
[
  • {
    }
]