Skip to main content
API docs by Redocly

The Dog API

Download OpenAPI specification:Download

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

REST API documentation for the Dog API 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

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

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": [
    ]
}

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 is no longer to_be_reviewed.

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": [
    ]
}