$schema: https://spec.openapis.org/oas/3.2/schema/2024-10-31
openapi: 3.2.0
$self: https://api.petstoreapi.com/v1/openapi.json
jsonSchemaDialect: https://json-schema.org/draft/2020-12/schema
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
tags:
  - name: Store
    summary: Store operations
    description: Store operations including orders and inventory
    kind: category
  - name: Pet
    summary: Pet management
    description: Pet catalog and management operations
    kind: resource
    parent: Store
  - name: Payments
    summary: Payment processing
    description: Payment processing with polymorphic payment sources
    kind: resource
    parent: Store
  - name: User
    summary: User accounts
    description: User account management
    kind: resource
  - name: Chat
    summary: AI Chat
    description: AI-powered chat completions with streaming support using Server-Sent Events (SSE)
    kind: feature
    externalDocs:
      description: Learn more about Chat API
      url: https://petstoreapi.com/docs/chat
  - name: Webhooks
    summary: Event notifications
    description: Event-driven webhook notifications (OpenAPI 3.2)
    kind: system
    externalDocs:
      description: Learn more about webhooks
      url: https://petstoreapi.com/docs/webhooks
paths:
  /pets/{id}:
    parameters:
      - name: id
        in: path
        description: Unique identifier for the pet
        required: true
        example: 01936c8f-1234-7000-8000-111111111111
        schema:
          type: string
          format: uuid
      - $ref: '#/components/parameters/TenantID'
    get:
      summary: Get Pet
      deprecated: false
      description: Retrieve detailed information about a specific pet.
      operationId: getPet
      tags:
        - Pet
      security: []
      x-codeSamples:
        - lang: TypeScript
          label: TypeScript SDK
          source: |-
            import { PetStoreAPI } from '@petstoreapi/sdk';

            const client = new PetStoreAPI({
              apiKey: process.env.PETSTORE_API_KEY
            });

            const pet = await client.pets.get('01936c8f-1234-7000-8000-111111111111');
            console.log(`Found ${pet.name}, a ${pet.age_months}-month-old ${pet.species}`);
        - lang: Python
          label: Python
          source: |-
            from petstore import PetStoreAPI

            client = PetStoreAPI(api_key=os.environ['PETSTORE_API_KEY'])

            pet = client.pets.get('01936c8f-1234-7000-8000-111111111111')
            print(f"Found {pet.name}, a {pet.age_months}-month-old {pet.species}")
        - lang: JavaScript
          label: JavaScript (Fetch)
          source: |-
            const response = await fetch(
              'https://api.petstoreapi.com/v1/pets/01936c8f-1234-7000-8000-111111111111',
              {
                headers: {
                  'Accept': 'application/json'
                }
              }
            );

            const pet = await response.json();
            console.log(`Found ${pet.name}, a ${pet.age_months}-month-old ${pet.species}`);
        - lang: Shell
          label: cURL
          source: |-
            curl -X GET 'https://api.petstoreapi.com/v1/pets/01936c8f-1234-7000-8000-111111111111' \
              -H 'Accept: application/json'
      responses:
        '200':
          description: Successful response with pet details
          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/Pet'
              examples:
                cat-example:
                  summary: A friendly cat
                  value:
                    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
                      - https://cdn.petstoreapi.com/pets/01936c8f-1234-7000-8000-111111111111/photo2.jpg
                    medicalInfo:
                      spayedNeutered: true
                      vaccinated: true
                      microchipped: true
                      specialNeeds: false
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    put:
      summary: Update Pet
      deprecated: false
      description: Update information for an existing pet. Staff only.
      operationId: updatePet
      tags:
        - Pet
      security:
        - bearerAuth: []
        - oauth2:
            - write:pets
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Pet'
            example:
              name: Max Updated
              species: DOG
              breed: Golden Retriever
              ageMonths: 25
              size: LARGE
              color: Golden
              gender: MALE
              goodWithKids: true
              price: '275.00'
              currency: USD
              status: AVAILABLE
              description: Friendly and well-trained golden retriever
              medicalInfo:
                vaccinated: true
                spayedNeutered: true
                microchipped: true
                specialNeeds: false
                healthNotes: Up to date on all vaccinations, recent dental cleaning
      responses:
        '200':
          description: Pet updated successfully
          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/Pet'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    delete:
      summary: Delete Pet
      deprecated: false
      description: Delete a pet from the system. Staff only.
      operationId: deletePet
      tags:
        - Pet
      security:
        - bearerAuth: []
        - oauth2:
            - write:pets
      responses:
        '204':
          description: Pet deleted successfully
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /pets:
    parameters:
      - $ref: '#/components/parameters/TenantID'
    post:
      summary: Create Pet
      deprecated: false
      description: >-
        Add a new pet to the store catalog, making it available for adoption.


        ## Pet Lifecycle Workflow


        When a new pet enters the system:


        1. **Intake**: Staff creates a pet record with this endpoint (status: `available`)

        2. **Profile**: Pet details include species, breed, age, medical info, photos, and adoption fee

        3. **Discovery**: Pet appears in search results and listings

        4. **Adoption Application**: Potential adopters can apply through the adoption endpoints

        5. **Adoption**: Once approved, pet status changes to `adopted`

        6. **Post-Adoption**: Pet record is retained for historical purposes


        **Access**: This operation requires staff permissions (`write:pets` scope or valid Bearer token). Only
        authenticated staff members can add pets to the system.
      operationId: createPet
      tags:
        - Pet
      security:
        - bearerAuth: []
        - oauth2:
            - write:pets
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Pet'
            example:
              name: Max
              species: DOG
              breed: Golden Retriever
              ageMonths: 24
              size: LARGE
              color: Golden
              gender: MALE
              goodWithKids: true
              price: '250.00'
              currency: USD
              status: AVAILABLE
              description: Friendly golden retriever looking for an active family
              medicalInfo:
                vaccinated: true
                spayedNeutered: true
                microchipped: true
                specialNeeds: false
                healthNotes: Up to date on all vaccinations
      x-codeSamples:
        - lang: TypeScript
          label: TypeScript SDK
          source: |-
            import { PetStoreAPI } from '@petstoreapi/sdk';

            const client = new PetStoreAPI({
              accessToken: process.env.OAUTH_ACCESS_TOKEN
            });

            const newPet = await client.pets.create({
              species: 'dog',
              name: 'Buddy',
              breed: 'Golden Retriever',
              ageMonths: 24,
              size: 'large',
              color: 'Golden',
              gender: 'male',
              goodWithKids: true,

              price: '150.00',
              description: 'Friendly golden retriever looking for an active family'
            });

            console.log(`Created pet with ID: ${newPet.id}`);
        - lang: Python
          label: Python
          source: |-
            from petstore import PetStoreAPI

            client = PetStoreAPI(access_token=os.environ['OAUTH_ACCESS_TOKEN'])

            new_pet = client.pets.create(
                species='dog',
                name='Buddy',
                breed='Golden Retriever',
                ageMonths=24,
                size='large',
                color='Golden',
                gender='male',
                goodWithKids=True,

                price='150.00',
                description='Friendly golden retriever looking for an active family'
            )

            print(f"Created pet with ID: {new_pet.id}")
        - lang: JavaScript
          label: JavaScript (Fetch)
          source: |-
            const response = await fetch(
              'https://api.petstoreapi.com/v1/pets',
              {
                method: 'POST',
                headers: {
                  'Authorization': `Bearer ${accessToken}`,
                  'Content-Type': 'application/json'
                },
                body: JSON.stringify({
                  species: 'dog',
                  name: 'Buddy',
                  breed: 'Golden Retriever',
                  ageMonths: 24,
                  size: 'large',
                  color: 'Golden',
                  gender: 'male',
                  goodWithKids: true,
    
                  price: '150.00',
                  description: 'Friendly golden retriever looking for an active family'
                })
              }
            );

            const newPet = await response.json();
            console.log(`Created pet with ID: ${newPet.id}`);
        - lang: Shell
          label: cURL
          source: |-
            curl -X POST 'https://api.petstoreapi.com/v1/pets' \
              -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
              -H 'Content-Type: application/json' \
              -d '{
                "species": "dog",
                "name": "Buddy",
                "breed": "Golden Retriever",
                "ageMonths": 24,
                "size": "large",
                "color": "Golden",
                "gender": "male",
                "goodWithKids": true,

                "price": "150.00",
                "description": "Friendly golden retriever looking for an active family"
              }'
      responses:
        '201':
          description: Pet created successfully
          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/Pet'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
    get:
      summary: List Pets
      deprecated: false
      description: Retrieve a paginated list of pets available for adoption with optional filtering.
      operationId: listPets
      tags:
        - Pet
      security: []
      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'
    query:
      summary: Advanced Pet Search (QUERY method)
      deprecated: false
      description: >-
        Perform complex pet searches using the QUERY HTTP method (RFC draft-ietf-httpbis-safe-method-w-body). Unlike
        GET, this allows sending structured search criteria in the request body while maintaining safe, idempotent
        semantics.


        ## Why QUERY?


        The QUERY method is ideal for:

        - **Complex queries** that exceed URL length limits

        - **Structured search criteria** better expressed in JSON

        - **Safe operations** that don't modify resources

        - **Cacheable results** like GET requests


        ## Use Cases


        - Multi-criteria searches (medical history, temperament, location)

        - Saved search queries reused programmatically

        - Advanced filtering with nested conditions


        This endpoint returns the same response format as GET /pets but accepts complex search criteria in the body.
      operationId: searchPets
      tags:
        - Pet
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                criteria:
                  type: object
                  description: Search criteria for finding pets
                  properties:
                    species:
                      type: array
                      items:
                        type: string
                        enum:
                          - DOG
                          - CAT
                          - RABBIT
                          - BIRD
                          - REPTILE
                          - OTHER
                      description: Filter by one or more species
                    ageRange:
                      type: object
                      properties:
                        min:
                          type: integer
                          minimum: 0
                        max:
                          type: integer
                          minimum: 0
                    size:
                      type: array
                      items:
                        type: string
                        enum:
                          - SMALL
                          - MEDIUM
                          - LARGE
                    compatibility:
                      type: object
                      properties:
                        goodWithKids:
                          type: boolean

                    medical:
                      type: object
                      properties:
                        vaccinated:
                          type: boolean
                        spayedNeutered:
                          type: boolean
                        specialNeeds:
                          type: boolean
                sort:
                  type: object
                  properties:
                    field:
                      type: string
                      enum:
                        - ageMonths
                        - price
                    order:
                      type: string
                      enum:
                        - ASC
                        - DESC
                pagination:
                  type: object
                  properties:
                    page:
                      type: integer
                      minimum: 1
                      default: 1
                    limit:
                      type: integer
                      minimum: 1
                      maximum: 100
                      default: 20
            examples:
              family-friendly-dogs:
                summary: Family-friendly dogs
                value:
                  criteria:
                    species:
                      - DOG
                    ageRange:
                      min: 12
                      max: 72
                    size:
                      - medium
                      - large
                    compatibility:
                      goodWithKids: true

                    medical:
                      vaccinated: true
                      spayedNeutered: true
                  sort:
                    field: age_months
                    order: asc
                  pagination:
                    page: 1
                    limit: 20
      responses:
        '200':
          description: Search results
          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:
                type: object
                required:
                  - data
                  - pagination
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Pet'
                  pagination:
                    $ref: '#/components/schemas/PaginationInfo'
        '400':
          $ref: '#/components/responses/BadRequest'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /chat/completions:
    post:
      summary: Create Chat Completion
      deprecated: false
      description: >-
        Creates a model response for a chat conversation with the Pet Adoption Advisor AI. Supports streaming responses
        using Server-Sent Events (SSE).


        ## Pet Adoption Advisor


        Our AI assistant helps users:

        - Get personalized pet recommendations

        - Learn about pet care and adoption process

        - Answer questions about specific pets

        - Provide breed information and compatibility advice


        ## Streaming Mode


        When `stream: true`, the response is sent as Server-Sent Events (SSE), with each token delivered incrementally.
        This provides a better user experience for longer responses.


        ### Stream Format


        Each chunk is sent as:

        ```

        data: {"id":"chatcmpl_abc","object":"chat.completion.chunk","choices":[{"delta":{"content":"Hello"},"index":0}]}


        ```


        The stream ends with:

        ```

        data: [DONE]


        ```


        ## Non-Streaming Mode


        When `stream: false` or omitted, returns a complete response object.
      operationId: createChatCompletion
      tags:
        - Chat
      externalDocs:
        description: Complete Chat API Guide with Streaming Examples
        url: https://petstoreapi.com/docs/chat/streaming-guide
      security:
        - bearerAuth: []
        - oauth2:
            - chat:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - messages
              properties:
                messages:
                  type: array
                  description: A list of messages comprising the conversation so far
                  items:
                    type: object
                    required:
                      - role
                      - content
                    properties:
                      role:
                        type: string
                        enum:
                          - SYSTEM
                          - USER
                          - ASSISTANT
                        description: The role of the message author
                      content:
                        type: string
                        description: The contents of the message
                  minItems: 1
                model:
                  type: string
                  description: ID of the model to use
                  enum:
                    - PET_ADVISOR_1
                    - PET_ADVISOR_TURBO
                  default: PET_ADVISOR_1
                stream:
                  type: boolean
                  description: If true, partial message deltas will be sent via Server-Sent Events
                  default: true
                maxTokens:
                  type: integer
                  description: Maximum number of tokens to generate
                  minimum: 1
                  maximum: 4096
                  default: 1024
                temperature:
                  type: number
                  description: Sampling temperature between 0 and 2
                  minimum: 0
                  maximum: 2
                  default: 1
              unevaluatedProperties: false
            examples:
              simple-question:
                summary: Simple pet question
                value:
                  messages:
                    - role: user
                      content: What should I know before adopting a cat?
                  model: pet-advisor-1
                  stream: false
              streaming-conversation:
                summary: Streaming multi-turn conversation
                value:
                  messages:
                    - role: system
                      content: You are a helpful pet adoption advisor.
                    - role: user
                      content: I'm looking for a pet that's good with kids
                    - role: assistant
                      content: Great! Dogs like Labrador Retrievers and Golden Retrievers are excellent with children.
                    - role: user
                      content: Tell me more about Golden Retrievers
                  model: pet-advisor-turbo
                  stream: true
                  temperature: 0.7
      x-codeSamples:
        - lang: TypeScript
          label: TypeScript SDK (Non-Streaming)
          source: |-
            import { PetStoreAPI } from '@petstoreapi/sdk';

            const client = new PetStoreAPI({
              accessToken: process.env.OAUTH_ACCESS_TOKEN
            });

            const completion = await client.chat.completions.create({
              messages: [
                { role: 'user', content: 'What should I know before adopting a cat?' }
              ],
              model: 'pet-advisor-1',
              stream: false
            });

            console.log(completion.choices[0].message.content);
        - lang: TypeScript
          label: TypeScript SDK (Streaming)
          source: |-
            import { PetStoreAPI } from '@petstoreapi/sdk';

            const client = new PetStoreAPI({
              accessToken: process.env.OAUTH_ACCESS_TOKEN
            });

            const stream = await client.chat.completions.create({
              messages: [
                { role: 'user', content: 'What should I know before adopting a cat?' }
              ],
              model: 'pet-advisor-1',
              stream: true
            });

            for await (const chunk of stream) {
              const content = chunk.choices[0]?.delta?.content;
              if (content) {
                process.stdout.write(content);
              }
            }
        - lang: Python
          label: Python (Streaming)
          source: |-
            from petstore import PetStoreAPI

            client = PetStoreAPI(access_token=os.environ['OAUTH_ACCESS_TOKEN'])

            stream = client.chat.completions.create(
                messages=[
                    {"role": "user", "content": "What should I know before adopting a cat?"}
                ],
                model="pet-advisor-1",
                stream=True
            )

            for chunk in stream:
                if chunk.choices[0].delta.content:
                    print(chunk.choices[0].delta.content, end="")
        - lang: JavaScript
          label: JavaScript (Fetch with SSE)
          source: |-
            const response = await fetch(
              'https://api.petstoreapi.com/v1/chat/completions',
              {
                method: 'POST',
                headers: {
                  'Authorization': `Bearer ${accessToken}`,
                  'Content-Type': 'application/json'
                },
                body: JSON.stringify({
                  messages: [
                    { role: 'user', content: 'What should I know before adopting a cat?' }
                  ],
                  model: 'pet-advisor-1',
                  stream: true
                })
              }
            );

            const reader = response.body.getReader();
            const decoder = new TextDecoder();

            while (true) {
              const { value, done } = await reader.read();
              if (done) break;
              
              const chunk = decoder.decode(value);
              const lines = chunk.split('\n').filter(line => line.startsWith('data: '));
              
              for (const line of lines) {
                const data = line.replace('data: ', '');
                if (data === '[DONE]') break;
                const parsed = JSON.parse(data);
                process.stdout.write(parsed.choices[0]?.delta?.content || '');
              }
            }
        - lang: Shell
          label: cURL (Non-Streaming)
          source: |-
            curl -X POST 'https://api.petstoreapi.com/v1/chat/completions' \
              -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
              -H 'Content-Type: application/json' \
              -d '{
                "messages": [
                  {
                    "role": "user",
                    "content": "What should I know before adopting a cat?"
                  }
                ],
                "model": "pet-advisor-1",
                "stream": false
              }'
      responses:
        '201':
          description: Successful response. Format depends on the `stream` parameter.
          headers:
            Content-Type:
              description: Response content type
              schema:
                type: string
                enum:
                  - text/event-stream
                  - application/json
          content:
            text/event-stream:
              schema:
                type: string
                description: 'Streaming response (when stream=true). Each line contains a JSON chunk prefixed with ''data: '''
                format: binary
              examples:
                streaming-response:
                  summary: Streaming chat completion
                  value: >+
                    data:
                    {"id":"chatcmpl_abc123","object":"chat.completion.chunk","created":1702648800,"model":"pet-advisor-1","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}]}


                    data:
                    {"id":"chatcmpl_abc123","object":"chat.completion.chunk","created":1702648800,"model":"pet-advisor-1","choices":[{"index":0,"delta":{"content":"Before"},"finish_reason":null}]}


                    data:
                    {"id":"chatcmpl_abc123","object":"chat.completion.chunk","created":1702648800,"model":"pet-advisor-1","choices":[{"index":0,"delta":{"content":"
                    adopting"},"finish_reason":null}]}


                    data:
                    {"id":"chatcmpl_abc123","object":"chat.completion.chunk","created":1702648800,"model":"pet-advisor-1","choices":[{"index":0,"delta":{"content":"
                    a"},"finish_reason":null}]}


                    data:
                    {"id":"chatcmpl_abc123","object":"chat.completion.chunk","created":1702648800,"model":"pet-advisor-1","choices":[{"index":0,"delta":{"content":"
                    cat"},"finish_reason":null}]}


                    data:
                    {"id":"chatcmpl_abc123","object":"chat.completion.chunk","created":1702648800,"model":"pet-advisor-1","choices":[{"index":0,"delta":{"content":"..."},"finish_reason":null}]}


                    data:
                    {"id":"chatcmpl_abc123","object":"chat.completion.chunk","created":1702648800,"model":"pet-advisor-1","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}


                    data: [DONE]

            application/json:
              schema:
                type: object
                description: Non-streaming response (when stream=false)
                properties:
                  id:
                    type: string
                    description: Unique identifier for the completion
                    pattern: ^chatcmpl_[a-z0-9]+$
                  object:
                    type: string
                    const: chat.completion
                  created:
                    type: integer
                    description: Unix timestamp of when the completion was created
                  model:
                    type: string
                    description: Model used for completion
                  choices:
                    type: array
                    items:
                      type: object
                      properties:
                        index:
                          type: integer
                        message:
                          type: object
                          properties:
                            role:
                              type: string
                              const: assistant
                            content:
                              type: string
                        finishReason:
                          type: string
                          enum:
                            - STOP
                            - LENGTH
                            - CONTENT_FILTER
                  usage:
                    type: object
                    properties:
                      promptTokens:
                        type: integer
                      completionTokens:
                        type: integer
                      totalTokens:
                        type: integer
              examples:
                complete-response:
                  summary: Complete chat response
                  value:
                    id: chatcmpl_abc123
                    object: chat.completion
                    created: 1702648800
                    model: pet-advisor-1
                    choices:
                      - index: 0
                        message:
                          role: assistant
                          content: |-
                            Before adopting a cat, consider these important factors:

                            1. **Time Commitment**: Cats can live 15-20 years
                            2. **Space**: Ensure you have adequate living space
                            3. **Allergies**: Check if anyone in your household has cat allergies
                            4. **Costs**: Budget for food, litter, vet care, and supplies
                            5. **Lifestyle**: Consider if your schedule allows for proper care

                            Would you like recommendations for cats currently available for adoption?
                        finishReason: stop
                    usage:
                      promptTokens: 15
                      completionTokens: 89
                      totalTokens: 104

        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /pets/{id}/images:
    post:
      summary: Upload Pet Image
      deprecated: false
      description: Upload an image for the specified pet. Requires authentication and write:pets permission.
      operationId: uploadPetPhoto
      tags:
        - Pet
      parameters:
        - name: id
          in: path
          description: Unique identifier for the pet
          required: true
          example: 01936c8f-1234-7000-8000-111111111111
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                additionalMetadata:
                  description: Additional data to pass to server
                  type: string
                  example: ''
                file:
                  description: File to upload
                  type: string
                  format: binary
                  example: ''
            examples: {}
      responses:
        '201':
          description: Operation successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
              example:
                code: 3
                type: ex dolor
                message: Pecus carcer cometes credo.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      security:
        - bearerAuth: []
        - oauth2:
            - write:pets
  /orders/{id}/payment:
    post:
      summary: Pay Order
      deprecated: false
      description: >-
        Process payment for an existing order.


        ## Payment Workflow


        Payment processing follows this workflow:


        1. **Create Order**: First create an order using `POST /orders` (status: `placed`)

        2. **Submit Payment**: Call this endpoint with payment details (card or bank account)

        3. **Payment Processing**: The payment is processed with status `processing`

        4. **Payment Result**:
           - **Success**: Payment status becomes `succeeded`, order status updates to `approved`
           - **Failure**: Payment status becomes `failed`, order remains `placed` and can be retried
        5. **Receipt**: After successful payment, retrieve the receipt from the order details


        **Security Note**: Sensitive payment data (like CVC codes) are `writeOnly` and never returned in responses.
        Card numbers and account numbers are masked when read.
      operationId: createOrderPayment
      tags:
        - Payments
      parameters:
        - name: id
          in: path
          description: Unique identifier for the order
          required: true
          example: 019b4139-1234-7abc-8def-123456789abc
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderPayment'
            examples:
              Card:
                value:
                  amount: "49.99"
                  currency: GBP
                  source:
                    object: card
                    name: J. Doe
                    number: '4242424242424242'
                    cvc: '123'
                    expMonth: 12
                    expYear: 2025
                    addressLine1: 123 Fake Street
                    addressLine2: 4th Floor
                    addressCity: London
                    addressCountry: gb
                    addressPostCode: N12 9XX
                summary: Pay by Bank Card
              Bank:
                value:
                  amount: "100.50"
                  currency: GBP
                  source:
                    object: bank_account
                    name: J. Doe
                    number: '00012345'
                    sortCode: '000123'
                    accountType: individual
                    bankName: Starling Bank
                    country: gb
                summary: Pay by Bank Account
        required: true
      responses:
        '201':
          description: Payment successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderPayment'
              examples:
                '1':
                  summary: Card Payment
                  value:
                    id: 2e3b4f5a-6b7c-8d9e-0f1a-2b3c4d5e6f7a
                    amount: "49.99"
                    currency: GBP
                    source:
                      object: card
                      name: J. Doe
                      number: '************4242'
                      cvc: '123'
                      expMonth: 12
                      expYear: 2025
                      addressCountry: gb
                      addressPostCode: N12 9XX
                    status: succeeded
                '2':
                  summary: Bank Account Payment
                  value:
                    id: 2e3b4f5a-6b7c-8d9e-0f1a-2b3c4d5e6f7a
                    amount: "100.50"
                    currency: GBP
                    source:
                      object: bank_account
                      name: J. Doe
                      accountType: individual
                      number: '*********2345'
                      sortCode: '000123'
                      bankName: Starling Bank
                      country: gb
                    status: succeeded
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      security: []
  /inventories:
    get:
      summary: List Inventory
      deprecated: false
      description: Returns a mapping of status codes to quantities.
      operationId: getInventory
      tags:
        - Store
      parameters:
        - name: status
          in: query
          description: Values to filter inventory status (comma-separated).
          required: false
          example:
            - AVAILABLE
            - PENDING
          schema:
            type: array
            items:
              type: string
      responses:
        '200':
          description: Operation successful
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: integer
                  format: int32
                properties: {}
          headers: {}
      security:
        - bearerToken: []
  /orders:
    parameters:
      - $ref: '#/components/parameters/TenantID'
    post:
      summary: Create Order
      deprecated: false
      description: Create a new order in the store.
      operationId: createOrder
      tags:
        - Store
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Order'
            example:
              petId: 019b4132-70aa-764f-b315-e2803d882a24
              userId: 019b4138-e0af-70b9-8f0c-6ea97d495dfa
      x-codeSamples:
        - lang: TypeScript
          label: TypeScript SDK
          source: |-
            import { PetStoreAPI } from '@petstoreapi/sdk';

            const client = new PetStoreAPI({
              accessToken: process.env.OAUTH_ACCESS_TOKEN
            });

            const order = await client.orders.create({
              petId: 90180021,
              quantity: 1,
              shipDate: '2025-08-15',
              status: 'placed'
            });

            console.log(`Order ${order.id} created successfully`);
        - lang: Python
          label: Python
          source: |-
            from petstore import PetStoreAPI

            client = PetStoreAPI(access_token=os.environ['OAUTH_ACCESS_TOKEN'])

            order = client.orders.create(
                petId=90180021,
                quantity=1,
                shipDate='2025-08-15',
                status='placed'
            )

            print(f"Order {order.id} created successfully")
        - lang: JavaScript
          label: JavaScript (Fetch)
          source: |-
            const response = await fetch(
              'https://api.petstoreapi.com/v1/orders',
              {
                method: 'POST',
                headers: {
                  'Content-Type': 'application/json'
                },
                body: JSON.stringify({
                  petId: 90180021,
                  quantity: 1,
                  shipDate: '2025-08-15',
                  status: 'placed'
                })
              }
            );

            const order = await response.json();
            console.log(`Order ${order.id} created successfully`);
        - lang: Shell
          label: cURL
          source: |-
            curl -X POST 'https://api.petstoreapi.com/v1/orders' \
              -H 'Content-Type: application/json' \
              -d '{
                "petId": 90180021,
                "quantity": 1,
                "shipDate": "2025-08-15",
                "status": "placed"
              }'
      responses:
        '201':
          description: Operation successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
              example:
                id: 44524671
                petId: 90180021
                quantity: 23
                shipDate: '2025-08-15'
                status: placed
                complete: false
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      security: []
  /orders/{id}:
    parameters:
      - name: id
        in: path
        description: Unique identifier for the order
        required: true
        example: 019b4139-1234-7abc-8def-123456789abc
        schema:
          type: string
          format: uuid
      - $ref: '#/components/parameters/TenantID'
    get:
      summary: Get Order
      deprecated: false
      description: Retrieve order information by order ID.
      operationId: getOrder
      tags:
        - Store
      responses:
        '200':
          description: Operation successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
              example:
                id: 40238436
                petId: 69923630
                quantity: 87
                shipDate: '2024-12-09'
                status: approved
                complete: false
          headers: {}
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
      security: []
    delete:
      summary: Delete Order
      deprecated: false
      description: Delete an existing order by its unique identifier.
      operationId: deleteOrder
      tags:
        - Store
      parameters:
        - name: id
          in: path
          description: Unique identifier for the order
          required: true
          example: 019b4139-1234-7abc-8def-123456789abc
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: Resource deleted successfully
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
      security: []
    post:
      summary: Callback Example
      deprecated: false
      description: Handles order events and supports asynchronous processing with Callback.
      operationId: callbackOrder
      tags:
        - Store
      parameters:
        - name: id
          in: path
          description: Unique identifier for the order
          required: true
          example: 019b4139-1234-7abc-8def-123456789abc
          schema:
            type: string
            format: uuid
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                amount:
                  type: string
                  description: The payment amount
                currency:
                  type: string
                  description: The payment currency
                timestamp:
                  type: string
                  description: Operation timestamp
                callbackUrl:
                  type: string
                  format: uri
                  description: URL to call back when processing is complete
              required:
                - amount
                - currency
                - timestamp
                - callbackUrl
            example:
              amount: "738.05"
              currency: USD
              timestamp: '1758613403'
              callbackUrl: https://example.com/callbacks/orders/1312312
      responses:
        '201':
          description: Callback enqueued successfully.
          content:
            application/json:
              schema:
                type: object
                properties: {}
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
      security: []
      callbacks:
        orderProcessed:
          '{$request.body#/callbackUrl}':
            post:
              requestBody:
                content:
                  application/json:
                    schema:
                      type: object
                      properties:
                        requestId:
                          type: string
                          format: uuid
                        orderId:
                          type: string
                        status:
                          type: string
                          enum:
                            - COMPLETED
                            - FAILED
                        result:
                          type: object
                        timestamp:
                          type: string
                      required:
                        - requestId
                        - orderId
                        - status
                        - timestamp
                    example:
                      requestId: 0d7a3836-956f-453b-b633-94a16e720d60
                      orderId: '1312312'
                      status: completed
                      result:
                        transactionId: tx_12345
                        processingDetails:
                          processor: payment-gateway-1
                          approvalCode: AUTH123456
                      timestamp: '1758613503'
              responses:
                '200':
                  description: Callback received successfully
  /users:
    parameters:
      - $ref: '#/components/parameters/TenantID'
    post:
      summary: Create User
      deprecated: false
      description: Create a new user in the system.
      operationId: createUser
      tags:
        - User
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
            example:
              username: kylekinh
              firstName: Kyle
              lastName: Kihn
              email: kyle.kihn@example.com
              password: SecurePass123!
              phone: '+18638982053'
      responses:
        '201':
          description: User created successfully.
          content:
            application/json:
              schema:
                type: object
                properties: {}
        '400':
          $ref: '#/components/responses/BadRequest'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security: []
  /users/{id}:
    parameters:
      - name: id
        in: path
        description: Unique identifier for the user
        required: true
        example: user_abc123xyz
        schema:
          type: string
      - $ref: '#/components/parameters/TenantID'
    put:
      summary: Update User
      deprecated: false
      description: Update user information. Only the logged-in user can perform this operation.
      operationId: updateUser
      tags:
        - User
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/User'
            example:
              firstName: Jeffrey
              lastName: Kris
              email: jeffrey.kris@example.com
              phone: '+18634063542'
      responses:
        '200':
          description: User updated successfully.
          content:
            application/json:
              schema:
                type: object
                properties: {}
          headers: {}
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      security: []
    get:
      summary: Get User
      deprecated: false
      description: Retrieve user information by user ID.
      operationId: getUserById
      tags:
        - User
      parameters:
        - name: id
          in: path
          description: Unique identifier for the user
          required: true
          example: user_abc123xyz
          schema:
            type: string
      responses:
        '200':
          description: Operation successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
              example:
                id: 019b4138-e0af-70b9-8f0c-6ea97d495dfa
                username: ameliehackett
                firstName: Amelie
                lastName: Hackett
                email: amelie.hackett@example.com
                phone: '+16324377270'
                createdAt: '2025-12-21T13:56:23Z'
                updatedAt: '2025-12-21T13:56:23Z'
          headers: {}
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
      security: []
    delete:
      summary: Delete User
      deprecated: false
      description: Delete a user account. Only the logged-in user can perform this operation.
      operationId: deleteUser
      tags:
        - User
      parameters:
        - name: id
          in: path
          description: Unique identifier for the user
          required: true
          example: user_abc123xyz
          schema:
            type: string
      responses:
        '204':
          description: Resource deleted successfully
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
      security: []
  /auth/tokens:
    post:
      summary: Create Token (Login)
      deprecated: false
      description: Authenticate user and obtain an access token.
      operationId: createToken
      tags:
        - User
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - username
                - password
              properties:
                username:
                  type: string
                  description: Login username
                  examples:
                    - johndoe
                password:
                  type: string
                  writeOnly: true
                  description: User password (never returned in responses)
                  examples:
                    - securePassword123
              unevaluatedProperties: false
            example:
              username: kylekinh
              password: SecurePass123!
      responses:
        '200':
          description: Login successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  token:
                    type: string
                    description: Authentication token
                  expiresAt:
                    type: string
                    format: date-time
                    description: Token expiration time
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      security: []

components:
  schemas:
    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
          # format: double removed as it is not valid for 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
    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
    User:
      type: object
      description: User account information
      required:
        - id
        - username
        - email
        - firstName
        - lastName
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
          description: Unique user identifier (UUID v7)
          examples:
            - 019b4138-e0af-70b9-8f0c-6ea97d495dfa
            - 019b4128-6a6b-777c-9ae8-335e962c68d8
        username:
          type: string
          description: Unique username for login
          minLength: 3
          maxLength: 50
          examples:
            - johndoe
            - mysqluser
        email:
          type: string
          format: email
          description: User email address
          examples:
            - user@example.com
            - john.doe@petstore.com
        firstName:
          type: string
          description: User's first name
          examples:
            - John
            - Jane
        lastName:
          type: string
          description: User's last name
          examples:
            - Doe
            - Smith
        phone:
          type: string
          pattern: ^\+?[1-9]\d{1,14}$
          description: Phone number in E.164 format
          examples:
            - '+12025551234'
        createdAt:
          type: string
          format: date-time
          readOnly: true
          description: Account creation timestamp (RFC 3339)
          examples:
            - '2025-12-21T13:56:23Z'
            - '2025-11-15T08:30:00Z'
        updatedAt:
          type: string
          format: date-time
          readOnly: true
          description: Account last update timestamp (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 user belongs to a specific
            tenant. Null or omitted means the user is in the shared/public data pool.
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
            - 7c9e6679-7425-40de-944b-e07fc1f90ae7
          nullable: true
        preferences:
          type: object
          properties:
            newsletter:
              type: boolean
              description: Whether to receive newsletter emails
            notifications:
              type: boolean
              description: Whether to receive notification emails
          unevaluatedProperties: false
      unevaluatedProperties: false
    OrderPayment:
      description: Order payment information with polymorphic payment sources
      type: object
      required:
        - id
        - amount
        - currency
        - source
        - status
      properties:
        id:
          description: Unique payment identifier
          type: string
          format: uuid
          readOnly: true
          examples:
            - 2e3b4f5a-6b7c-8d9e-0f1a-2b3c4d5e6f7a
        amount:
          description: Payment amount (positive decimal)
          type: string
          # exclusiveMinimum: 0 removed
          examples:
            - "49.99"
            - "100.50"
        currency:
          description: Three-letter ISO 4217 currency code (uppercase)
          type: string
          enum:
            - USD
            - EUR
            - GBP
            - CAD
            - AUD
          default: USD
        source:
          description: Payment source (card or bank account)
          discriminator:
            propertyName: object
            mapping:
              card: '#/components/schemas/CardPaymentSource'
              bankAccount: '#/components/schemas/BankAccountPaymentSource'
          oneOf:
            - $ref: '#/components/schemas/CardPaymentSource'
            - $ref: '#/components/schemas/BankAccountPaymentSource'
        status:
          description: Payment status
          type: string
          enum:
            - PENDING
            - PROCESSING
            - SUCCEEDED
            - FAILED
            - CANCELLED
          readOnly: true
        createdAt:
          type: string
          format: date-time
          readOnly: true
          description: Payment creation timestamp
      unevaluatedProperties: false
    CardPaymentSource:
      type: object
      title: Bank Card
      description: Debit or credit card payment source
      externalDocs:
        description: Payment Security Best Practices and PCI Compliance Guide
        url: https://petstoreapi.com/docs/payments/security
      required:
        - object
        - name
        - number
        - expMonth
        - expYear
      properties:
        object:
          type: string
          const: card
          description: Discriminator value for card payments
        name:
          type: string
          description: Cardholder name
          examples:
            - Jane Doe
            - John Smith
        number:
          type: string
          description: Card number (masked when reading)
          pattern: ^[0-9*]{13,19}$
          examples:
            - '4242424242424242'
            - '************4242'
        cvc:
          type: string
          description: Card security code
          pattern: ^[0-9]{3,4}$
          writeOnly: true
        expMonth:
          type: integer
          minimum: 1
          maximum: 12
          description: Expiration month (1-12)
        expYear:
          type: integer
          minimum: 2024
          description: Expiration year (4 digits)
        brand:
          type: string
          enum:
            - VISA
            - MASTERCARD
            - AMEX
            - DISCOVER
            - DINERS
            - JCB
            - UNIONPAY
          readOnly: true
          description: Card brand
        last4:
          type: string
          pattern: ^[0-9]{4}$
          readOnly: true
          description: Last 4 digits
        billingAddress:
          type: object
          properties:
            line1:
              type: string
              writeOnly: true
            line2:
              type: string
              writeOnly: true
            city:
              type: string
            state:
              type: string
            postalCode:
              type: string
            country:
              type: string
              pattern: ^[A-Z]{2}$
              description: ISO 3166-1 alpha-2 country code
          unevaluatedProperties: false
      unevaluatedProperties: false
    BankAccountPaymentSource:
      type: object
      title: Bank Account
      description: Bank account payment source
      externalDocs:
        description: ACH Payment Processing and Bank Account Verification
        url: https://petstoreapi.com/docs/payments/ach-guide
      required:
        - object
        - accountHolderName
        - accountNumber
        - routingNumber
        - accountType
      properties:
        object:
          type: string
          const: bank_account
          description: Discriminator value for bank account payments
        accountHolderName:
          type: string
          description: Name of account holder
        accountNumber:
          type: string
          description: Bank account number (masked when reading)
          pattern: ^[0-9*]{4,17}$
        routingNumber:
          type: string
          description: Bank routing number
          pattern: ^[0-9]{9}$
        accountType:
          type: string
          enum:
            - CHECKING
            - SAVINGS
          description: Type of bank account
        bankName:
          type: string
          readOnly: true
          description: Name of the bank
        last4:
          type: string
          pattern: ^[0-9]{4}$
          readOnly: true
          description: Last 4 digits of account number
      unevaluatedProperties: false
    Category:
      type: object
      description: Pet category
      required:
        - id
        - name
      properties:
        id:
          type: string
          description: Unique category identifier
        name:
          type: string
          description: Category name
      unevaluatedProperties: false
    Links:
      description: Hypermedia links for resource navigation
      type: object
      required:
        - self
      properties:
        self:
          type: string
          format: uri
          description: Link to this resource
      unevaluatedProperties: false
    Order:
      type: object
      description: Pet store order details
      required:
        - id
        - petId
        - userId
        - status
        - totalAmount
        - currency
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
          description: Unique order identifier (UUID v7)
          examples:
            - 019b4139-1234-7abc-8def-123456789abc
            - 019b4127-5678-7def-9012-234567890def
        petId:
          type: string
          format: uuid
          description: ID of the pet being ordered
          examples:
            - 019b4132-70aa-764f-b315-e2803d882a24
            - 019b4127-54d5-76d9-b626-0d4c7bfce5b6
        userId:
          type: string
          format: uuid
          description: ID of the user placing the order
          examples:
            - 019b4138-e0af-70b9-8f0c-6ea97d495dfa
            - 019b4128-6a6b-777c-9ae8-335e962c68d8
        status:
          type: string
          description: Order status
          enum:
            - PLACED
            - APPROVED
            - SHIPPED
            - DELIVERED
            - CANCELLED
          examples:
            - PLACED
            - APPROVED
        totalAmount:
          type: string
          # format: double removed
          # minimum: 0 removed
          description: Total order amount
          examples:
            - "125.50"
            - "75.00"
            - "200.99"
        currency:
          type: string
          description: Currency code for the order amount (ISO 4217)
          default: USD
          pattern: ^[A-Z]{3}$
          examples:
            - USD
            - EUR
            - GBP
        createdAt:
          type: string
          format: date-time
          readOnly: true
          description: Order creation timestamp (RFC 3339)
          examples:
            - '2025-12-21T13:56:23Z'
            - '2025-11-15T08:30:00Z'
        updatedAt:
          type: string
          format: date-time
          readOnly: true
          description: Order last update timestamp (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 order belongs to a specific
            tenant. Null or omitted means the order is in the shared/public data pool.
          examples:
            - 550e8400-e29b-41d4-a716-446655440000
            - 7c9e6679-7425-40de-944b-e07fc1f90ae7
          nullable: true
      unevaluatedProperties: false
    ApiResponse:
      type: object
      description: Generic API response
      properties:
        message:
          type: string
          description: Human-readable message
        success:
          type: boolean
          description: Whether the operation was successful
      unevaluatedProperties: false
    Tag:
      type: object
      description: Tags associated with pets
      required:
        - id
        - name
      properties:
        id:
          type: string
          description: Unique tag identifier
        name:
          type: string
          description: Tag name
      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
    Unauthorized:
      description: Unauthorized - Authentication required
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            missing-token:
              summary: Missing authentication token
              value:
                type: https://petstoreapi.com/errors/unauthorized
                title: Unauthorized
                status: 401
                detail: Authentication is required to access this resource. Please provide a valid OAuth 2.0 token.
    Forbidden:
      description: Forbidden - Insufficient permissions
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            insufficient-permissions:
              summary: Insufficient permissions
              value:
                type: https://petstoreapi.com/errors/forbidden
                title: Forbidden
                status: 403
                detail: You do not have permission to access this resource.
    NotFound:
      description: Resource not found
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            pet-not-found:
              summary: Pet not found
              value:
                type: https://petstoreapi.com/errors/not-found
                title: Not Found
                status: 404
                detail: The requested pet with ID '123' was not found.
                instance: /pets/123
    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.
    InternalServerError:
      description: Internal server error
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            server-error:
              summary: Internal server error
              value:
                type: https://petstoreapi.com/errors/internal-server-error
                title: Internal Server Error
                status: 500
                detail: An unexpected error occurred. Please try again later.
    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
    MethodNotAllowed:
      description: Method not allowed - HTTP method not supported for this endpoint
      headers:
        Allow:
          description: List of HTTP methods that are allowed for this resource
          schema:
            type: string
          example: GET, POST, PUT, DELETE
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            method-not-allowed:
              summary: HTTP method not allowed
              value:
                type: https://petstoreapi.com/errors/method-not-allowed
                title: Method Not Allowed
                status: 405
                detail: The TRACE method is not allowed for this resource
                instance: /pets/019b4132-70aa-764f-b315-e2803d882a24
  securitySchemes:
    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
        deviceCode:
          deviceAuthorizationUrl: https://auth.petstoreapi.com/device/authorize
          tokenUrl: https://auth.petstoreapi.com/token
          refreshUrl: https://auth.petstoreapi.com/refresh
          scopes:
            read:pets: Read pet information
            chat:write: Access AI chat completions
    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 <token>`
  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
  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
  pathItems:
    pet-resource:
      parameters:
        - name: id
          in: path
          description: Unique identifier for the pet
          required: true
          schema:
            type: string
            format: uuid
          examples:
            cat:
              value: 01936c8f-1234-7000-8000-111111111111
              summary: A cat ID
            dog:
              value: 01936c8f-2345-7000-8000-222222222222
              summary: A dog ID
      get:
        summary: Get Pet Details
        description: Retrieve detailed information about a specific pet
        operationId: getPetById
        tags:
          - Pet
        security: []
        responses:
          '200':
            description: Pet found
            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/Pet'
          '404':
            $ref: '#/components/responses/NotFound'
          '429':
            $ref: '#/components/responses/TooManyRequests'
      put:
        summary: Update Pet
        description: Update information for an existing pet
        operationId: updatePetById
        tags:
          - Pet
        security:
          - oauth2:
              - write:pets
        requestBody:
          required: true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
        responses:
          '200':
            description: Pet updated
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/Pet'
          '401':
            $ref: '#/components/responses/Unauthorized'
          '404':
            $ref: '#/components/responses/NotFound'
      delete:
        summary: Delete Pet
        description: Remove a pet from the system
        operationId: deletePetById
        tags:
          - Pet
        security:
          - oauth2:
              - write:pets
        responses:
          '204':
            description: Pet deleted
          '401':
            $ref: '#/components/responses/Unauthorized'
          '404':
            $ref: '#/components/responses/NotFound'
  mediaTypes:
    pet-json:
      schema:
        $ref: '#/components/schemas/Pet'
      examples:
        cat-example:
          summary: A friendly cat
          value:
            id: 01936c8f-1234-7000-8000-111111111111
            species: CAT
            name: Whiskers
            breed: Domestic Shorthair
            ageMonths: 18
            size: MEDIUM
            goodWithKids: true

            price: "75.00"
            status: AVAILABLE
        dog-example:
          summary: An energetic dog
          value:
            id: 01936c8f-2345-7000-8000-222222222222
            species: DOG
            name: Max
            breed: Labrador Retriever
            ageMonths: 24
            size: LARGE
            goodWithKids: true

            price: "150.00"
            status: AVAILABLE
    pet-collection-json:
      schema:
        type: object
        required:
          - data
          - pagination
        properties:
          data:
            type: array
            items:
              $ref: '#/components/schemas/Pet'
          pagination:
            $ref: '#/components/schemas/PaginationInfo'
      examples:
        pets-page-1:
          summary: First page of pets
          value:
            data:
              - id: 01936c8f-1234-7000-8000-111111111111
                species: CAT
                name: Whiskers
                ageMonths: 18
                status: AVAILABLE
            pagination:
              page: 1
              limit: 20
              totalItems: 45
              totalPages: 3
    event-stream:
      schema:
        type: string
        contentMediaType: text/event-stream
        description: Server-Sent Events stream with incremental chat completion tokens
      examples:
        chat-stream:
          summary: Chat completion stream
          value: >+
            data:
            {"id":"chatcmpl_abc123","object":"chat.completion.chunk","choices":[{"delta":{"content":"Hello"},"index":0}]}


            data: {"id":"chatcmpl_abc123","object":"chat.completion.chunk","choices":[{"delta":{"content":"
            there!"},"index":0}]}


            data: [DONE]

    problem-json:
      schema:
        $ref: '#/components/schemas/ProblemDetails'
      examples:
        not-found:
          summary: Resource not found
          value:
            type: https://petstoreapi.com/errors/not-found
            title: Not Found
            status: 404
            detail: The requested pet with ID '00000000-0000-0000-0000-invalid00000' was not found
            instance: /v1/pets/00000000-0000-0000-0000-invalid00000
servers:
  - url: https://api.petstoreapi.com/v1
    description: Production server
security:
  - bearerAuth: []
  - oauth2: []
webhooks:
  orderStatusChanged:
    post:
      summary: Order Status Changed Event
      description: >-
        Triggered when an order's status changes. This webhook notifies your system of order lifecycle events,
        enabling real-time updates for order tracking, notifications, and fulfillment workflows.


        ## Status Transitions


        Orders follow this lifecycle:

        - `PLACED` → `APPROVED` (payment confirmed)

        - `APPROVED` → `SHIPPED` (order dispatched)

        - `SHIPPED` → `DELIVERED` (order completed)

        - Any status → `CANCELLED` (order cancelled)


        ## Webhook Security


        All webhooks include a signature header (`X-Webhook-Signature`) for verification.
        See our [webhook security guide](https://petstoreapi.com/docs/webhooks/security) for implementation details.
      operationId: orderStatusChangedWebhook
      tags:
        - Webhooks
      externalDocs:
        description: Webhook Integration Guide
        url: https://petstoreapi.com/docs/webhooks/integration-guide
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - eventId
                - eventType
                - timestamp
                - data
              properties:
                eventId:
                  type: string
                  format: uuid
                  description: Unique identifier for this webhook event
                  examples:
                    - evt_9f4a8b3c-2d5e-6f7g-8h9i-0j1k2l3m4n5o
                eventType:
                  type: string
                  const: order.statusChanged
                  description: Type of event
                timestamp:
                  type: string
                  format: date-time
                  description: When the event occurred (RFC 3339)
                data:
                  type: object
                  required:
                    - order
                    - previousStatus
                    - newStatus
                  properties:
                    order:
                      $ref: '#/components/schemas/Order'
                    previousStatus:
                      type: string
                      enum:
                        - PLACED
                        - APPROVED
                        - SHIPPED
                        - DELIVERED
                        - CANCELLED
                      description: The order status before this change
                    newStatus:
                      type: string
                      enum:
                        - PLACED
                        - APPROVED
                        - SHIPPED
                        - DELIVERED
                        - CANCELLED
                      description: The new order status after this change
                    changedAt:
                      type: string
                      format: date-time
                      description: When the status change occurred
                    changedBy:
                      type: string
                      description: Identifier of who/what triggered the change (user ID or system)
                  unevaluatedProperties: false
              unevaluatedProperties: false
            examples:
              order-approved:
                summary: Order approved after payment
                value:
                  eventId: evt_9f4a8b3c-2d5e-6f7g-8h9i-0j1k2l3m4n5o
                  eventType: order.statusChanged
                  timestamp: '2024-12-16T10:30:00Z'
                  data:
                    order:
                      id: 019b4139-1234-7abc-8def-123456789abc
                      petId: 019b4132-70aa-764f-b315-e2803d882a24
                      userId: 019b4138-e0af-70b9-8f0c-6ea97d495dfa
                      status: APPROVED
                      totalAmount: "125.50"
                      currency: USD
                      createdAt: '2024-12-16T09:00:00Z'
                      updatedAt: '2024-12-16T10:30:00Z'
                    previousStatus: PLACED
                    newStatus: APPROVED
                    changedAt: '2024-12-16T10:30:00Z'
                    changedBy: system
              order-shipped:
                summary: Order shipped for delivery
                value:
                  eventId: evt_1a2b3c4d-5e6f-7g8h-9i0j-k1l2m3n4o5p6
                  eventType: order.statusChanged
                  timestamp: '2024-12-17T14:00:00Z'
                  data:
                    order:
                      id: 019b4139-1234-7abc-8def-123456789abc
                      petId: 019b4132-70aa-764f-b315-e2803d882a24
                      userId: 019b4138-e0af-70b9-8f0c-6ea97d495dfa
                      status: SHIPPED
                      totalAmount: "125.50"
                      currency: USD
                      createdAt: '2024-12-16T09:00:00Z'
                      updatedAt: '2024-12-17T14:00:00Z'
                    previousStatus: APPROVED
                    newStatus: SHIPPED
                    changedAt: '2024-12-17T14:00:00Z'
                    changedBy: staff_user_123
              order-cancelled:
                summary: Order cancelled by user
                value:
                  eventId: evt_2b3c4d5e-6f7g-8h9i-0j1k-l2m3n4o5p6q7
                  eventType: order.statusChanged
                  timestamp: '2024-12-16T11:15:00Z'
                  data:
                    order:
                      id: 019b4139-5678-7def-9012-345678901234
                      petId: 019b4127-54d5-76d9-b626-0d4c7bfce5b6
                      userId: 019b4128-6a6b-777c-9ae8-335e962c68d8
                      status: CANCELLED
                      totalAmount: "75.00"
                      currency: USD
                      createdAt: '2024-12-16T08:00:00Z'
                      updatedAt: '2024-12-16T11:15:00Z'
                    previousStatus: PLACED
                    newStatus: CANCELLED
                    changedAt: '2024-12-16T11:15:00Z'
                    changedBy: usr_019b4128-6a6b-777c-9ae8-335e962c68d8
      responses:
        '200':
          description: Webhook received successfully
        '401':
          description: Invalid webhook signature
  paymentSucceeded:
    post:
      summary: Payment Succeeded Event
      description: >-
        Triggered when a payment is successfully processed and confirmed. This webhook notifies your system
        of successful payment transactions, enabling real-time updates for order fulfillment, customer notifications,
        and accounting workflows.


        ## Payment Processing


        When a payment succeeds:

        - Payment status changes to `SUCCEEDED`

        - Order status typically updates to `APPROVED`

        - Payment receipt is generated

        - Funds are confirmed and captured


        ## Webhook Security


        All webhooks include a signature header (`X-Webhook-Signature`) for verification.
        See our [webhook security guide](https://petstoreapi.com/docs/webhooks/security) for implementation details.
      operationId: paymentSucceededWebhook
      tags:
        - Webhooks
      externalDocs:
        description: Payment Webhook Integration Guide
        url: https://petstoreapi.com/docs/webhooks/payment-integration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - eventId
                - eventType
                - timestamp
                - data
              properties:
                eventId:
                  type: string
                  format: uuid
                  description: Unique identifier for this webhook event
                  examples:
                    - evt_3c4d5e6f-7g8h-9i0j-1k2l-3m4n5o6p7q8r
                eventType:
                  type: string
                  const: payment.succeeded
                  description: Type of event
                timestamp:
                  type: string
                  format: date-time
                  description: When the event occurred (RFC 3339)
                data:
                  type: object
                  required:
                    - payment
                    - order
                  properties:
                    payment:
                      $ref: '#/components/schemas/OrderPayment'
                    order:
                      $ref: '#/components/schemas/Order'
                    receipt:
                      type: object
                      description: Payment receipt information
                      properties:
                        receiptId:
                          type: string
                          format: uuid
                          description: Unique receipt identifier
                        receiptUrl:
                          type: string
                          format: uri
                          description: URL to download the receipt
                        generatedAt:
                          type: string
                          format: date-time
                          description: When the receipt was generated
                  unevaluatedProperties: false
              unevaluatedProperties: false
            examples:
              card-payment-success:
                summary: Successful card payment
                value:
                  eventId: evt_3c4d5e6f-7g8h-9i0j-1k2l-3m4n5o6p7q8r
                  eventType: payment.succeeded
                  timestamp: '2024-12-16T10:30:15Z'
                  data:
                    payment:
                      id: 2e3b4f5a-6b7c-8d9e-0f1a-2b3c4d5e6f7a
                      amount: "125.50"
                      currency: USD
                      source:
                        object: card
                        name: Jane Doe
                        number: '************4242'
                        expMonth: 12
                        expYear: 2025
                        brand: VISA
                        addressCountry: us
                        addressPostCode: '10001'
                      status: SUCCEEDED
                      createdAt: '2024-12-16T10:30:00Z'
                    order:
                      id: 019b4139-1234-7abc-8def-123456789abc
                      petId: 019b4132-70aa-764f-b315-e2803d882a24
                      userId: 019b4138-e0af-70b9-8f0c-6ea97d495dfa
                      status: APPROVED
                      totalAmount: "125.50"
                      currency: USD
                      createdAt: '2024-12-16T09:00:00Z'
                      updatedAt: '2024-12-16T10:30:15Z'
                    receipt:
                      receiptId: rcp_4d5e6f7g-8h9i-0j1k-2l3m-4n5o6p7q8r9s
                      receiptUrl: https://api.petstoreapi.com/v1/receipts/rcp_4d5e6f7g-8h9i-0j1k-2l3m-4n5o6p7q8r9s
                      generatedAt: '2024-12-16T10:30:15Z'
              bank-payment-success:
                summary: Successful bank account payment
                value:
                  eventId: evt_5f6g7h8i-9j0k-1l2m-3n4o-5p6q7r8s9t0u
                  eventType: payment.succeeded
                  timestamp: '2024-12-16T15:45:30Z'
                  data:
                    payment:
                      id: 3f4g5h6i-7j8k-9l0m-1n2o-3p4q5r6s7t8u
                      amount: "75.00"
                      currency: USD
                      source:
                        object: bank_account
                        accountHolderName: John Smith
                        accountNumber: '*********5678'
                        routingNumber: '110000000'
                        accountType: CHECKING
                        bankName: Chase Bank
                        last4: '5678'
                      status: SUCCEEDED
                      createdAt: '2024-12-16T15:45:00Z'
                    order:
                      id: 019b4139-5678-7def-9012-345678901234
                      petId: 019b4127-54d5-76d9-b626-0d4c7bfce5b6
                      userId: 019b4128-6a6b-777c-9ae8-335e962c68d8
                      status: APPROVED
                      totalAmount: "75.00"
                      currency: USD
                      createdAt: '2024-12-16T15:30:00Z'
                      updatedAt: '2024-12-16T15:45:30Z'
                    receipt:
                      receiptId: rcp_6g7h8i9j-0k1l-2m3n-4o5p-6q7r8s9t0u1v
                      receiptUrl: https://api.petstoreapi.com/v1/receipts/rcp_6g7h8i9j-0k1l-2m3n-4o5p-6q7r8s9t0u1v
                      generatedAt: '2024-12-16T15:45:30Z'
      responses:
        '200':
          description: Webhook received successfully
        '401':
          description: Invalid webhook signature