API reference

Anyone can read with a free key. Verified shelters can also add and update their own pets, and can ask us to let their app contact owners. The base address is https://www.nokillnetwork.org/api/v1. Send your key as Authorization: Bearer nkn_live_…

The machine-readable description (OpenAPI 3.1) is at https://www.nokillnetwork.org/api/v1/openapi.json.

GET /pets · Adoptable pets
GET /pets/{id} · One pet
POST /pets/{id}/inquiries · Contact a pet's owner (verified shelters only)
GET /lost-found · Lost and found reports
GET /shelters · No-kill shelters
GET /shelters/{id} · One shelter
GET /shelters/{id}/pets · Your shelter's pets (shelter keys)
POST /shelters/{id}/pets · Add a pet (shelter keys)
GET /shelters/{id}/pets/{petId} · One of your shelter's pets (shelter keys)
PATCH /shelters/{id}/pets/{petId} · Update a pet or mark it adopted (shelter keys)
DELETE /shelters/{id}/pets/{petId} · Remove a pet (shelter keys)
POST /shelters/{id}/pets/{petId}/photos · Add a photo (shelter keys)
DELETE /shelters/{id}/pets/{petId}/photos/{photoId} · Delete a photo (shelter keys)
GET /breeds · Breed names

For shelters: add and update your pets

If you manage a shelter that's verified on The nØkill Network (claim your shelter's page first), you can turn on any of your keys for your shelter at Your API keys. That key can then add pets, update them, add photos and mark them adopted, for your shelter only, with the /shelters/{id}/pets endpoints below. Pets go live at once and work like any listing on the site. Keep your own id for each pet in externalId so your shelter software can sync without making duplicates.

The same key also adds pet tools to the MCP server, so an AI assistant can post and update pets for you. AI assistants (MCP)

`GET /api/v1/pets`

Adoptable pets. Live adoption listings in the US. Give a ZIP (nearest first) or a state (featured first, then newest).

Parameters

Name	In	Type	Description
`zip`	query	string	5-digit US ZIP code: results nearest first
`radius`	query	integer	Miles from the ZIP (1 to 250) Default 50.
`state`	query	string	2-letter US state code, e.g. CO
`city`	query	string	City name, with state
`species`	query	string	dog, cat, bird, rabbit, reptile or other
`breed`	query	string	Breed as listed (see /breeds)
`size`	query	string	small, medium, large or xlarge
`age`	query	string	baby, young, adult or senior. Only newer listings record an age, so this narrows results a lot
`limit`	query	integer	Results per page (1 to 100) Default 20.
`page`	query	integer	Page number Default 1.

Responses

200 Pets
400 Bad parameters
401 Missing or invalid API key
429 Over the per-minute or per-day limit (see Retry-After)

`GET /api/v1/pets/{id}`

One pet. A live adoption or lost & found listing. Closed, removed or expired listings return 404.

Parameters

Name	In	Type	Description
`id` (required)	path	integer	The pet's id

Responses

200 The pet
400 Bad parameters
401 Missing or invalid API key
404 No live pet with that id
429 Over the per-minute or per-day limit (see Retry-After)

`POST /api/v1/pets/{id}/inquiries`

Contact a pet's owner (verified shelters only). Sends an adopter's message to the pet's owner, typed by the adopter in a verified shelter's app. Only keys our staff have enabled for a verified shelter can use it. The message goes through the same scam checks as our own contact form; the owner's email names your shelter and their reply goes straight to the adopter, who also gets a copy. The answer is 202 whether the message was delivered or held for review.

Parameters

Name	In	Type	Description
`id` (required)	path	integer	The pet's id

Request body: application/json, Inquiry

Responses

202 Received
400 Bad parameters
401 Missing or invalid API key
403 This key can't contact owners (not enabled for a verified shelter)
404 No live pet with that id
429 Over the per-minute or per-day limit (see Retry-After)

`GET /api/v1/lost-found`

Lost and found reports. Reports from the last 6 months, featured reports first: then near a ZIP (nearest first), or newest first, optionally in one state.

