openapi: 3.2.0
info:
  title: GPT Backend Gallery API
  version: 0.1.0
servers:
- url: https://api.usepomo.ai
  description: Base URL declared by the provider in apis.yml (roadmap#122).
tags:
- name: gallery
paths:
  /api/gallery/images:
    get:
      tags:
      - gallery
      summary: Get Gallery Images
      description: Get paginated gallery images with filtering and sorting options
      operationId: get_gallery_images_api_gallery_images_get
      security:
      - HTTPBearer: []
      parameters:
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
          title: Page
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 20
          minimum: 1
          default: 20
          title: Limit
      - name: category
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Category
      - name: subcategory
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Subcategory
      - name: media_type
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Media Type
      - name: asset_origin
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            pattern: ^(brand_assets|pomo_generations|external_ads)$
          - type: 'null'
          title: Asset Origin
      - name: ad_platform
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            pattern: ^[A-Za-z0-9_-]{1,32}$
          - type: 'null'
          title: Ad Platform
      - name: performance_tier
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            pattern: ^(high|typical|low|learning)$
          - type: 'null'
          title: Performance Tier
      - name: analysis_status
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            pattern: ^completed$
          - type: 'null'
          title: Analysis Status
      - name: is_favorite
        in: query
        required: false
        schema:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Is Favorite
      - name: search
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Search
      - name: sort_by
        in: query
        required: false
        schema:
          type: string
          pattern: ^(created_at|updated_at|title)$
          default: created_at
          title: Sort By
      - name: sort_order
        in: query
        required: false
        schema:
          type: string
          pattern: ^(asc|desc)$
          default: desc
          title: Sort Order
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GalleryListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/gallery/images/{image_id}:
    get:
      tags:
      - gallery
      summary: Get Gallery Image
      description: Get a specific gallery image by ID
      operationId: get_gallery_image_api_gallery_images__image_id__get
      security:
      - HTTPBearer: []
      parameters:
      - name: image_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Image Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GalleryImageResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    put:
      tags:
      - gallery
      summary: Update Gallery Image
      description: Update gallery image metadata
      operationId: update_gallery_image_api_gallery_images__image_id__put
      security:
      - HTTPBearer: []
      parameters:
      - name: image_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Image Id
      - name: title
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
      - name: description
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
      - name: is_favorite
        in: query
        required: false
        schema:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Is Favorite
      requestBody:
        content:
          application/json:
            schema:
              anyOf:
              - type: array
                items:
                  type: string
              - type: 'null'
              title: Tags
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GalleryImageResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - gallery
      summary: Delete Gallery Image
      description: Delete a gallery image (soft delete by default, permanent if specified)
      operationId: delete_gallery_image_api_gallery_images__image_id__delete
      security:
      - HTTPBearer: []
      parameters:
      - name: image_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Image Id
      - name: permanent
        in: query
        required: false
        schema:
          type: boolean
          default: false
          title: Permanent
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/gallery/images/{image_id}/preview:
    get:
      tags:
      - gallery
      summary: Get Gallery Image Preview
      description: Proxy a gallery image or managed video poster through profile-scoped auth.
      operationId: get_gallery_image_preview_api_gallery_images__image_id__preview_get
      security:
      - HTTPBearer: []
      parameters:
      - name: image_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Image Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/gallery/images/{image_id}/media-playback:
    get:
      tags:
      - gallery
      summary: Get Gallery Video Playback
      description: Mint a short-lived, asset- and profile-scoped URL for native video playback.
      operationId: get_gallery_video_playback_api_gallery_images__image_id__media_playback_get
      security:
      - HTTPBearer: []
      parameters:
      - name: image_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Image Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/gallery/images/{image_id}/media:
    get:
      tags:
      - gallery
      summary: Stream Gallery Video
      description: Authenticated range endpoint for canonical Gallery video assets.
      operationId: stream_gallery_video_api_gallery_images__image_id__media_get
      security:
      - HTTPBearer: []
      parameters:
      - name: image_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Image Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/gallery/images/{image_id}/campaign-asset-intelligence:
    post:
      tags:
      - gallery
      summary: Analyze Gallery Image For Campaign
      description: Score a gallery image/video as user-provided creative for a campaign idea.
      operationId: analyze_gallery_image_for_campaign_api_gallery_images__image_id__campaign_asset_intelligence_post
      security:
      - HTTPBearer: []
      parameters:
      - name: image_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Image Id
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
              title: Payload
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/gallery/create-with-ai:
    post:
      tags:
      - gallery
      summary: Create Gallery Image With Ai
      description: 'Create images using AI and add them to the gallery.

        This uses the content editing generate_image endpoint internally.'
      operationId: create_gallery_image_with_ai_api_gallery_create_with_ai_post
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_create_gallery_image_with_ai_api_gallery_create_with_ai_post'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GalleryCreateResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/gallery/upload:
    post:
      tags:
      - gallery
      summary: Upload Gallery Image
      description: Upload a new image to the gallery
      operationId: upload_gallery_image_api_gallery_upload_post
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_upload_gallery_image_api_gallery_upload_post'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GalleryImageResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/gallery/upload-bulk:
    post:
      tags:
      - gallery
      summary: Upload Gallery Images Bulk
      description: Upload multiple images to the gallery at once (up to 9 images)
      operationId: upload_gallery_images_bulk_api_gallery_upload_bulk_post
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_upload_gallery_images_bulk_api_gallery_upload_bulk_post'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GalleryUploadResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/gallery/create-with-ai/job:
    post:
      tags:
      - gallery
      summary: Create Gallery Image With Ai Job
      description: 'Start an async AI Studio generation job (agent job pattern).

        Returns job info for polling/SSE.'
      operationId: create_gallery_image_with_ai_job_api_gallery_create_with_ai_job_post
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/Body_create_gallery_image_with_ai_job_api_gallery_create_with_ai_job_post'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /api/gallery/images/bulk-delete:
    post:
      tags:
      - gallery
      summary: Bulk Delete Gallery Images
      description: Delete multiple gallery images at once
      operationId: bulk_delete_gallery_images_api_gallery_images_bulk_delete_post
      security:
      - HTTPBearer: []
      parameters:
      - name: permanent
        in: query
        required: false
        schema:
          type: boolean
          default: false
          title: Permanent
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: string
                format: uuid
              title: Image Ids
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/gallery/categories:
    get:
      tags:
      - gallery
      summary: Get Gallery Categories
      description: Get all available categories and subcategories for the company's gallery
      operationId: get_gallery_categories_api_gallery_categories_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                items:
                  additionalProperties: true
                  type: object
                type: array
                title: Response Get Gallery Categories Api Gallery Categories Get
      security:
      - HTTPBearer: []
components:
  schemas:
    Body_create_gallery_image_with_ai_job_api_gallery_create_with_ai_job_post:
      properties:
        prompt:
          type: string
          title: Prompt
        size:
          type: string
          title: Size
          default: 1024x1024
        aspect_ratio:
          anyOf:
          - type: string
          - type: 'null'
          title: Aspect Ratio
        num_images:
          type: integer
          title: Num Images
          default: 1
        use_company_style:
          type: boolean
          title: Use Company Style
          default: true
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        tags:
          anyOf:
          - type: string
          - type: 'null'
          title: Tags
        reference_gallery_ids:
          anyOf:
          - items:
              type: string
            type: array
          - type: string
          - type: 'null'
          title: Reference Gallery Ids
      type: object
      required:
      - prompt
      title: Body_create_gallery_image_with_ai_job_api_gallery_create_with_ai_job_post
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    GalleryUploadResponse:
      properties:
        success:
          type: boolean
          title: Success
        uploaded_images:
          items:
            $ref: '#/components/schemas/GalleryImageResponse'
          type: array
          title: Uploaded Images
        total:
          type: integer
          title: Total
      type: object
      required:
      - success
      - uploaded_images
      - total
      title: GalleryUploadResponse
      description: Response for gallery upload endpoints
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    Body_upload_gallery_image_api_gallery_upload_post:
      properties:
        file:
          type: string
          format: binary
          title: File
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        category:
          type: string
          title: Category
          default: uploaded
        tags:
          anyOf:
          - type: string
          - type: 'null'
          title: Tags
      type: object
      required:
      - file
      title: Body_upload_gallery_image_api_gallery_upload_post
    ExternalAdMetadata:
      properties:
        platform:
          type: string
          title: Platform
        native_type:
          type: string
          title: Native Type
        performance_tier:
          type: string
          title: Performance Tier
        performance_reason:
          type: string
          title: Performance Reason
        attribution_scope:
          type: string
          title: Attribution Scope
        currency_code:
          anyOf:
          - type: string
          - type: 'null'
          title: Currency Code
        metrics:
          additionalProperties: true
          type: object
          title: Metrics
        benchmark:
          additionalProperties: true
          type: object
          title: Benchmark
        usage_count:
          type: integer
          title: Usage Count
        current_usage_count:
          type: integer
          title: Current Usage Count
          default: 0
        historical_usage_count:
          type: integer
          title: Historical Usage Count
          default: 0
        usages:
          items:
            $ref: '#/components/schemas/ExternalAdUsageMetadata'
          type: array
          title: Usages
        analysis:
          additionalProperties: true
          type: object
          title: Analysis
      type: object
      required:
      - platform
      - native_type
      - performance_tier
      - performance_reason
      - attribution_scope
      - usage_count
      title: ExternalAdMetadata
    ExternalAdUsageMetadata:
      properties:
        observation_id:
          type: string
          title: Observation Id
        platform:
          type: string
          title: Platform
        native_type:
          type: string
          title: Native Type
        account_id:
          type: string
          title: Account Id
        campaign_id:
          type: string
          title: Campaign Id
        campaign_name:
          type: string
          title: Campaign Name
        currency_code:
          anyOf:
          - type: string
          - type: 'null'
          title: Currency Code
        ad_group_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Ad Group Id
        ad_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Ad Id
        creative_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Creative Id
        creative_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Creative Name
        status:
          anyOf:
          - type: string
          - type: 'null'
          title: Status
        inventory_state:
          type: string
          title: Inventory State
          default: current
        media_role:
          anyOf:
          - type: string
          - type: 'null'
          title: Media Role
        provider_asset_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Provider Asset Id
        source_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Source Url
        thumbnail_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Thumbnail Url
        performance_tier:
          type: string
          title: Performance Tier
        performance_reason:
          type: string
          title: Performance Reason
        attribution_scope:
          type: string
          title: Attribution Scope
        metrics:
          additionalProperties: true
          type: object
          title: Metrics
        benchmark:
          additionalProperties: true
          type: object
          title: Benchmark
        metric_window:
          additionalProperties: true
          type: object
          title: Metric Window
        analysis:
          additionalProperties: true
          type: object
          title: Analysis
      type: object
      required:
      - observation_id
      - platform
      - native_type
      - account_id
      - campaign_id
      - campaign_name
      - performance_tier
      - performance_reason
      - attribution_scope
      title: ExternalAdUsageMetadata
    GalleryListResponse:
      properties:
        images:
          items:
            $ref: '#/components/schemas/GalleryImageResponse'
          type: array
          title: Images
        total:
          type: integer
          title: Total
        page:
          type: integer
          title: Page
        limit:
          type: integer
          title: Limit
        total_pages:
          type: integer
          title: Total Pages
        category_stats:
          additionalProperties:
            additionalProperties:
              type: integer
            type: object
          type: object
          title: Category Stats
      type: object
      required:
      - images
      - total
      - page
      - limit
      - total_pages
      title: GalleryListResponse
      description: Response for gallery list endpoint
    Body_upload_gallery_images_bulk_api_gallery_upload_bulk_post:
      properties:
        files:
          items:
            type: string
            format: binary
          type: array
          title: Files
        titles:
          anyOf:
          - items:
              type: string
            type: array
          - type: string
          - type: 'null'
          title: Titles
        descriptions:
          anyOf:
          - items:
              type: string
            type: array
          - type: string
          - type: 'null'
          title: Descriptions
        category:
          type: string
          title: Category
          default: uploaded
        tags:
          anyOf:
          - type: string
          - type: 'null'
          title: Tags
      type: object
      required:
      - files
      title: Body_upload_gallery_images_bulk_api_gallery_upload_bulk_post
    Body_create_gallery_image_with_ai_api_gallery_create_with_ai_post:
      properties:
        prompt:
          type: string
          title: Prompt
        size:
          type: string
          title: Size
          default: 1024x1024
        aspect_ratio:
          anyOf:
          - type: string
          - type: 'null'
          title: Aspect Ratio
        num_images:
          type: integer
          title: Num Images
          default: 1
        use_company_style:
          type: boolean
          title: Use Company Style
          default: true
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        tags:
          anyOf:
          - type: string
          - type: 'null'
          title: Tags
        reference_gallery_ids:
          anyOf:
          - items:
              type: string
            type: array
          - type: string
          - type: 'null'
          title: Reference Gallery Ids
        reference_images:
          anyOf:
          - items:
              type: string
              format: binary
            type: array
          - type: 'null'
          title: Reference Images
      type: object
      required:
      - prompt
      title: Body_create_gallery_image_with_ai_api_gallery_create_with_ai_post
    GalleryImageResponse:
      properties:
        id:
          anyOf:
          - type: string
          - type: 'null'
          title: Id
        company_profile_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Company Profile Id
        media_url:
          type: string
          title: Media Url
        thumbnail_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Thumbnail Url
        media_type:
          type: string
          title: Media Type
        file_format:
          anyOf:
          - type: string
          - type: 'null'
          title: File Format
        category:
          type: string
          title: Category
        subcategory:
          anyOf:
          - type: string
          - type: 'null'
          title: Subcategory
        source_type:
          type: string
          title: Source Type
        source_campaign_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Source Campaign Id
        source_campaign_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Source Campaign Type
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        tags:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Tags
        width:
          anyOf:
          - type: integer
          - type: 'null'
          title: Width
        height:
          anyOf:
          - type: integer
          - type: 'null'
          title: Height
        duration:
          anyOf:
          - type: integer
          - type: 'null'
          title: Duration
        file_size:
          anyOf:
          - type: integer
          - type: 'null'
          title: File Size
        generation_prompt:
          anyOf:
          - type: string
          - type: 'null'
          title: Generation Prompt
        generation_model:
          anyOf:
          - type: string
          - type: 'null'
          title: Generation Model
        edit_history:
          anyOf:
          - items:
              additionalProperties: true
              type: object
            type: array
          - type: 'null'
          title: Edit History
        is_visible:
          type: boolean
          title: Is Visible
          default: true
        is_favorite:
          type: boolean
          title: Is Favorite
          default: false
        created_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Created At
        updated_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Updated At
        external_ad_metadata:
          anyOf:
          - $ref: '#/components/schemas/ExternalAdMetadata'
          - type: 'null'
      type: object
      required:
      - id
      - company_profile_id
      - media_url
      - media_type
      - category
      - source_type
      title: GalleryImageResponse
      description: Response schema for gallery images with signed URL support
    GalleryCreateResponse:
      properties:
        success:
          type: boolean
          title: Success
        images:
          items:
            $ref: '#/components/schemas/GalleryImageResponse'
          type: array
          title: Images
        total:
          type: integer
          title: Total
        ai_policy_eval:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Ai Policy Eval
      type: object
      required:
      - success
      - images
      - total
      title: GalleryCreateResponse
      description: Response for gallery image creation endpoints
    JobResponse:
      properties:
        job_id:
          type: string
          title: Job Id
          description: Unique job identifier
        status:
          type: string
          title: Status
          description: Initial job status (typically 'running')
        stream_url:
          type: string
          title: Stream Url
          description: SSE endpoint for real-time progress
        poll_url:
          type: string
          title: Poll Url
          description: HTTP endpoint for polling status
      type: object
      required:
      - job_id
      - status
      - stream_url
      - poll_url
      title: JobResponse
      description: Response after submitting a job
      example:
        job_id: 987fcdeb-51a2-43f7-9876-543210987654
        poll_url: /api/chat/agentic/jobs/987fcdeb-51a2-43f7-9876-543210987654
        status: running
        stream_url: /api/chat/agentic/jobs/987fcdeb-51a2-43f7-9876-543210987654/stream
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer