openapi: 3.1.0
info:
  title: PhotoMentor Public API
  version: "1.0"
  description: >
    Analyze a single photograph and receive a structured critique including
    score, genre, verdict, full critique, strengths, weaknesses, advice
    variants, visual facts, and mood.
servers:
  - url: https://api.photomentor.pro/api/v1
paths:
  /analyze:
    post:
      operationId: analyzePhotoPublic
      summary: Analyze a photograph
      description: >
        Accepts one image as multipart/form-data and returns a structured
        photography critique.
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              additionalProperties: false
              properties:
                image:
                  type: string
                  format: binary
                  description: JPEG, PNG, WebP, or GIF image up to 20 MB.
                language:
                  type: string
                  enum: [en, ru, de, es]
                  default: en
                  description: Response language.
                tone_mode:
                  type: string
                  enum: [brutal, supportive]
                  default: brutal
                  description: Critique tone mode.
              required:
                - image
      responses:
        "200":
          description: Successful analysis
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PublicAnalyzeResponse"
        "401":
          description: Missing or invalid API key
        "413":
          description: Image too large
        "422":
          description: Unsupported or invalid image
        "429":
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Analysis failed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
  schemas:
    PublicAnalyzeResponse:
      type: object
      additionalProperties: false
      properties:
        request_id:
          type: string
          description: Unique request identifier.
        score:
          type: number
          description: Overall score from 0 to 10.
        genre:
          type: string
          description: Auto-detected photography genre.
        verdict:
          type: string
          description: One-line hard-truth summary.
        critique:
          type: string
          description: Full critique text.
        strengths:
          type: array
          items:
            type: string
        weaknesses:
          type: array
          items:
            type: string
        advice:
          type: object
          additionalProperties: false
          properties:
            purist:
              type: string
            standard:
              type: string
            creative:
              type: string
          required:
            - purist
            - standard
            - creative
        visual_facts:
          type: string
        mood:
          type: string
      required:
        - request_id
        - score
        - genre
        - verdict
        - critique
        - strengths
        - weaknesses
        - advice
        - visual_facts
        - mood
    ErrorResponse:
      type: object
      additionalProperties: true
      properties:
        detail:
          type: string
        error:
          type: string
        message:
          type: string