openapi: 3.1.0
info:
  title: Dog Breeds Images API
  description: The Dog API (dog.ceo) is the internet's largest collection of open-source dog pictures, exposing over 20,000 dog images accessible by more than 120 breeds. The API is free, requires no authentication, and returns JSON. An optional `alt` variant returns image URLs paired with descriptive alt text for accessibility. The canonical implementation is the open-source PHP Symfony project at github.com/ElliottLandsborough/dog-ceo-api, licensed MIT.
  version: 1.1.0
  contact:
    name: Dog API
    url: https://dog.ceo/dog-api/
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  x-generated-from: documentation+source
  x-source-url: https://github.com/ElliottLandsborough/dog-ceo-api/blob/main/src/Controller/MainController.php
  x-last-validated: '2026-05-30'
servers:
- url: https://dog.ceo/api
  description: Dog API production server
tags:
- name: Images
  description: Fetch random or breed-specific dog images (with optional alt text).
paths:
  /breed/{breed}/images:
    get:
      tags:
      - Images
      summary: Dog API List Images by Breed
      description: Returns all image URLs for a given master breed.
      operationId: listImagesByBreed
      parameters:
      - name: breed
        in: path
        required: true
        description: Master breed name.
        schema:
          type: string
        example: hound
      responses:
        '200':
          description: An array of image URLs for the breed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImageListResponse'
              examples:
                ListImagesByBreed200Example:
                  summary: Default listImagesByBreed 200 response
                  x-microcks-default: true
                  value:
                    message:
                    - https://images.dog.ceo/breeds/hound-afghan/n02088094_1003.jpg
                    - https://images.dog.ceo/breeds/hound-afghan/n02088094_1023.jpg
                    - https://images.dog.ceo/breeds/hound-afghan/n02088094_10263.jpg
                    status: success
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /breed/{breed}/images/random:
    get:
      tags:
      - Images
      summary: Dog API Random Image by Breed
      description: Returns a single random image URL for the given master breed.
      operationId: randomImageByBreed
      parameters:
      - name: breed
        in: path
        required: true
        description: Master breed name.
        schema:
          type: string
        example: hound
      responses:
        '200':
          description: A single random image URL for the breed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImageResponse'
              examples:
                RandomImageByBreed200Example:
                  summary: Default randomImageByBreed 200 response
                  x-microcks-default: true
                  value:
                    message: https://images.dog.ceo/breeds/hound-afghan/n02088094_1003.jpg
                    status: success
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /breed/{breed}/images/random/{amount}:
    get:
      tags:
      - Images
      summary: Dog API Multiple Random Images by Breed
      description: Returns multiple random image URLs for the given master breed.
      operationId: randomImagesByBreed
      parameters:
      - name: breed
        in: path
        required: true
        description: Master breed name.
        schema:
          type: string
        example: hound
      - name: amount
        in: path
        required: true
        description: Number of random images to return.
        schema:
          type: integer
          minimum: 1
        example: 3
      responses:
        '200':
          description: An array of random image URLs for the breed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImageListResponse'
              examples:
                RandomImagesByBreed200Example:
                  summary: Default randomImagesByBreed 200 response
                  x-microcks-default: true
                  value:
                    message:
                    - https://images.dog.ceo/breeds/hound-afghan/n02088094_1003.jpg
                    - https://images.dog.ceo/breeds/hound-afghan/n02088094_1023.jpg
                    - https://images.dog.ceo/breeds/hound-afghan/n02088094_10263.jpg
                    status: success
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /breed/{breed}/{subBreed}/images:
    get:
      tags:
      - Images
      summary: Dog API List Images by Sub-Breed
      description: Returns all image URLs for a given sub-breed.
      operationId: listImagesBySubBreed
      parameters:
      - name: breed
        in: path
        required: true
        description: Master breed name.
        schema:
          type: string
        example: hound
      - name: subBreed
        in: path
        required: true
        description: Sub-breed name.
        schema:
          type: string
        example: afghan
      responses:
        '200':
          description: An array of image URLs for the sub-breed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImageListResponse'
              examples:
                ListImagesBySubBreed200Example:
                  summary: Default listImagesBySubBreed 200 response
                  x-microcks-default: true
                  value:
                    message:
                    - https://images.dog.ceo/breeds/hound-afghan/n02088094_1003.jpg
                    - https://images.dog.ceo/breeds/hound-afghan/n02088094_1023.jpg
                    - https://images.dog.ceo/breeds/hound-afghan/n02088094_10263.jpg
                    status: success
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /breed/{breed}/{subBreed}/images/random:
    get:
      tags:
      - Images
      summary: Dog API Random Image by Sub-Breed
      description: Returns a single random image URL for the given sub-breed.
      operationId: randomImageBySubBreed
      parameters:
      - name: breed
        in: path
        required: true
        description: Master breed name.
        schema:
          type: string
        example: hound
      - name: subBreed
        in: path
        required: true
        description: Sub-breed name.
        schema:
          type: string
        example: afghan
      responses:
        '200':
          description: A single random image URL for the sub-breed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImageResponse'
              examples:
                RandomImageBySubBreed200Example:
                  summary: Default randomImageBySubBreed 200 response
                  x-microcks-default: true
                  value:
                    message: https://images.dog.ceo/breeds/hound-afghan/n02088094_1003.jpg
                    status: success
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /breed/{breed}/{subBreed}/images/random/{amount}:
    get:
      tags:
      - Images
      summary: Dog API Multiple Random Images by Sub-Breed
      description: Returns multiple random image URLs for the given sub-breed.
      operationId: randomImagesBySubBreed
      parameters:
      - name: breed
        in: path
        required: true
        description: Master breed name.
        schema:
          type: string
        example: hound
      - name: subBreed
        in: path
        required: true
        description: Sub-breed name.
        schema:
          type: string
        example: afghan
      - name: amount
        in: path
        required: true
        description: Number of random images to return.
        schema:
          type: integer
          minimum: 1
        example: 3
      responses:
        '200':
          description: An array of random image URLs for the sub-breed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImageListResponse'
              examples:
                RandomImagesBySubBreed200Example:
                  summary: Default randomImagesBySubBreed 200 response
                  x-microcks-default: true
                  value:
                    message:
                    - https://images.dog.ceo/breeds/hound-afghan/n02088094_1003.jpg
                    - https://images.dog.ceo/breeds/hound-afghan/n02088094_1023.jpg
                    - https://images.dog.ceo/breeds/hound-afghan/n02088094_10263.jpg
                    status: success
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /breeds/image/random:
    get:
      tags:
      - Images
      summary: Dog API Random Image From Any Breed
      description: Returns a random dog image URL from any breed.
      operationId: randomImage
      responses:
        '200':
          description: A single random image URL.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImageResponse'
              examples:
                RandomImage200Example:
                  summary: Default randomImage 200 response
                  x-microcks-default: true
                  value:
                    message: https://images.dog.ceo/breeds/hound-afghan/n02088094_1003.jpg
                    status: success
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /breeds/image/random/{amount}:
    get:
      tags:
      - Images
      summary: Dog API Multiple Random Images From Any Breed
      description: Returns multiple random dog image URLs from any breed.
      operationId: randomImages
      parameters:
      - name: amount
        in: path
        required: true
        description: Number of random images to return.
        schema:
          type: integer
          minimum: 1
        example: 3
      responses:
        '200':
          description: An array of random image URLs.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImageListResponse'
              examples:
                RandomImages200Example:
                  summary: Default randomImages 200 response
                  x-microcks-default: true
                  value:
                    message:
                    - https://images.dog.ceo/breeds/hound-afghan/n02088094_1003.jpg
                    - https://images.dog.ceo/breeds/hound-afghan/n02088094_1023.jpg
                    - https://images.dog.ceo/breeds/hound-afghan/n02088094_10263.jpg
                    status: success
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /breeds/image/random/{amount}/alt:
    get:
      tags:
      - Images
      summary: Dog API Multiple Random Images From Any Breed With Alt Text
      description: Returns multiple random images from any breed paired with descriptive alt text.
      operationId: randomImagesWithAlt
      parameters:
      - name: amount
        in: path
        required: true
        description: Number of random images to return.
        schema:
          type: integer
          minimum: 1
        example: 3
      responses:
        '200':
          description: An array of image objects each containing a URL and alt text.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AltImageListResponse'
              examples:
                RandomImagesWithAlt200Example:
                  summary: Default randomImagesWithAlt 200 response
                  x-microcks-default: true
                  value:
                    message:
                    - url: https://images.dog.ceo/breeds/hound-basset/n02088238_2217.jpg
                      altText: Basset hound dog
                    - url: https://images.dog.ceo/breeds/hound-blood/n02088466_6712.jpg
                      altText: Blood hound dog
                    status: success
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /breed/{breed}/images/alt:
    get:
      tags:
      - Images
      summary: Dog API List Images by Breed With Alt Text
      description: Returns all images for the given master breed paired with descriptive alt text.
      operationId: listImagesByBreedWithAlt
      parameters:
      - name: breed
        in: path
        required: true
        description: Master breed name.
        schema:
          type: string
        example: hound
      responses:
        '200':
          description: An array of image objects each containing a URL and alt text.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AltImageListResponse'
              examples:
                ListImagesByBreedWithAlt200Example:
                  summary: Default listImagesByBreedWithAlt 200 response
                  x-microcks-default: true
                  value:
                    message:
                    - url: https://images.dog.ceo/breeds/hound-basset/n02088238_2217.jpg
                      altText: Basset hound dog
                    - url: https://images.dog.ceo/breeds/hound-blood/n02088466_6712.jpg
                      altText: Blood hound dog
                    status: success
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /breed/{breed}/images/random/{amount}/alt:
    get:
      tags:
      - Images
      summary: Dog API Multiple Random Images by Breed With Alt Text
      description: Returns multiple random images for the given master breed paired with descriptive alt text.
      operationId: randomImagesByBreedWithAlt
      parameters:
      - name: breed
        in: path
        required: true
        description: Master breed name.
        schema:
          type: string
        example: hound
      - name: amount
        in: path
        required: true
        description: Number of random images to return.
        schema:
          type: integer
          minimum: 1
        example: 3
      responses:
        '200':
          description: An array of image objects each containing a URL and alt text.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AltImageListResponse'
              examples:
                RandomImagesByBreedWithAlt200Example:
                  summary: Default randomImagesByBreedWithAlt 200 response
                  x-microcks-default: true
                  value:
                    message:
                    - url: https://images.dog.ceo/breeds/hound-basset/n02088238_2217.jpg
                      altText: Basset hound dog
                    - url: https://images.dog.ceo/breeds/hound-blood/n02088466_6712.jpg
                      altText: Blood hound dog
                    status: success
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /breed/{breed}/{subBreed}/images/alt:
    get:
      tags:
      - Images
      summary: Dog API List Images by Sub-Breed With Alt Text
      description: Returns all images for the given sub-breed paired with descriptive alt text.
      operationId: listImagesBySubBreedWithAlt
      parameters:
      - name: breed
        in: path
        required: true
        description: Master breed name.
        schema:
          type: string
        example: hound
      - name: subBreed
        in: path
        required: true
        description: Sub-breed name.
        schema:
          type: string
        example: afghan
      responses:
        '200':
          description: An array of image objects each containing a URL and alt text.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AltImageListResponse'
              examples:
                ListImagesBySubBreedWithAlt200Example:
                  summary: Default listImagesBySubBreedWithAlt 200 response
                  x-microcks-default: true
                  value:
                    message:
                    - url: https://images.dog.ceo/breeds/hound-basset/n02088238_2217.jpg
                      altText: Basset hound dog
                    - url: https://images.dog.ceo/breeds/hound-blood/n02088466_6712.jpg
                      altText: Blood hound dog
                    status: success
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /breed/{breed}/{subBreed}/images/random/{amount}/alt:
    get:
      tags:
      - Images
      summary: Dog API Multiple Random Images by Sub-Breed With Alt Text
      description: Returns multiple random images for the given sub-breed paired with descriptive alt text.
      operationId: randomImagesBySubBreedWithAlt
      parameters:
      - name: breed
        in: path
        required: true
        description: Master breed name.
        schema:
          type: string
        example: hound
      - name: subBreed
        in: path
        required: true
        description: Sub-breed name.
        schema:
          type: string
        example: afghan
      - name: amount
        in: path
        required: true
        description: Number of random images to return.
        schema:
          type: integer
          minimum: 1
        example: 3
      responses:
        '200':
          description: An array of image objects each containing a URL and alt text.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AltImageListResponse'
              examples:
                RandomImagesBySubBreedWithAlt200Example:
                  summary: Default randomImagesBySubBreedWithAlt 200 response
                  x-microcks-default: true
                  value:
                    message:
                    - url: https://images.dog.ceo/breeds/hound-basset/n02088238_2217.jpg
                      altText: Basset hound dog
                    - url: https://images.dog.ceo/breeds/hound-blood/n02088466_6712.jpg
                      altText: Blood hound dog
                    status: success
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    AltImage:
      type: object
      description: A dog image URL paired with descriptive alt text suitable for accessibility.
      required:
      - url
      - altText
      properties:
        url:
          type: string
          format: uri
          description: URL of the dog image.
          example: https://images.dog.ceo/breeds/hound-basset/n02088238_2217.jpg
        altText:
          type: string
          description: Human-readable alt text describing the image (typically "{Sub-breed} {breed} dog").
          example: Basset hound dog
    ImageResponse:
      type: object
      description: Response envelope returning a single dog image URL.
      required:
      - message
      - status
      properties:
        message:
          type: string
          format: uri
          description: URL of the dog image.
          example: https://images.dog.ceo/breeds/hound-afghan/n02088094_1003.jpg
        status:
          type: string
          description: Outcome marker; "success" when the request succeeded.
          enum:
          - success
          - error
          example: success
    AltImageListResponse:
      type: object
      description: Response envelope returning a list of image objects each containing a URL and alt text.
      required:
      - message
      - status
      properties:
        message:
          type: array
          description: List of image objects with URL and alt text.
          items:
            $ref: '#/components/schemas/AltImage'
        status:
          type: string
          description: Outcome marker; "success" when the request succeeded.
          enum:
          - success
          - error
          example: success
    ImageListResponse:
      type: object
      description: Response envelope returning a list of dog image URLs.
      required:
      - message
      - status
      properties:
        message:
          type: array
          description: List of dog image URLs.
          items:
            type: string
            format: uri
            example: https://images.dog.ceo/breeds/hound-afghan/n02088094_1003.jpg
        status:
          type: string
          description: Outcome marker; "success" when the request succeeded.
          enum:
          - success
          - error
          example: success