Saltar al contenido principal
API docs by Redocly

Dog API (1.6.1)

Download OpenAPI specification:Download

License: Terms of Service

image

An open, read & write API all about Dogs

The Dog API gives you access to 1000's of dog images, and breeds.

    • Upload your own images - Detailed info on all the Breeds - Favourite or Vote on images - Get stats on your requests - Save a custom value with each request

How is this free?

Our goal is to create free, fun & useful public service API's, helping people learn to code, create awesome projects, and be a stable fixture in a turbulent world.

What are the premium plans?

Extra fields for the Breeds, and extra endpoints. Check out the features in the paid plans over at https://thedogapi.com

How do i get access?

Just signup for an API Key from https://thedogapi.com. We're looking forward to seeing what you build!

Images

Endpoints to get or upload Images

/images/search

Searches all approved public images. Default is to return RANDOM images, but with an API-Key you can use 'order=DESC' or 'order=ASC' along with the 'page' and 'limit' parameters to paginate through them in the order they were approved. Pagination-Count, Pagination-Page, and Pagination-Limit headers are present in the response so you know the total number of images that can be paginated through for the passed search filters.

Authorizations:
apikeyAuth
query Parameters
size
string
Example: size=full

[optional] thumb , small, med or full - small is perfect for Discord. Default is full

mime_types
string
Example: mime_types=jpg,png

[optional] a comma separated string of types to return e.g. jpg,png for static, or gif for gifs. Default will return any mime_type

format
string
Example: format=json

[optional] json | src - Default is json

has_breeds
boolean
Example: has_breeds=false

[optional] - only return images with breed data. Default false

order
string
Example: order=RANDOM

[optional] default:RANDOM - RANDOM | ASC | DESC

page
integer
Example: page=0

[optional] paginate through results

limit
integer
Example: limit=1

[optional] number of results to return, up to 25 with a valid API-Key

header Parameters
x-api-key
string
Example: {{YOUR-API-KEY}}

[optional] without it only the a basic set of images can be searched

Responses

Response samples

Content type
application/json
[
  • {
    }
]

/images/:image_id

Get a specific image by its ID. This can either be a public image, or one you have uploaded.

Authorizations:
apikeyAuth
path Parameters
image_id
required
string
Example: 6euYVVE_u

The ID of the image to retrieve

Responses

Response samples

Content type
application/json
{
  • "id": "6euYVVE_u",
  • "url": "https://cdn2.thedogapi.com/images/6euYVVE_u.jpg",
  • "width": 1024,
  • "height": 685,
  • "breeds": [
    ]
}

/images/:image_id

Can only delete images you have uploaded.

Authorizations:
apikeyAuth
path Parameters
image_id
required
string
Example: dMsUj1-nz
header Parameters
Content-Type
string
Example: application/json
x-api-key
string
Example: {{YOUR-API-KEY}}

Responses

/images/:image_id/analysis

Get the raw analysis results for any uploaded image

Authorizations:
apikeyAuth
path Parameters
image_id
required
string
Example: xxBaNrfM0

The ID of the image to analyze

header Parameters
x-api-key
string
Example: {{YOUR-API-KEY}}

[optional] will save this request to your account analytics

Responses

Response samples

Content type
application/json
[
  • {
    }
]

/images (Your uploads)

Lists the images you have uploaded via the POST /images/upload endpoint

Authorizations:
apikeyAuth
query Parameters
limit
integer
Example: limit=10

[Optional] number of images to return valid 1 to 10 - default: 1

page
integer
Example: page=0

[Optional] only works if account_id is present to page through your own uploads

order
string
Example: order=DESC

[Optional] only works if account_id is present, either ASC or DESC - ascending or descending.

header Parameters
x-api-key
required
string
Example: {{YOUR-API-KEY}}
  • will return all the images from your account

Responses

Response samples

Content type
application/json
Example
[]

/images/upload

Make sure you're using the right field to send the image, and Content-Type header

Authorizations:
apikeyAuth
header Parameters
Content-Type
string
Example: multipart/form-data
x-api-key
required
string
Example: {{YOUR-API-KEY}}
  • saves the uploaded image to your account.
Request Body schema: multipart/form-data
file
string <binary>
sub_id
string

[optional] - a string you can use to segment your images, e.g. knowing which of your own users uploaded it.

breed_ids
string

[optional] comma separated string of breed ids contained in the image

Responses

Response samples

Content type
application/json
{}

/images/:image_id/breeds

Get the breed information associated with a specific image

Authorizations:
apikeyAuth
path Parameters
image_id
required
string

Responses

/images/:image_id/breeds

Tag an image with a specific breed to associate them together

Authorizations:
apikeyAuth
path Parameters
image_id
required
string
header Parameters
Content-Type
string
Example: application/json
x-api-key
required
string
Example: {{YOUR-API-KEY}}
  • for now, you can only tag your own images with a breed
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{
  • "breed_id": 10
}

/images/:image_id/breeds/:breed_id

Remove the association between an image and a specific breed

