openapi: 3.0.3
info:
  title: Cataas Admin Upload 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: Upload
  description: Submit a cat image (rate-limited / moderated)
paths:
  /upload:
    post:
      operationId: uploadCat
      summary: CATAAS Upload a New Cat Image
      description: Submit a new cat image to the catalog. The image is validated as a real image file before being persisted. May require moderation before appearing in `/api/cats`.
      tags:
      - Upload
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/UploadCatRequest'
            examples:
              UploadCatRequestExample:
                summary: Default uploadCat request
                x-microcks-default: true
                value:
                  tags: cute,orange
      responses:
        '200':
          description: The newly created cat document
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Cat'
        '400':
          $ref: '#/components/responses/BadRequest'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    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
    UploadCatRequest:
      title: UploadCatRequest
      type: object
      description: Multipart upload payload for a new cat image.
      required:
      - file
      properties:
        file:
          type: string
          format: binary
          description: The cat image file (JPEG, PNG, or GIF).
        tags:
          type: string
          description: Comma-separated list of tags to apply to the new cat.
          example: cute,orange
    ErrorResponse:
      title: ErrorResponse
      type: object
      description: Generic error response.
      required:
      - error
      properties:
        error:
          type: object
          description: Error details.
          properties:
            name:
              type: string
              description: Error class name.
              example: NotFoundError
            message:
              type: string
              description: Human-readable error description.
              example: Cat not found
  responses:
    BadRequest:
      description: Invalid input
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            BadRequestExample:
              summary: Default 400 response
              x-microcks-default: true
              value:
                error:
                  name: ValidationError
                  message: Uploaded file is not a valid image
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Admin-only bearer token for moderation and catalog management.