Skip to main content

Create a pet

Most of what you build on TheDogAPI starts with a pet: a record for one owner's dog that holds its photos, details and results. Breed identification, age, body condition, portraits, health history and the calculators all take its id as pet_id. Create one per pet, keep its id against your own record, and reuse it every time.

1. Create it with photos​

Send the details and up to 20 photos in one multipart/form-data request:

curl -X POST -H "x-api-key: YOUR-API-KEY" -H "Content-Type: multipart/form-data" \
  -F "name=Buddy" \
  -F "breed_id=115" \
  -F "date_of_birth=2022-06-15" \
  -F "sex=female" \
  -F "neuter_status=neutered" \
  -F "external_owner_id=usr_8b3d91" \
  -F "images=@/path/to/side.jpg" \
  -F "images=@/path/to/above.jpg" \
  -F 'poses={"0":"side","1":"top"}' \
  https://api.thedogapi.com/v1/pets
{
  "id": "UGqpzmlMbw",
  "name": "Buddy",
  "breed_id": "115",
  "country": "GB",
  "sex": "female",
  "neuter_status": "neutered",
  "date_of_birth": "2022-06-15",
  "external_owner_id": "usr_8b3d91",
  "images": [ … ],
  "created_at": "2026-10-06T02:00:48.846Z",
  "updated_at": "2026-10-06T02:00:48.846Z"
}

Save id. That's the pet_id every other guide asks for.

Without photos, send JSON instead. You can add photos later.

curl -X POST -H "x-api-key: YOUR-API-KEY" -H "Content-Type: application/json" \
  -d '{"name": "Buddy", "breed_id": "115", "age_years": 3}' \
  https://api.thedogapi.com/v1/pets

2. The fields​

Every field is optional, but the more you send, the better the results.

FieldWhat it's for
name, descriptionFor your owners.
breed_idThe breed, from GET /breeds. Unlocks breed data, predispositions and breed weight ranges. Don't know it? Identify it from a photo.
date_of_birthYYYY-MM-DD. Or send age_years and age_months and we work the date out. Don't know either? Estimate it.
sex, neuter_statusmale / female / unknown and neutered / intact / unknown. Used by the calculators.
countryISO code such as GB. Sets seasonal context for photo analysis. If you leave it out, we fill it in from where the request came from.
external_owner_id, sub_idYour own identifiers, so you can find a user's pets again. See Link pets to your users.
microchip_idIf the owner has it.
body_condition_scoreA score you already have, 1 to 9.

Don't send owners' names, emails or other personal details in any field. Use your own identifier and keep the personal data on your side.

3. Add photos​

Add more photos at any time, up to 20 per request:

curl -X POST -H "x-api-key: YOUR-API-KEY" -H "Content-Type: multipart/form-data" \
  -F "images=@/path/to/front.jpg" \
  -F 'poses={"0":"front"}' \
  https://api.thedogapi.com/v1/pets/{pet_id}/images
  • Poses tell the models what each photo shows: front, side, rear or top. poses is a JSON object from the photo's position in the request (starting at 0) to its pose. It's optional but helps, especially for body condition.
  • Analysis uses the latest photos, so adding new ones is how you get a fresh result. Results are reused until new photos arrive.
  • Limits: 50 MB per photo, and 100 new photos per pet in 24 hours. More than that returns 429, which is there to stop a client stuck in a retry loop. Ask us if you need more.

4. Add a video​

curl -X POST -H "x-api-key: YOUR-API-KEY" \
  -F "file=@/path/to/sleeping.MOV;type=video/quicktime" \
  https://api.thedogapi.com/v1/pets/{pet_id}/videos

Keep the ;type= part when you use curl, or the video can be refused. Upload a pet video covers formats, processing and limits.

5. Read, update and delete​

# One pet, with its photos
curl -H "x-api-key: YOUR-API-KEY" https://api.thedogapi.com/v1/pets/{pet_id}

# A user's pets
curl -H "x-api-key: YOUR-API-KEY" "https://api.thedogapi.com/v1/pets?external_owner_id=usr_8b3d91"

# Change details
curl -X PATCH -H "x-api-key: YOUR-API-KEY" -H "Content-Type: application/json" \
  -d '{"neuter_status": "neutered"}' \
  https://api.thedogapi.com/v1/pets/{pet_id}

# Delete, for example when a user closes their account
curl -X DELETE -H "x-api-key: YOUR-API-KEY" https://api.thedogapi.com/v1/pets/{pet_id}

A pet belongs to the account that created it. Another account's key gets 403, and an id that doesn't exist gets 404.

Next​