Parameters

Name	In	Type	Description
`zip`	query	string	5-digit US ZIP code: results nearest first
`radius`	query	integer	Miles from the ZIP (1 to 250) Default 50.
`state`	query	string	2-letter US state code, when no ZIP is given
`status`	query	string	lost or found
`species`	query	string	dog or cat
`limit`	query	integer	Results per page (1 to 100) Default 20.

Responses

200 Reports
400 Bad parameters
401 Missing or invalid API key
429 Over the per-minute or per-day limit (see Retry-After)

`GET /api/v1/shelters`

No-kill shelters. Shelters in The nØkill Network's no-kill directory: near a US ZIP (nearest first) or in a state / city.

Parameters

Name	In	Type	Description
`zip`	query	string	5-digit US ZIP code: results nearest first
`radius`	query	integer	Miles from the ZIP (1 to 250) Default 50.
`state`	query	string	2-letter state code
`city`	query	string	City name, with state
`limit`	query	integer	Results per page (1 to 100) Default 20.

Responses

200 Shelters
400 Bad parameters
401 Missing or invalid API key
429 Over the per-minute or per-day limit (see Retry-After)

`GET /api/v1/shelters/{id}`

One shelter.

Parameters

Name	In	Type	Description
`id` (required)	path	integer	The shelter's id

Responses

200 The shelter
400 Bad parameters
401 Missing or invalid API key
404 No shelter with that id
429 Over the per-minute or per-day limit (see Retry-After)

`GET /api/v1/shelters/{id}/pets`

Your shelter's pets (shelter keys). Pets your shelter added through the API, newest first. Only for a key a verified manager of the shelter turned on at /developers/keys.

Parameters

Name	In	Type	Description
`id` (required)	path	integer	Your shelter's id (from /shelters)
`status`	query	string	available (live pets) or all (adopted, closed and expired too) Default available.
`externalId`	query	string	Find the pet with your own id
`limit`	query	integer	Results per page (1 to 100) Default 50.
`page`	query	integer	Page number Default 1.

Responses

200 Pets
400 Bad parameters
401 Missing or invalid API key
403 This key can't manage this shelter's pets (see /developers/keys)
429 Over the per-minute or per-day limit (see Retry-After)

`POST /api/v1/shelters/{id}/pets`

