openapi: 3.1.0
info:
  title: Cat Facts 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
paths:
  /fact:
    get:
      operationId: getRandomFact
      summary: Get a random cat fact
      description: Returns a single random cat fact.
      parameters:
        - name: max_length
          in: query
          required: false
          description: Maximum length of returned fact in characters.
          schema:
            type: integer
            minimum: 1
      responses:
        '200':
          description: A single cat fact
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Fact'
              example:
                fact: "In multi-cat households, cats of the opposite sex usually get along better."
                length: 75
        '404':
          description: No fact found matching criteria
  /facts:
    get:
      operationId: getFacts
      summary: Get a paginated list of cat facts
      description: Returns a paginated list of cat facts.
      parameters:
        - name: max_length
          in: query
          required: false
          description: Maximum length of returned facts in characters.
          schema:
            type: integer
            minimum: 1
        - name: limit
          in: query
          required: false
          description: Number of facts 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 facts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FactList'
              example:
                current_page: 1
                data:
                  - fact: "Unlike dogs, cats do not have a sweet tooth. Scientists believe this is due to a mutation in a key taste receptor."
                    length: 114
                  - fact: "When a cat chases its prey, it keeps its head level. Dogs and humans bob their heads up and down."
                    length: 97
                first_page_url: "https://catfact.ninja/facts?page=1"
                from: 1
                last_page: 166
                last_page_url: "https://catfact.ninja/facts?page=166"
                next_page_url: "https://catfact.ninja/facts?page=2"
                path: "https://catfact.ninja/facts"
                per_page: 10
                prev_page_url: null
                to: 10
                total: 1656
  /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
components:
  schemas:
    Fact:
      type: object
      description: A single cat fact with its character length.
      required:
        - fact
        - length
      properties:
        fact:
          type: string
          description: The cat fact text.
          example: "In multi-cat households, cats of the opposite sex usually get along better."
        length:
          type: integer
          description: Character length of the fact.
          example: 75
    FactList:
      type: object
      description: Paginated list of cat facts (Laravel-style pagination).
      properties:
        current_page:
          type: integer
          description: Current page number.
          example: 1
        data:
          type: array
          description: Array of cat facts on this page.
          items:
            $ref: '#/components/schemas/Fact'
        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: 166
        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 facts.
          example: 1656
    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"
    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.