> ## Documentation Index > Fetch the complete documentation index at: https://docs2.petstoreapi.com/llms.txt > Use this file to discover all available pages before exploring further. # List Pets > Retrieve a paginated list of pets available for adoption with optional filtering. ## OpenAPI ````yaml api-reference/modern-petstore-3.1.openapi.json get /pets openapi: 3.1.0 info: title: Modern Petstore API summary: A modern, realistic pet store API demonstrating current best practices description: >- This is a modern Pet Store API based on the OpenAPI 3.2 specification. It demonstrates contemporary API design patterns and best practices including RESTful compliance, proper HTTP methods, structured error responses (RFC 9457), and modern authentication flows. Key features include pet catalog browsing, adoption workflow, order management, user accounts, AI-powered chat advisor, and real-time event notifications via webhooks. The API showcases OpenAPI 3.2 capabilities like hierarchical tags, QUERY HTTP method, OAuth device flow, and server-sent events. Some useful links: - [API Documentation](https://docs.petstoreapi.com) - [Source Code Repository](https://github.com/petstoreapi/PetstoreAPI) - [OpenAPI Specification](https://petstoreapi.com/v1/specs/modern-petstore-3.2.openapi.yaml) version: 1.0.0 contact: name: Petstore API Support url: https://petstoreapi.com/support email: support@petstoreapi.com license: name: MIT identifier: MIT servers: - url: https://api.petstoreapi.com/v1 description: Production server security: - bearerAuth: [] - oauth2: [] tags: - name: Store description: Store operations including orders and inventory - name: Pet description: Pet catalog and management operations - name: Payments description: Payment processing with polymorphic payment sources - name: User description: User account management - name: Chat description: >- AI-powered chat completions with streaming support using Server-Sent Events (SSE) externalDocs: description: Learn more about Chat API url: https://petstoreapi.com/docs/chat - name: Webhooks description: Event-driven webhook notifications (OpenAPI 3.2) externalDocs: description: Learn more about webhooks url: https://petstoreapi.com/docs/webhooks paths: /pets: parameters: - $ref: '#/components/parameters/TenantID' get: tags: - Pet summary: List Pets description: >- Retrieve a paginated list of pets available for adoption with optional filtering. operationId: listPets parameters: - name: species in: query description: Filter by pet species required: false schema: type: string enum: - DOG - CAT - RABBIT - BIRD - REPTILE - OTHER - name: status in: query description: Filter by adoption status required: false schema: type: string enum: - AVAILABLE - PENDING - ADOPTED default: AVAILABLE - name: ageMin in: query description: Minimum age in months required: false schema: type: integer minimum: 0 - name: ageMax in: query description: Maximum age in months required: false schema: type: integer minimum: 0 - name: size in: query description: Filter by pet size required: false schema: type: string enum: - SMALL - MEDIUM - LARGE - name: goodWithKids in: query description: Filter pets that are good with children required: false schema: type: boolean - name: page in: query description: Page number for pagination required: false schema: type: integer minimum: 1 default: 1 - name: limit in: query description: Number of items per page required: false schema: type: integer minimum: 1 maximum: 100 default: 20 responses: '200': description: Successful response with pet collection headers: RateLimit-Limit: $ref: '#/components/headers/RateLimit-Limit' RateLimit-Remaining: $ref: '#/components/headers/RateLimit-Remaining' RateLimit-Reset: $ref: '#/components/headers/RateLimit-Reset' content: application/json: schema: $ref: '#/components/schemas/PetCollection' examples: multiple-pets: summary: Multiple pets available value: data: - id: 01936c8f-1234-7000-8000-111111111111 species: CAT name: Whiskers breed: Domestic Shorthair ageMonths: 18 size: MEDIUM color: Orange Tabby gender: MALE goodWithKids: true price: '75.00' description: >- Friendly and playful orange tabby looking for a loving home status: AVAILABLE photos: - >- https://cdn.petstoreapi.com/pets/01936c8f-1234-7000-8000-111111111111/photo1.jpg - id: 01936c8f-2345-7000-8000-222222222222 species: DOG name: Max breed: Labrador Retriever ageMonths: 36 size: LARGE color: Yellow gender: MALE goodWithKids: true price: '150.00' description: Energetic and loyal lab who loves fetch and long walks status: AVAILABLE photos: - >- https://cdn.petstoreapi.com/pets/01936c8f-2345-7000-8000-222222222222/photo1.jpg pagination: page: 1 limit: 20 totalItems: 45 totalPages: 3 '400': $ref: '#/components/responses/BadRequest' '422': $ref: '#/components/responses/UnprocessableEntity' '429': $ref: '#/components/responses/TooManyRequests' deprecated: false security: [] components: parameters: TenantID: name: X-Tenant-ID in: header description: >- Optional tenant identifier for data isolation. When provided, all operations will be scoped to this tenant, ensuring data separation between different organizations or users. If omitted, operations will access the shared/public data pool where data may be visible to and modified by other users. required: false schema: type: string format: uuid examples: organization: value: 550e8400-e29b-41d4-a716-446655440000 summary: Organization tenant ID development: value: 7c9e6679-7425-40de-944b-e07fc1f90ae7 summary: Development environment production: value: 9b5e4f89-3c12-4a5e-9f8e-2d3c5a7e6b1a summary: Production environment headers: RateLimit-Limit: description: The maximum number of requests allowed in the current time window schema: type: integer example: 100 RateLimit-Remaining: description: The number of requests remaining in the current time window schema: type: integer example: 95 RateLimit-Reset: description: The time at which the current rate limit window resets (Unix timestamp) schema: type: integer example: 1702648800 schemas: PetCollection: type: object description: Collection of pets with pagination required: - data - pagination properties: data: type: array items: $ref: '#/components/schemas/Pet' pagination: type: object required: - page - limit - totalItems - totalPages properties: page: type: integer minimum: 1 description: Current page number limit: type: integer minimum: 1 description: Number of items per page totalItems: type: integer minimum: 0 description: Total number of items totalPages: type: integer minimum: 0 description: Total number of pages unevaluatedProperties: false unevaluatedProperties: false Pet: type: object description: Animal information in the pet store available for adoption. required: - id - name - species - ageMonths - price - currency - status - createdAt - updatedAt properties: id: type: string format: uuid readOnly: true description: Unique identifier for the pet (UUID v7) examples: - 019b4132-70aa-764f-b315-e2803d882a24 - 019b4127-54d5-76d9-b626-0d4c7bfce5b6 species: type: string enum: - DOG - CAT - RABBIT - BIRD - REPTILE - OTHER description: The species of the pet name: type: string minLength: 1 maxLength: 50 description: The pet's name examples: - Whiskers - Max - Luna breed: type: string description: The breed of the pet examples: - Domestic Shorthair - Labrador Retriever - Holland Lop ageMonths: type: integer minimum: 0 description: Age of the pet in months examples: - 18 - 36 - 6 size: type: string enum: - SMALL - MEDIUM - LARGE description: Size category of the pet color: type: string description: Primary color or coloring pattern examples: - Orange Tabby - Black - Brown and White gender: type: string enum: - MALE - FEMALE - UNKNOWN description: The pet's gender goodWithKids: type: boolean description: Whether the pet is good with children price: type: string description: Adoption fee amount examples: - '75.00' - '150.00' - '50.00' currency: type: string description: Currency code for the adoption fee (ISO 4217) default: USD pattern: ^[A-Z]{3}$ examples: - USD - EUR - GBP description: type: string description: Detailed description of the pet's personality and traits status: type: string enum: - AVAILABLE - PENDING - ADOPTED - NOT_AVAILABLE description: Current adoption status createdAt: type: string format: date-time readOnly: true description: Timestamp when the pet record was created (RFC 3339) examples: - '2025-12-21T13:56:23Z' - '2025-11-15T08:30:00Z' updatedAt: type: string format: date-time readOnly: true description: Timestamp when the pet record was last updated (RFC 3339) examples: - '2025-12-21T13:56:23Z' - '2025-12-21T15:30:45Z' tenantId: type: string format: uuid readOnly: true description: >- Optional tenant identifier for data isolation. When present, indicates this pet belongs to a specific tenant. Null or omitted means the pet is in the shared/public data pool. examples: - 550e8400-e29b-41d4-a716-446655440000 - 7c9e6679-7425-40de-944b-e07fc1f90ae7 nullable: true photos: type: array items: type: string format: uri description: URLs of pet photos minItems: 0 medicalInfo: type: object properties: spayedNeutered: type: boolean description: Whether the pet has been spayed or neutered vaccinated: type: boolean description: Whether the pet is up to date on vaccinations microchipped: type: boolean description: Whether the pet has a microchip specialNeeds: type: boolean description: Whether the pet has special medical needs healthNotes: type: string description: Additional medical notes unevaluatedProperties: false unevaluatedProperties: false Error: type: object description: RFC 9457 Problem Details for HTTP APIs required: - type - title - status properties: type: type: string format: uri description: A URI reference that identifies the problem type examples: - https://petstoreapi.com/errors/not-found - https://petstoreapi.com/errors/validation-error title: type: string description: A short, human-readable summary of the problem examples: - Resource Not Found - Validation Error status: type: integer description: The HTTP status code examples: - 404 - 400 - 422 detail: type: string description: A human-readable explanation specific to this occurrence examples: - The requested pet with ID '123' was not found instance: type: string format: uri description: A URI reference that identifies the specific occurrence examples: - /v1/pets/123 errors: type: array description: Detailed validation errors (for 422 responses) items: type: object required: - field - message properties: field: type: string description: The field that failed validation message: type: string description: Description of the validation error code: type: string description: Machine-readable error code unevaluatedProperties: false unevaluatedProperties: false responses: BadRequest: description: Bad request - Invalid parameters headers: RateLimit-Limit: $ref: '#/components/headers/RateLimit-Limit' RateLimit-Remaining: $ref: '#/components/headers/RateLimit-Remaining' RateLimit-Reset: $ref: '#/components/headers/RateLimit-Reset' content: application/problem+json: schema: $ref: '#/components/schemas/Error' examples: invalid-parameter: summary: Invalid query parameter value: type: https://petstoreapi.com/errors/bad-request title: Bad Request status: 400 detail: >- Invalid value for parameter 'status'. Must be one of: available, pending, sold. instance: /pets UnprocessableEntity: description: Unprocessable entity - Validation errors content: application/problem+json: schema: $ref: '#/components/schemas/Error' examples: validation-errors: summary: Validation errors value: type: https://petstoreapi.com/errors/validation-error title: Validation Error status: 422 detail: The request body contains validation errors. instance: /pets errors: - field: name message: Pet name is required code: required_field - field: status message: Invalid status value code: invalid_format TooManyRequests: description: Too many requests - Rate limit exceeded headers: RateLimit-Limit: $ref: '#/components/headers/RateLimit-Limit' RateLimit-Remaining: schema: type: integer example: 0 RateLimit-Reset: $ref: '#/components/headers/RateLimit-Reset' Retry-After: description: Number of seconds to wait before retrying schema: type: integer example: 60 content: application/problem+json: schema: $ref: '#/components/schemas/Error' examples: rate-limit-exceeded: summary: Rate limit exceeded value: type: https://petstoreapi.com/errors/rate-limit-exceeded title: Too Many Requests status: 429 detail: >- Rate limit exceeded. Please wait 60 seconds before making another request. securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- Bearer token authentication using JWT (JSON Web Token). Include the token in the Authorization header as: `Authorization: Bearer ` oauth2: type: oauth2 description: >- OAuth 2.0 authorization with multiple flows including device authorization for IoT devices and smart TVs flows: authorizationCode: authorizationUrl: https://auth.petstoreapi.com/authorize tokenUrl: https://auth.petstoreapi.com/token refreshUrl: https://auth.petstoreapi.com/refresh scopes: read:pets: Read pet information write:pets: Create and update pets read:orders: Read order information write:orders: Create and manage orders read:user: Read user profile write:user: Update user profile chat:write: Access AI chat completions ````