openapi: 3.0.3
info:
  title: Dog CEO Breed Sub-Breed API
  description: 'Free REST API providing random dog images organized by breed and sub-breed from 120+ breeds. Backed by the Stanford Dogs Dataset and community-contributed photos. No authentication or API key required. All endpoints return JSON with image URLs served via CDN. Open-source under the MIT license.

    '
  version: 1.0.0
  contact:
    name: Dog CEO API
    url: https://dog.ceo/dog-api/
  license:
    name: MIT
    url: https://github.com/ElliottLandsborough/dog-ceo-api/blob/main/LICENSE
servers:
- url: https://dog.ceo/api
  description: Production server
security: []
tags:
- name: Sub-Breed
  description: Operations for fetching images from a specific sub-breed
paths:
  /breed/{breed}/list:
    get:
      operationId: listSubBreeds
      summary: List sub-breeds of a breed
      description: Returns an array of all sub-breeds for the specified breed.
      tags:
      - Sub-Breed
      parameters:
      - $ref: '#/components/parameters/breed'
      responses:
        '200':
          description: Successful response with sub-breed list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubBreedsListResponse'
              example:
                message:
                - afghan
                - basset
                - blood
                - english
                - ibizan
                - plott
                - walker
                status: success
        '404':
          description: Breed not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /breed/{breed}/{subBreed}/images:
    get:
      operationId: getSubBreedImages
      summary: All images from a sub-breed
      description: Returns an array of all image URLs for a specific sub-breed.
      tags:
      - Sub-Breed
      parameters:
      - $ref: '#/components/parameters/breed'
      - $ref: '#/components/parameters/subBreed'
      responses:
        '200':
          description: Successful response with all sub-breed images
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MultipleImagesResponse'
              example:
                message:
                - https://images.dog.ceo/breeds/hound-afghan/n02088094_1003.jpg
                - https://images.dog.ceo/breeds/hound-afghan/n02088094_1007.jpg
                status: success
        '404':
          description: Breed or sub-breed not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /breed/{breed}/{subBreed}/images/random:
    get:
      operationId: getSubBreedRandomImage
      summary: Random image from a sub-breed
      description: Returns a single random dog image from a specific sub-breed.
      tags:
      - Sub-Breed
      parameters:
      - $ref: '#/components/parameters/breed'
      - $ref: '#/components/parameters/subBreed'
      responses:
        '200':
          description: Successful response with a random sub-breed image URL
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SingleImageResponse'
              example:
                message: https://images.dog.ceo/breeds/hound-afghan/n02088094_1003.jpg
                status: success
        '404':
          description: Breed or sub-breed not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /breed/{breed}/{subBreed}/images/random/{count}:
    get:
      operationId: getSubBreedRandomImages
      summary: Multiple random images from a sub-breed
      description: 'Returns multiple random dog images from a specific sub-breed. Maximum count is 50.

        '
      tags:
      - Sub-Breed
      parameters:
      - $ref: '#/components/parameters/breed'
      - $ref: '#/components/parameters/subBreed'
      - name: count
        in: path
        required: true
        description: Number of images to return (max 50)
        schema:
          type: integer
          minimum: 1
          maximum: 50
          example: 3
      responses:
        '200':
          description: Successful response with multiple random sub-breed images
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MultipleImagesResponse'
        '404':
          description: Breed or sub-breed not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  parameters:
    breed:
      name: breed
      in: path
      required: true
      description: 'The breed name (lowercase). Use the /breeds/list/all endpoint to get all valid breed names.

        '
      schema:
        type: string
        example: hound
    subBreed:
      name: subBreed
      in: path
      required: true
      description: 'The sub-breed name (lowercase). Use the /breed/{breed}/list endpoint to get valid sub-breed names for a given breed.

        '
      schema:
        type: string
        example: afghan
  schemas:
    ErrorResponse:
      type: object
      required:
      - message
      - status
      properties:
        message:
          type: string
          description: Error message describing what went wrong
          example: Breed not found (master breed does not exist)
        status:
          type: string
          enum:
          - error
          example: error
    MultipleImagesResponse:
      type: object
      required:
      - message
      - status
      properties:
        message:
          type: array
          items:
            type: string
            format: uri
          description: Array of dog image URLs
          example:
          - https://images.dog.ceo/breeds/retriever-chesapeake/n02099849_1068.jpg
          - https://images.dog.ceo/breeds/vizsla/n02100583_1214.jpg
        status:
          $ref: '#/components/schemas/ApiStatus'
    ApiStatus:
      type: string
      enum:
      - success
      - error
      description: Indicates whether the API call was successful or encountered an error
    SingleImageResponse:
      type: object
      required:
      - message
      - status
      properties:
        message:
          type: string
          format: uri
          description: URL of the dog image
          example: https://images.dog.ceo/breeds/terrier-silky/n02097658_2882.jpg
        status:
          $ref: '#/components/schemas/ApiStatus'
    SubBreedsListResponse:
      type: object
      required:
      - message
      - status
      properties:
        message:
          type: array
          items:
            type: string
          description: Array of sub-breed names for the requested breed
          example:
          - afghan
          - basset
          - blood
        status:
          $ref: '#/components/schemas/ApiStatus'