openapi: 3.0.3
info:
  title: '1Kosmos Factory TV API Documentation'
  description: 'API for TV applications (Apple TV, Android TV) to display artworks.'
  version: 1.0.0
servers:
  -
    url: 'https://stage.1kosmosfactory.com'
tags:
  -
    name: 'TV Artworks'
    description: "\nAPIs for TV applications to display artworks with QR codes."
components:
  securitySchemes:
    default:
      type: apiKey
      name: X-API-Key
      in: header
      description: 'Contact the administrator to get your API key for TV applications.'
security:
  -
    default: []
paths:
  /api/v1/tv/artworks:
    get:
      summary: 'List Artworks'
      operationId: listArtworks
      description: "Get a paginated list of artworks for TV display. Each artwork includes images and a QR code\nthat links to the artwork detail page in the mobile/web application."
      parameters:
        -
          in: query
          name: per_page
          description: 'Number of items per page. Min: 1, Max: 50.'
          example: 20
          required: false
          schema:
            type: integer
            description: 'Number of items per page. Min: 1, Max: 50.'
            example: 20
        -
          in: query
          name: category_id
          description: 'Filter by category ID.'
          example: 1
          required: false
          schema:
            type: integer
            description: 'Filter by category ID.'
            example: 1
        -
          in: query
          name: featured
          description: 'Show only featured artworks.'
          example: true
          required: false
          schema:
            type: boolean
            description: 'Show only featured artworks.'
            example: true
        -
          in: query
          name: sort
          description: 'Sort order: new, popular, price_asc, price_desc.'
          example: new
          required: false
          schema:
            type: string
            description: 'Sort order: new, popular, price_asc, price_desc.'
            example: new
        -
          in: header
          name: X-API-Key
          description: ''
          example: '{YOUR_API_KEY}'
          schema:
            type: string
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    -
                      id: 1
                      title: 'Sunset Canvas'
                      description: 'A beautiful sunset painting'
                      artist_name: 'John Doe'
                      images:
                        -
                          thumbnail: 'https://example.com/thumb.jpg'
                          medium: 'https://example.com/medium.jpg'
                          large: 'https://example.com/large.jpg'
                          original: 'https://example.com/original.jpg'
                      category: Paintings
                      price:
                        amount: 1500.0
                        currency: USD
                        formatted: '$1,500.00'
                      dimensions:
                        width: 24
                        height: 36
                        depth: 2
                        unit: inches
                      qr_code:
                        url: 'https://stage.1kosmosfactory.com/web/artist/artwork-detail?id=1'
                        base64: 'data:image/png;base64,iVBORw0KGgo...'
                  meta:
                    current_page: 1
                    last_page: 5
                    per_page: 20
                    total: 100
                properties:
                  data:
                    type: array
                    example:
                      -
                        id: 1
                        title: 'Sunset Canvas'
                        description: 'A beautiful sunset painting'
                        artist_name: 'John Doe'
                        images:
                          -
                            thumbnail: 'https://example.com/thumb.jpg'
                            medium: 'https://example.com/medium.jpg'
                            large: 'https://example.com/large.jpg'
                            original: 'https://example.com/original.jpg'
                        category: Paintings
                        price:
                          amount: 1500
                          currency: USD
                          formatted: '$1,500.00'
                        dimensions:
                          width: 24
                          height: 36
                          depth: 2
                          unit: inches
                        qr_code:
                          url: 'https://stage.1kosmosfactory.com/web/artist/artwork-detail?id=1'
                          base64: 'data:image/png;base64,iVBORw0KGgo...'
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          example: 1
                        title:
                          type: string
                          example: 'Sunset Canvas'
                        description:
                          type: string
                          example: 'A beautiful sunset painting'
                        artist_name:
                          type: string
                          example: 'John Doe'
                        images:
                          type: array
                          example:
                            -
                              thumbnail: 'https://example.com/thumb.jpg'
                              medium: 'https://example.com/medium.jpg'
                              large: 'https://example.com/large.jpg'
                              original: 'https://example.com/original.jpg'
                          items:
                            type: object
                            properties:
                              thumbnail:
                                type: string
                                example: 'https://example.com/thumb.jpg'
                              medium:
                                type: string
                                example: 'https://example.com/medium.jpg'
                              large:
                                type: string
                                example: 'https://example.com/large.jpg'
                              original:
                                type: string
                                example: 'https://example.com/original.jpg'
                        category:
                          type: string
                          example: Paintings
                        price:
                          type: object
                          properties:
                            amount:
                              type: number
                              example: 1500.0
                            currency:
                              type: string
                              example: USD
                            formatted:
                              type: string
                              example: '$1,500.00'
                        dimensions:
                          type: object
                          properties:
                            width:
                              type: integer
                              example: 24
                            height:
                              type: integer
                              example: 36
                            depth:
                              type: integer
                              example: 2
                            unit:
                              type: string
                              example: inches
                        qr_code:
                          type: object
                          properties:
                            url:
                              type: string
                              example: 'https://stage.1kosmosfactory.com/web/artist/artwork-detail?id=1'
                            base64:
                              type: string
                              example: 'data:image/png;base64,iVBORw0KGgo...'
                  meta:
                    type: object
                    properties:
                      current_page:
                        type: integer
                        example: 1
                      last_page:
                        type: integer
                        example: 5
                      per_page:
                        type: integer
                        example: 20
                      total:
                        type: integer
                        example: 100
      tags:
        - 'TV Artworks'
  '/api/v1/tv/artworks/{id}':
    get:
      summary: 'Get Artwork'
      operationId: getArtwork
      description: "Get a single artwork by ID for TV display. Includes full details, images, artist info,\nand a QR code that links to the artwork detail page."
      parameters:
        -
          in: header
          name: X-API-Key
          description: ''
          example: '{YOUR_API_KEY}'
          schema:
            type: string
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    id: 1
                    title: 'Sunset Canvas'
                    description: 'A beautiful sunset painting with vibrant colors'
                    artist_name: 'John Doe'
                    artist:
                      id: 5
                      name: 'John Doe'
                      bio: 'Contemporary artist based in New York'
                      profile_image: 'https://example.com/artist.jpg'
                    images:
                      -
                        thumbnail: 'https://example.com/thumb.jpg'
                        medium: 'https://example.com/medium.jpg'
                        large: 'https://example.com/large.jpg'
                        original: 'https://example.com/original.jpg'
                    category: Paintings
                    price:
                      amount: 1500.0
                      currency: USD
                      formatted: '$1,500.00'
                    dimensions:
                      width: 24
                      height: 36
                      depth: 2
                      unit: inches
                    qr_code:
                      url: 'https://stage.1kosmosfactory.com/web/artist/artwork-detail?id=1'
                      base64: 'data:image/png;base64,iVBORw0KGgo...'
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 1
                      title:
                        type: string
                        example: 'Sunset Canvas'
                      description:
                        type: string
                        example: 'A beautiful sunset painting with vibrant colors'
                      artist_name:
                        type: string
                        example: 'John Doe'
                      artist:
                        type: object
                        properties:
                          id:
                            type: integer
                            example: 5
                          name:
                            type: string
                            example: 'John Doe'
                          bio:
                            type: string
                            example: 'Contemporary artist based in New York'
                          profile_image:
                            type: string
                            example: 'https://example.com/artist.jpg'
                      images:
                        type: array
                        example:
                          -
                            thumbnail: 'https://example.com/thumb.jpg'
                            medium: 'https://example.com/medium.jpg'
                            large: 'https://example.com/large.jpg'
                            original: 'https://example.com/original.jpg'
                        items:
                          type: object
                          properties:
                            thumbnail:
                              type: string
                              example: 'https://example.com/thumb.jpg'
                            medium:
                              type: string
                              example: 'https://example.com/medium.jpg'
                            large:
                              type: string
                              example: 'https://example.com/large.jpg'
                            original:
                              type: string
                              example: 'https://example.com/original.jpg'
                      category:
                        type: string
                        example: Paintings
                      price:
                        type: object
                        properties:
                          amount:
                            type: number
                            example: 1500.0
                          currency:
                            type: string
                            example: USD
                          formatted:
                            type: string
                            example: '$1,500.00'
                      dimensions:
                        type: object
                        properties:
                          width:
                            type: integer
                            example: 24
                          height:
                            type: integer
                            example: 36
                          depth:
                            type: integer
                            example: 2
                          unit:
                            type: string
                            example: inches
                      qr_code:
                        type: object
                        properties:
                          url:
                            type: string
                            example: 'https://stage.1kosmosfactory.com/web/artist/artwork-detail?id=1'
                          base64:
                            type: string
                            example: 'data:image/png;base64,iVBORw0KGgo...'
        404:
          description: 'Not Found'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'No query results for model [App\Models\Artwork] 999'
                properties:
                  message:
                    type: string
                    example: 'No query results for model [App\Models\Artwork] 999'
      tags:
        - 'TV Artworks'
    parameters:
      -
        in: path
        name: id
        description: 'The artwork ID.'
        example: 1
        required: true
        schema:
          type: integer