openapi: 3.0.3
info:
  title: Cataas Admin Catalog API
  version: 1.0.0
  description: CATAAS (Cat as a Service) is a free, no-authentication REST API that returns random cat images and GIFs with optional tags, filters, sizing, and text overlays. It is an open-source project published under the GitHub cataas organization (https://github.com/cataas/cataas) and is consumed primarily as image URLs that can be embedded directly into HTML, README files, and chat applications.
  contact:
    name: CATAAS Project
    url: https://github.com/cataas/cataas
  license:
    name: Open Source (no SPDX declared)
    url: https://github.com/cataas/cataas
  x-generated-from: documentation
  x-last-validated: '2026-05-30'
servers:
- url: https://cataas.com
  description: Public production API
tags:
- name: Catalog
  description: Browse cats, tags, and stats programmatically (JSON)
paths:
  /api/cats:
    get:
      operationId: listCats
      summary: CATAAS List Cats in the Catalog
      description: Returns an array of cat documents. Filter by tags and paginate using `skip` and `limit`. Use this endpoint to discover ids consumable by `/cat/{id}`.
      tags:
      - Catalog
      parameters:
      - name: tags
        in: query
        description: Comma-separated list of tags to filter on. Returns only cats that carry at least one of the given tags.
        required: false
        schema:
          type: string
        example: cute,orange
      - name: skip
        in: query
        description: Number of records to skip for pagination.
        required: false
        schema:
          type: integer
          minimum: 0
        example: 0
      - name: limit
        in: query
        description: Maximum number of records to return.
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 1000
        example: 25
      responses:
        '200':
          description: Array of cat documents
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Cat'
              examples:
                ListCats200Example:
                  summary: Default listCats 200 response
                  x-microcks-default: true
                  value:
                  - _id: 595f280b557291a9750ebf66
                    id: 595f280b557291a9750ebf66
                    tags:
                    - cute
                    - orange
                    mimetype: image/jpeg
                    size: 18234
                    created_at: '2026-05-29T14:30:00Z'
                    url: https://cataas.com/cat/595f280b557291a9750ebf66
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /api/tags:
    get:
      operationId: listTags
      summary: CATAAS List All Available Tags
      description: Returns a sorted array of every unique tag attached to a cat in the catalog.
      tags:
      - Catalog
      responses:
        '200':
          description: Sorted array of tag strings
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
              examples:
                ListTags200Example:
                  summary: Default listTags 200 response
                  x-microcks-default: true
                  value:
                  - black
                  - cute
                  - gif
                  - orange
                  - sleepy
                  - white
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /api/count:
    get:
      operationId: getCatCount
      summary: CATAAS Get the Total Number of Cats
      description: Returns a single document with the total count of cats in the catalog.
      tags:
      - Catalog
      responses:
        '200':
          description: Total cat count
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CountResponse'
              examples:
                GetCatCount200Example:
                  summary: Default getCatCount 200 response
                  x-microcks-default: true
                  value:
                    count: 9384
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    CountResponse:
      title: CountResponse
      type: object
      description: Total count of cats in the catalog.
      required:
      - count
      properties:
        count:
          type: integer
          description: Total number of cats in the catalog.
          example: 9384
    Cat:
      title: Cat
      type: object
      description: A cat catalog document.
      required:
      - id
      - tags
      properties:
        _id:
          type: string
          description: MongoDB document id of the cat.
          example: 595f280b557291a9750ebf66
        id:
          type: string
          description: Public id of the cat (mirror of `_id`).
          example: 595f280b557291a9750ebf66
        tags:
          type: array
          description: Tags attached to this cat.
          items:
            type: string
          example:
          - cute
          - orange
        mimetype:
          type: string
          description: MIME type of the cat image file.
          example: image/jpeg
        size:
          type: integer
          description: Size of the cat image file in bytes.
          example: 18234
        created_at:
          type: string
          format: date-time
          description: Timestamp when the cat document was created.
          example: '2026-05-29T14:30:00Z'
        edited_at:
          type: string
          format: date-time
          description: Timestamp when the cat document was last edited.
          example: '2026-05-29T15:00:00Z'
        validated:
          type: boolean
          description: Whether this cat has been moderated and approved for the public catalog.
          example: true
        url:
          type: string
          format: uri
          description: Direct URL to the cat image.
          example: https://cataas.com/cat/595f280b557291a9750ebf66
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Admin-only bearer token for moderation and catalog management.