Authorizations:
apikeyAuth
path Parameters
image_id
required
string
breed_id
required
string
header Parameters
Content-Type
string
Example: application/json
x-api-key
required
string
Example: {{YOUR-API-KEY}}
  • only you can delete breeds from your images

Responses

Breeds

Endpoints to get information about different Breeds

/breeds

Get a list of all available dog breeds with optional pagination

Authorizations:
apikeyAuth
query Parameters
limit
integer
Example: limit=10
page
integer
Example: page=0

Responses

Response samples

Content type
application/json
[
  • {
    }
]

/breeds/:breed_id

Get detailed information about a specific dog breed

Authorizations:
apikeyAuth
path Parameters
breed_id
required
string

Responses

Response samples

Content type
application/json
{
  • "weight": {
    },
  • "height": {
    },
  • "id": 111,
  • "name": "Finnish Spitz",
  • "bred_for": "Hunting birds, small mammals",
  • "breed_group": "Non-Sporting",
  • "life_span": "12 - 15 years",
  • "temperament": "Playful, Loyal, Independent, Intelligent, Happy, Vocal",
  • "reference_image_id": "3PjHlQbkV"
}

Search Breeds

Search for dog breeds by name with optional image attachment

Authorizations:
apikeyAuth
query Parameters
q
string
Example: q=air

search term for breed name

attach_image
integer
Example: attach_image=1

[optional] whether to attach the reference_image_id image or not

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Favourites

Endpoints to save or get Favourited Images by your Users

/favourites

Get all your favourite images that you have saved

Authorizations:
apikeyAuth
header Parameters
x-api-key
required
string
Example: {{YOUR-API-KEY}}

Responses

Response samples

Content type
application/json
[
  • {
    }
]

/favourites

Save an image as a favourite to your account - with optional sub_id to represent your own user that is performing the action. You can then list /favourites using that sub_id as a filter.

Authorizations:
apikeyAuth
header Parameters
Content-Type
string
Example: application/json
x-api-key
required
string
Example: {{YOUR-API-KEY}}
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
"{\n\t\"image_id\":asf2,\n\t\"sub_id\": \"my-user-1234\"\n}"

Response samples

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

/favourites/:favourite_id

Get details of a specific favourite by its ID

Authorizations:
apikeyAuth
path Parameters
favourite_id
required
string
header Parameters
x-api-key
required
string
Example: {{YOUR-API-KEY}}

Responses

/favourites/:favourite_id

Remove a specific favourite from your account

Authorizations:
apikeyAuth
path Parameters
favourite_id
required
string
header Parameters
x-api-key
required
string
Example: {{YOUR-API-KEY}}

Responses

Votes

Endpoints to let your Users Vote on Images

/votes

Get all votes that you have submitted for images

Authorizations:
apikeyAuth
header Parameters
x-api-key
required
string
Example: {{YOUR-API-KEY}}

Responses

Response samples

Content type
application/json
[
  • {
    }
]

/votes

Submit a vote (like or dislike) for a specific image - with optional sub_id to represent your own user that is performing the action. You can then list /votes using that sub_id as a filter.

Authorizations:
apikeyAuth
header Parameters
Content-Type
string
Example: application/json
x-api-key
required
string
Example: {{YOUR-API-KEY}}
Request Body schema: application/json
object

Responses

Request samples

Content type
application/json
{
  • "image_id": "asf2",
  • "sub_id": "my-user-1234",
  • "value": 1
}

Response samples

Content type
application/json
{
  • "message": "SUCCESS",
  • "id": 1120951,
  • "image_id": "asf2",
  • "sub_id": "my-user-1234",
  • "value": 1,
  • "country_code": "AU"
}

/votes/:vote_id

Get details of a specific vote by its ID

Authorizations:
apikeyAuth
path Parameters
vote_id
required
string
header Parameters
x-api-key
required
string
Example: {{YOUR-API-KEY}}

Responses

/votes/:vote_id

Delete a specific vote from your account

Authorizations:
apikeyAuth
path Parameters
vote_id
required
string
header Parameters
x-api-key
required
string
Example: {{YOUR-API-KEY}}

Responses

Webhooks

Endpoints allowing the setting up Webhooks for events in your Account

Facts

Premium feature: https://portal.thatapicompany.com/catalog

Returns an evergrowing list of Facts about Cats, Dogs and their different breeds. These have been checked for accuracy and to be safe for schools.

Get Ordered Fact(s) About Breed

Get one or more facts about the Species. For more at a time just update the 'limit' field, and to paginate through them just increment the 'page' field.

The response headers have the pagination details, such as how many there are in total, what page you're on, and the current amount per page.

To redorder change the order to ASC for ascending order, DESC for descending, and RAND for random order.

Authorizations:
apikeyAuth
path Parameters
breed_id
required
string
Example: 111
query Parameters
limit
integer
Example: limit=5
page
integer
Example: page=0
order
string
Example: order=ASC

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Get Random Fact(s)

Get one or more Random facts and the Species. For more at a time just update the 'limit' field

Authorizations:
apikeyAuth

Responses

Response samples

Content type
application/json
[
  • {
    }
]