canonical: https://jentic.com/apis/petfinder.com/petfinder # Petfinder API Jentic publishes the only agent-ready OpenAPI specification for Petfinder API v2, keeping it validated and integration-ready. Search adoptable animals by type, breed, size, age, location, and behavior traits, retrieve animal welfare organization details, and access comprehensive pet adoption data. Filter by good with children, dogs, or cats, house-trained status, special needs, and location radius. OAuth 2.0 client credentials authentication with hourly token refresh. Supports paginated results with up to 100 pets per page. ## For AI agents Search adoptable animals, retrieve breed and organization data, and filter by location, size, age, gender, and compatibility traits through Petfinder's adoption database. ## Scope Does not manage shelter operations, process adoptions, or handle payment - use for pet discovery, search, and organization data retrieval only. ## Capabilities - Search adoptable animals by type, breed, size, gender, age, color, coat, and behavior traits - Filter pets by good with children, dogs, cats, house-trained, declawed, and special needs - Search by location with distance radius up to 500 miles from postal code or coordinates - Retrieve detailed animal profiles with photos, videos, descriptions, and contact information - Access animal welfare organization details including mission, hours, and adoption policies - Browse available animal types (dog, cat, rabbit, bird, etc.) with associated breeds and attributes - Retrieve breed lists for each animal type with full metadata - Paginate through results with customizable page size up to 100 records ## Use cases ### AI Agent Pet Adoption Search AI agents use the Petfinder API through Jentic to search adoptable animals by location, breed, age, size, and compatibility traits without managing OAuth credentials directly. The agent searches Jentic for 'find adoptable dogs near me', receives the /animals endpoint schema with filter parameters (location, distance, type, size, good_with_children), and executes. Jentic handles OAuth token refresh so the agent never manages client credentials or token expiration logic. Example prompt: Search for medium-sized dogs within 25 miles of 90210 that are good with children and house-trained, then return the first 20 results with photos and organization contact information ### Location-Based Pet Search Search for adoptable animals within a specific radius of a postal code, city and state, or latitude/longitude coordinates. Filter by distance up to 500 miles and sort by proximity, recency, or random. Results include distance from the search location, animal details, photos, and organization contact information. Ideal for building pet adoption tools, shelter integrations, and location-aware pet discovery features. Example prompt: Find all adoptable cats within 100 miles of New York, NY, sorted by distance, and return the name, breed, age, photos, and shelter contact details for each ### Organization and Shelter Discovery Search animal welfare organizations by name, location, state, or country (US and CA supported). Retrieve organization profiles including mission statements, hours of operation, adoption policies, contact information, social media links, and photos. Use this to build shelter directories, partner with local organizations, or integrate adoption data into community platforms. Example prompt: Search for all animal welfare organizations in California with 'rescue' in the name, then retrieve their mission statements, websites, and adoption policy URLs ### Breed and Type Metadata Retrieve all available animal types (dog, cat, rabbit, small-furry, horse, bird, scales-fins-other, barnyard) with associated breeds, coats, colors, and gender options. Use this metadata to build search filters, validate user input, or display breed-specific information. The /types endpoint returns type metadata, while /types/{type}/breeds returns the full breed list for a given animal type. Example prompt: Retrieve all available dog breeds from Petfinder, then use the breed names to populate a dropdown filter for a pet search form ## Key endpoints | Method | Path | Description | | --- | --- | --- | | GET | /animals | Search adoptable animals with filters for type, breed, size, age, gender, color, coat, location, distance, and behavior traits | | GET | /animals/{id} | Retrieve detailed profile for a specific animal by ID including photos, videos, and organization contact information | | GET | /organizations | Search animal welfare organizations by name, location, state, or country with pagination | | GET | /organizations/{id} | Retrieve details for a specific organization including mission, hours, adoption policies, and social media links | | GET | /types | Get all available animal types with associated coats, colors, and gender options | | GET | /types/{type}/breeds | Retrieve all breeds for a specific animal type | ## Key resources - **Animals** — Adoptable pets with breed, age, size, gender, coat, photos, videos, behavior traits, and organization details - **Organizations** — Animal welfare organizations with mission statements, contact information, hours, adoption policies, and social media links - **Animal Types** — Pet categories (dog, cat, rabbit, etc.) with associated breeds, coats, colors, and gender options - **Breeds** — Breed names for each animal type used for search filtering and metadata ## Why Jentic - **Setup:** Wiring the Petfinder API by hand means running its OAuth2 client-credentials flow against api.petfinder.com/v2 to mint tokens, refreshing them, and handling the search request formatting yourself. Through Jentic you install once, import the Petfinder API from the API Directory, store the client credentials once, and your agent calls it. - **Permission scoping:** Petfinder puts the resource id in the URL path (/animals/{id}, /organizations/{id}), so a rule can pin your agent to one animal or one organization: all of its exposed operations are reads, so the agent retrieves and searches pet and organization data and does nothing else. You choose the operations it may call, so it is limited to the lookups you allow. - **Credential handling:** Your Petfinder client credentials are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'find adoptable dogs near a location', and Jentic returns the matching Petfinder operation with its input schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **Adopt-a-Pet API** — Adopt-a-Pet provides a similar pet adoption database while Petfinder is the largest pet adoption network in North America - **Pets Adoptions API** — A Petfinder alternative for managing pet adoption listings and connecting animals with new homes programmatically. ## FAQ ### Why is there no official OpenAPI spec for Petfinder API? Petfinder does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Petfinder API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer. ### What authentication does the Petfinder API use? Petfinder uses OAuth 2.0 client credentials flow. Agents obtain an access token valid for 1 hour (3600 seconds) by presenting a client ID and client secret to the /oauth2/token endpoint. Through Jentic, credentials are stored encrypted in your Jentic One instance and tokens are refreshed automatically - agents never handle raw client secrets or token expiration logic. ### Can I search for pets by location with the Petfinder API? Yes. The /animals endpoint accepts a location parameter (city and state, postal code, or latitude/longitude) and a distance parameter in miles (default 100, max 500). Results include the distance field showing miles from the search location. Sort by distance, recency, or random to customize result ordering. ### How do I filter pets by behavior traits like good with children or house-trained? Use the boolean filter parameters: good_with_children, good_with_dogs, good_with_cats, house_trained, declawed, and special_needs. These parameters accept true or false and filter the results to only include animals matching the specified criteria. Combine multiple filters to narrow the search (e.g., good_with_children=true and house_trained=true). ### How do I search adoptable pets through the Petfinder API via Jentic? Search Jentic for 'find adoptable dogs near me' or 'petfinder search animals', then load the /animals operation schema. Specify filters like type, location, distance, size, age, and behavior traits, and Jentic handles OAuth token refresh and credential injection. Results include animal details, photos, and organization contact information. Install with pip install jentic run it through Jentic One, the self-hosted execution layer. ### Can I retrieve organization details for animal shelters with the Petfinder API? Yes. The /organizations endpoint searches organizations by name, location, state, or country. The /organizations/{id} endpoint retrieves full details including mission statement, hours of operation, adoption policies, contact information, social media links, and photos. Use this to build shelter directories or integrate adoption workflows. ### Can I limit what my agent is allowed to do with the Petfinder API? Yes. Because you run Jentic One yourself, your own rules decide which Petfinder operations and credentials the agent may use. Every exposed Petfinder operation is read-only (searching animals via /animals, fetching one animal with /animals/{id}, searching shelters via /organizations, and reading types and breeds), so you can allow only the specific lookups you want and the agent can do nothing beyond retrieving and searching pet and organization data. Since the resource id sits in the URL path, a rule can even pin the agent to a single animal or a single organization.