openapi: 3.1.0
info:
  title: Cat Facts Breeds API
  description: Free REST API providing random cat facts, breed information, and cat-related trivia for developers building fun applications and learning APIs. No authentication required; CORS enabled for frontend use. Endpoints return paginated JSON data with configurable limits and max-length filters.
  version: 1.0.0
  contact:
    url: https://catfact.ninja/
  license:
    name: MIT
    url: https://github.com/alexwohlbruck/cat-facts/blob/master/LICENSE
servers:
- url: https://catfact.ninja
  description: Production server
tags:
- name: Breeds
paths:
  /breeds:
    get:
      operationId: getBreeds
      summary: Get a paginated list of cat breeds
      description: Returns a paginated list of cat breeds with details.
      parameters:
      - name: limit
        in: query
        required: false
        description: Number of breeds to return per page.
        schema:
          type: integer
          minimum: 1
          maximum: 1000
          default: 10
      - name: page
        in: query
        required: false
        description: Page number for pagination.
        schema:
          type: integer
          minimum: 1
          default: 1
      responses:
        '200':
          description: Paginated list of cat breeds
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BreedList'
              example:
                current_page: 1
                data:
                - breed: Abyssinian
                  country: Ethiopia
                  origin: Natural/Standard
                  coat: Short
                  pattern: Ticked
                - breed: Aegean
                  country: Greece
                  origin: Natural/Standard
                  coat: Semi-long
                  pattern: Bi- or tri-colored
                first_page_url: https://catfact.ninja/breeds?page=1
                from: 1
                last_page: 49
                last_page_url: https://catfact.ninja/breeds?page=49
                next_page_url: https://catfact.ninja/breeds?page=2
                path: https://catfact.ninja/breeds
                per_page: 10
                prev_page_url: null
                to: 10
                total: 487
      tags:
      - Breeds
components:
  schemas:
    BreedList:
      type: object
      description: Paginated list of cat breeds (Laravel-style pagination).
      properties:
        current_page:
          type: integer
          description: Current page number.
          example: 1
        data:
          type: array
          description: Array of cat breeds on this page.
          items:
            $ref: '#/components/schemas/Breed'
        first_page_url:
          type: string
          format: uri
          description: URL of the first page.
        from:
          type: integer
          description: First item number in current page.
          example: 1
        last_page:
          type: integer
          description: Last page number.
          example: 49
        last_page_url:
          type: string
          format: uri
          description: URL of the last page.
        links:
          type: array
          description: Pagination links.
          items:
            $ref: '#/components/schemas/PaginationLink'
        next_page_url:
          type: string
          format: uri
          nullable: true
          description: URL of the next page, or null if on last page.
        path:
          type: string
          format: uri
          description: Base path for this resource.
        per_page:
          type: integer
          description: Number of items per page.
          example: 10
        prev_page_url:
          type: string
          format: uri
          nullable: true
          description: URL of the previous page, or null if on first page.
        to:
          type: integer
          description: Last item number in current page.
          example: 10
        total:
          type: integer
          description: Total number of breeds.
          example: 487
    PaginationLink:
      type: object
      description: A single pagination link entry.
      properties:
        url:
          type: string
          format: uri
          nullable: true
          description: URL for this page link.
        label:
          type: string
          description: Display label for this link (e.g. page number or Previous/Next).
        active:
          type: boolean
          description: Whether this link represents the current page.
    Breed:
      type: object
      description: Information about a cat breed.
      required:
      - breed
      properties:
        breed:
          type: string
          description: Name of the cat breed.
          example: Abyssinian
        country:
          type: string
          description: Country of origin.
          example: Ethiopia
        origin:
          type: string
          description: Origin type (e.g. Natural/Standard, Mutation, Hybrid).
          example: Natural/Standard
        coat:
          type: string
          description: Coat length description.
          example: Short
        pattern:
          type: string
          description: Coat pattern description.
          example: Ticked