Add a pet (shelter keys). Lists one of your shelter's pets for adoption. It goes live at once, at your shelter's city, state and ZIP unless you give others, and works like any listing on the site: its own page, search, the contact form (messages come to the key's owner) and a 3-month life that any update renews. Up to 100 new pets a day. Add photos with the photos endpoint.

Parameters

Name	In	Type	Description
`id` (required)	path	integer	Your shelter's id (from /shelters)

Request body: application/json, PetInput

Responses

201 Added: the pet, with its id and page
400 Bad parameters
401 Missing or invalid API key
403 This key can't manage this shelter's pets (see /developers/keys)
409 You already added a pet with this externalId (its id is in the answer)
429 Over the per-minute or per-day limit (see Retry-After)

`GET /api/v1/shelters/{id}/pets/{petId}`

One of your shelter's pets (shelter keys). Any status except removed.

Parameters

Name	In	Type	Description
`id` (required)	path	integer	Your shelter's id (from /shelters)
`petId` (required)	path	integer	The pet's id

Responses

200 The pet
400 Bad parameters
401 Missing or invalid API key
403 This key can't manage this shelter's pets (see /developers/keys)
404 No pet of this shelter with that id
429 Over the per-minute or per-day limit (see Retry-After)

`PATCH /api/v1/shelters/{id}/pets/{petId}`

Update a pet or mark it adopted (shelter keys). Send only the fields that change. status: available, adopted or closed (no longer available). Where the pet is can't change: its page address stays the same. Any update keeps the pet live for another 3 months.

Parameters

Name	In	Type	Description
`id` (required)	path	integer	Your shelter's id (from /shelters)
`petId` (required)	path	integer	The pet's id

Request body: application/json, PetUpdate

Responses

200 The updated pet
400 Bad parameters
401 Missing or invalid API key
403 This key can't manage this shelter's pets (see /developers/keys)
404 No pet of this shelter with that id
409 Another of your pets has this externalId
429 Over the per-minute or per-day limit (see Retry-After)

`DELETE /api/v1/shelters/{id}/pets/{petId}`

Remove a pet (shelter keys). Takes the pet down completely. When it found a home, mark it adopted with PATCH instead.

Parameters

Name	In	Type	Description
`id` (required)	path	integer	Your shelter's id (from /shelters)
`petId` (required)	path	integer	The pet's id

Responses

204 Removed
400 Bad parameters
401 Missing or invalid API key
403 This key can't manage this shelter's pets (see /developers/keys)
404 No pet of this shelter with that id
429 Over the per-minute or per-day limit (see Retry-After)

`POST /api/v1/shelters/{id}/pets/{petId}/photos`

Add a photo (shelter keys). Send the image file itself as the body, with its Content-Type (JPEG, PNG, WebP, HEIC or GIF, up to 8 MB). We fix its orientation, remove its metadata (location too) and store it. Up to 10 photos; the first is the main one.

Parameters

Name	In	Type	Description
`id` (required)	path	integer	Your shelter's id (from /shelters)
`petId` (required)	path	integer	The pet's id

Request body: the image file itself, with its Content-Type (image/jpeg, image/png, image/webp, image/heic or image/gif).

Responses

201 The pet with its photos
400 Bad parameters
401 Missing or invalid API key
403 This key can't manage this shelter's pets (see /developers/keys)
404 No pet of this shelter with that id
409 The pet has 10 photos
413 Over 8 MB
415 Not an image type we take
429 Over the per-minute or per-day limit (see Retry-After)

`DELETE /api/v1/shelters/{id}/pets/{petId}/photos/{photoId}`

Delete a photo (shelter keys).

Parameters

Name	In	Type	Description
`id` (required)	path	integer	Your shelter's id (from /shelters)
`petId` (required)	path	integer	The pet's id
`photoId` (required)	path	integer	The photo's id (from the pet's photos)

Responses

204 Deleted
400 Bad parameters
401 Missing or invalid API key
403 This key can't manage this shelter's pets (see /developers/keys)
404 No such photo on this shelter's pet
429 Over the per-minute or per-day limit (see Retry-After)

`GET /api/v1/breeds`

Breed names. Breeds as owners list them for a species, most listed first. Use them in the breed filter.

Parameters

Name	In	Type	Description
`species` (required)	query	string	dog, cat, bird, rabbit or reptile

Responses

200 Breeds
400 Bad parameters
401 Missing or invalid API key
429 Over the per-minute or per-day limit (see Retry-After)

Objects

Inquiry

Field	Type	Description
`name`	string	The adopter's name (1 to 80 characters)
`email`	string (email)	The adopter's email address: the owner replies to it
`message`	string	The adopter's message (20 to 4,000 characters)

PetInput

