openapi: 3.1.0
info:
  title: Cat Breeds 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
tags:
- name: Facts
paths:
  /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
      tags:
      - Facts
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
    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.
    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