Field	Type	Description
`name`	string	The pet's name (1 to 60 characters)
`species`	string	dog, cat, rabbit, bird, reptile or other
`breed`	string	Breed (default Unknown)
`sex`	string	male, female or unknown
`size`	string	small, medium, large or xlarge
`age`	string	baby, young, adult or senior
`description`	string	The pet's story (30 to 5,000 characters)
`spayedNeutered`	string	yes, no or unknown
`goodWithKids`	string	yes, no or unknown
`goodWithDogs`	string	yes, no or unknown
`goodWithCats`	string	yes, no or unknown
`energy`	string	low, medium or high
`city`	string	City or town (default: your shelter's)
`state`	string	US state code, or for UK shelters England, Scotland, Wales or Northern Ireland (default: your shelter's)
`postalCode`	string	ZIP code or postcode (default: your shelter's, else the city's)
`externalId`	string	Your own id for the pet, unique in your shelter, so a sync can find it again

PetUpdate

Field	Type	Description
`name`	string	The pet's name
`breed`	string	Breed
`description`	string	The pet's story
`age`	string	baby, young, adult or senior
`status`	string	available, adopted or closed
`externalId`	string	Your own id for the pet

ShelterPet

Field	Type	Description
`id`	integer	Pet id (the same as in /pets)
`externalId`	string \| null
`status`	string	available, adopted, closed or expired
`name`	string \| null
`species`	string \| null
`breed`	string \| null
`sex`	string
`size`	string \| null
`age`	string \| null
`description`	string \| null
`spayedNeutered`	string \| null
`goodWithKids`	string \| null
`goodWithDogs`	string \| null
`goodWithCats`	string \| null
`energy`	string \| null
`city`	string \| null
`state`	string \| null
`country`	string	US or UK
`photos`	object[]
`postedAt`	string \| null (date-time)
`updatedAt`	string \| null (date-time)
`url`	string (uri)	The pet's page on The nØkill Network

Error

Field	Type	Description
`error`	string
`details`	string[]

Pet

Field	Type	Description
`id`	integer	Pet id
`section`	string	adoption, lost or found
`name`	string \| null
`species`	string \| null
`breed`	string \| null
`sex`	string	male, female, mixed or unknown
`size`	string \| null	Null when the owner didn't say
`age`	string \| null	Null when the owner didn't say (most older listings)
`city`	string \| null
`state`	string \| null
`country`	string	US or UK
`description`	string \| null
`photos`	string (uri)[]
`featured`	boolean
`postedAt`	string \| null (date-time)
`url`	string (uri)	The pet's page: link to it wherever you show the pet

Shelter

Field	Type	Description
`id`	integer	Shelter id
`name`	string
`city`	string \| null
`state`	string \| null
`website`	string \| null
`phone`	string \| null
`description`	string \| null
`hours`	string \| null
`howToAdopt`	string \| null
`rating`	number \| null	Average review rating, 1 to 5
`reviewCount`	integer
`noKillPledge`	boolean
`url`	string (uri)	The shelter's page on The nØkill Network
`distanceMiles`	number	ZIP searches only

API reference

For shelters: add and update your pets

GET /api/v1/pets

Parameters

Responses

GET /api/v1/pets/{id}

Parameters

Responses

POST /api/v1/pets/{id}/inquiries

Parameters

Responses

GET /api/v1/lost-found

Parameters

Responses

GET /api/v1/shelters

Parameters

Responses

GET /api/v1/shelters/{id}

Parameters

Responses

GET /api/v1/shelters/{id}/pets

Parameters

Responses

POST /api/v1/shelters/{id}/pets

Parameters

Responses

GET /api/v1/shelters/{id}/pets/{petId}

Parameters

Responses

PATCH /api/v1/shelters/{id}/pets/{petId}

Parameters

Responses

DELETE /api/v1/shelters/{id}/pets/{petId}

Parameters

Responses

POST /api/v1/shelters/{id}/pets/{petId}/photos

Parameters

Responses

DELETE /api/v1/shelters/{id}/pets/{petId}/photos/{photoId}

Parameters

Responses

GET /api/v1/breeds

Parameters

Responses

Objects

Inquiry

PetInput

PetUpdate

ShelterPet

Error

Pet

Shelter

Try it

`GET /api/v1/pets`

`GET /api/v1/pets/{id}`

`POST /api/v1/pets/{id}/inquiries`

`GET /api/v1/lost-found`

`GET /api/v1/shelters`

`GET /api/v1/shelters/{id}`

`GET /api/v1/shelters/{id}/pets`

`POST /api/v1/shelters/{id}/pets`

`GET /api/v1/shelters/{id}/pets/{petId}`

`PATCH /api/v1/shelters/{id}/pets/{petId}`

`DELETE /api/v1/shelters/{id}/pets/{petId}`

`POST /api/v1/shelters/{id}/pets/{petId}/photos`

`DELETE /api/v1/shelters/{id}/pets/{petId}/photos/{photoId}`

`GET /api/v1/breeds`