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 Artists'
    description: "\nAPIs for TV applications to display artist profiles.\nAll endpoints require the `X-API-Key` header and a valid TV access token\nobtained from the TV pairing flow (`Authorization: Bearer <tv_access_token>`)."
  -
    name: 'TV Artworks'
    description: "\nAPIs for TV applications to display artworks with QR codes.\nAll endpoints require the `X-API-Key` header and a valid TV access token\nobtained from the TV pairing flow (`Authorization: Bearer <tv_access_token>`)."
  -
    name: 'TV Authentication'
    description: "\nEndpoints for pairing a TV device with a mobile user account.\nQR and poll endpoints require only the `X-API-Key` header. The pair endpoint\nrequires an authenticated user bearer token from the mobile/Flutter app."
  -
    name: 'TV Me'
    description: "\nEndpoints for the authenticated TV device to retrieve information about the\ncurrently paired user. Requires a valid TV access token returned by the pairing flow."
  -
    name: 'TV Subscriptions'
    description: "\nEndpoints for the authenticated TV device to browse membership plans and\nsubscribe via native in-app purchase platforms. All endpoints require a valid\nTV access token returned by the pairing flow."
components:
  securitySchemes:
    default:
      type: apiKey
      name: X-API-Key
      in: header
      description: 'TV endpoints require an API key via the X-API-Key header. Endpoints marked "requires authentication" also need an Authorization: Bearer header with the TV access token returned by poll() (or the mobile user bearer token for pair()).'
security:
  -
    default: []
paths:
  /api/v1/tv/artists:
    get:
      summary: 'List Artists'
      operationId: listArtists
      description: "Get a paginated list of artists for TV display. Returns basic profile info\nsuitable for artist listing screens."
      parameters:
        -
          in: query
          name: page
          description: 'Page number for pagination. Default: 1.'
          example: 1
          required: false
          schema:
            type: integer
            description: 'Page number for pagination. Default: 1.'
            example: 1
        -
          in: query
          name: per_page
          description: 'Number of items per page. Min: 1, Max: 50. Default: 20.'
          example: 20
          required: false
          schema:
            type: integer
            description: 'Number of items per page. Min: 1, Max: 50. Default: 20.'
            example: 20
        -
          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: 5
                      name: 'John Doe'
                      profile_image: 'https://example.com/artists/5/photo.jpg'
                      specialty: 'Oil Painting'
                      permanent_location: 'Rajkot, Gujarat, India'
                  meta:
                    current_page: 1
                    last_page: 3
                    per_page: 20
                    total: 55
                properties:
                  data:
                    type: array
                    example:
                      -
                        id: 5
                        name: 'John Doe'
                        profile_image: 'https://example.com/artists/5/photo.jpg'
                        specialty: 'Oil Painting'
                        permanent_location: 'Rajkot, Gujarat, India'
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          example: 5
                        name:
                          type: string
                          example: 'John Doe'
                        profile_image:
                          type: string
                          example: 'https://example.com/artists/5/photo.jpg'
                        specialty:
                          type: string
                          example: 'Oil Painting'
                        permanent_location:
                          type: string
                          example: 'Rajkot, Gujarat, India'
                  meta:
                    type: object
                    properties:
                      current_page:
                        type: integer
                        example: 1
                      last_page:
                        type: integer
                        example: 3
                      per_page:
                        type: integer
                        example: 20
                      total:
                        type: integer
                        example: 55
      tags:
        - 'TV Artists'
  '/api/v1/tv/artists/{id}':
    get:
      summary: 'Get Artist'
      operationId: getArtist
      description: "Get a single artist by ID for TV display. Includes full profile details,\nbio, permanent location, social links, and career sections (education,\nexhibitions, galleries, residencies, institutions)."
      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: 5
                    name: 'John Doe'
                    profile_image: 'https://example.com/artists/5/photo.jpg'
                    bio: 'Contemporary artist based in Rajkot.'
                    specialty: 'Oil Painting'
                    years_of_experience: 10
                    permanent_location: 'Rajkot, Gujarat, India'
                    social_links:
                      instagram: 'https://instagram.com/johndoe'
                      facebook: null
                      website: 'https://johndoe.art'
                      twitter: null
                    education:
                      -
                        name: 'Fine Arts Academy'
                        date: '2010'
                        location: 'Mumbai, India'
                    exhibitions:
                      -
                        name: 'Modern Art Expo'
                        date: '2022'
                        location: 'Delhi, India'
                    galleries:
                      -
                        name: 'City Gallery'
                        date: '2021'
                        location: 'Ahmedabad, India'
                    residencies:
                      -
                        name: 'Artist Residency Program'
                        date: '2019'
                        location: 'Jaipur, India'
                    institutions:
                      -
                        name: 'National Institute of Art'
                        date: '2018'
                        location: 'Baroda, India'
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 5
                      name:
                        type: string
                        example: 'John Doe'
                      profile_image:
                        type: string
                        example: 'https://example.com/artists/5/photo.jpg'
                      bio:
                        type: string
                        example: 'Contemporary artist based in Rajkot.'
                      specialty:
                        type: string
                        example: 'Oil Painting'
                      years_of_experience:
                        type: integer
                        example: 10
                      permanent_location:
                        type: string
                        example: 'Rajkot, Gujarat, India'
                      social_links:
                        type: object
                        properties:
                          instagram:
                            type: string
                            example: 'https://instagram.com/johndoe'
                          facebook:
                            type: string
                            example: null
                            nullable: true
                          website:
                            type: string
                            example: 'https://johndoe.art'
                          twitter:
                            type: string
                            example: null
                            nullable: true
                      education:
                        type: array
                        example:
                          -
                            name: 'Fine Arts Academy'
                            date: '2010'
                            location: 'Mumbai, India'
                        items:
                          type: object
                          properties:
                            name:
                              type: string
                              example: 'Fine Arts Academy'
                            date:
                              type: string
                              example: '2010'
                            location:
                              type: string
                              example: 'Mumbai, India'
                      exhibitions:
                        type: array
                        example:
                          -
                            name: 'Modern Art Expo'
                            date: '2022'
                            location: 'Delhi, India'
                        items:
                          type: object
                          properties:
                            name:
                              type: string
                              example: 'Modern Art Expo'
                            date:
                              type: string
                              example: '2022'
                            location:
                              type: string
                              example: 'Delhi, India'
                      galleries:
                        type: array
                        example:
                          -
                            name: 'City Gallery'
                            date: '2021'
                            location: 'Ahmedabad, India'
                        items:
                          type: object
                          properties:
                            name:
                              type: string
                              example: 'City Gallery'
                            date:
                              type: string
                              example: '2021'
                            location:
                              type: string
                              example: 'Ahmedabad, India'
                      residencies:
                        type: array
                        example:
                          -
                            name: 'Artist Residency Program'
                            date: '2019'
                            location: 'Jaipur, India'
                        items:
                          type: object
                          properties:
                            name:
                              type: string
                              example: 'Artist Residency Program'
                            date:
                              type: string
                              example: '2019'
                            location:
                              type: string
                              example: 'Jaipur, India'
                      institutions:
                        type: array
                        example:
                          -
                            name: 'National Institute of Art'
                            date: '2018'
                            location: 'Baroda, India'
                        items:
                          type: object
                          properties:
                            name:
                              type: string
                              example: 'National Institute of Art'
                            date:
                              type: string
                              example: '2018'
                            location:
                              type: string
                              example: 'Baroda, India'
        404:
          description: 'Not Found'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'No query results for model [App\Models\User] 999'
                properties:
                  message:
                    type: string
                    example: 'No query results for model [App\Models\User] 999'
      tags:
        - 'TV Artists'
    parameters:
      -
        in: path
        name: id
        description: 'The artist user ID.'
        example: 5
        required: true
        schema:
          type: integer
  '/api/v1/tv/artists/{id}/subscribe':
    post:
      summary: 'Subscribe to an artist'
      operationId: subscribeToAnArtist
      description: "Subscribe the authenticated TV user to an artist. Allows the user to filter\nartworks by subscribed artists."
      parameters:
        -
          in: header
          name: X-API-Key
          description: ''
          example: '{YOUR_API_KEY}'
          schema:
            type: string
      responses:
        201:
          description: Success
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Subscribed successfully'
                  artist_id: 5
                  is_subscribed: true
                properties:
                  message:
                    type: string
                    example: 'Subscribed successfully'
                  artist_id:
                    type: integer
                    example: 5
                  is_subscribed:
                    type: boolean
                    example: true
        422:
          description: 'Already Subscribed'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Already subscribed to this artist'
                properties:
                  message:
                    type: string
                    example: 'Already subscribed to this artist'
      tags:
        - 'TV Artists'
    delete:
      summary: 'Unsubscribe from an artist'
      operationId: unsubscribeFromAnArtist
      description: 'Unsubscribe the authenticated TV user from an artist.'
      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:
                  message: 'Unsubscribed successfully'
                  artist_id: 5
                  is_subscribed: false
                properties:
                  message:
                    type: string
                    example: 'Unsubscribed successfully'
                  artist_id:
                    type: integer
                    example: 5
                  is_subscribed:
                    type: boolean
                    example: false
        422:
          description: 'Not Subscribed'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Not subscribed to this artist'
                properties:
                  message:
                    type: string
                    example: 'Not subscribed to this artist'
      tags:
        - 'TV Artists'
    parameters:
      -
        in: path
        name: id
        description: 'The artist user ID.'
        example: 5
        required: true
        schema:
          type: integer
  /api/v1/tv/me/artist-subscriptions:
    get:
      summary: "Get user's subscribed artists"
      operationId: getUsersSubscribedArtists
      description: 'Get a paginated list of artists the authenticated TV user is subscribed to.'
      parameters:
        -
          in: query
          name: page
          description: 'Page number for pagination. Default: 1.'
          example: 1
          required: false
          schema:
            type: integer
            description: 'Page number for pagination. Default: 1.'
            example: 1
        -
          in: query
          name: per_page
          description: 'Number of items per page. Min: 1, Max: 50. Default: 20.'
          example: 20
          required: false
          schema:
            type: integer
            description: 'Number of items per page. Min: 1, Max: 50. Default: 20.'
            example: 20
        -
          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: 5
                      name: 'John Doe'
                      profile_image: 'https://example.com/artists/5/photo.jpg'
                      specialty: 'Oil Painting'
                      permanent_location: 'Rajkot, Gujarat, India'
                      is_subscribed: true
                  meta:
                    current_page: 1
                    last_page: 1
                    per_page: 20
                    total: 3
                properties:
                  data:
                    type: array
                    example:
                      -
                        id: 5
                        name: 'John Doe'
                        profile_image: 'https://example.com/artists/5/photo.jpg'
                        specialty: 'Oil Painting'
                        permanent_location: 'Rajkot, Gujarat, India'
                        is_subscribed: true
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          example: 5
                        name:
                          type: string
                          example: 'John Doe'
                        profile_image:
                          type: string
                          example: 'https://example.com/artists/5/photo.jpg'
                        specialty:
                          type: string
                          example: 'Oil Painting'
                        permanent_location:
                          type: string
                          example: 'Rajkot, Gujarat, India'
                        is_subscribed:
                          type: boolean
                          example: true
                  meta:
                    type: object
                    properties:
                      current_page:
                        type: integer
                        example: 1
                      last_page:
                        type: integer
                        example: 1
                      per_page:
                        type: integer
                        example: 20
                      total:
                        type: integer
                        example: 3
      tags:
        - 'TV Artists'
  /api/v1/tv/me/category-preferences:
    get:
      summary: "Get user's category preferences"
      operationId: getUsersCategoryPreferences
      description: "Get the authenticated TV user's selected category preferences. Returns the list\nof categories the user has selected for filtering artworks."
      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:
                    categories:
                      -
                        id: 1
                        name: Painting
                        slug: painting
                        description: 'Oil and acrylic paintings'
                      -
                        id: 2
                        name: Photography
                        slug: photography
                        description: 'Digital and film photography'
                    category_ids:
                      - 1
                      - 2
                properties:
                  data:
                    type: object
                    properties:
                      categories:
                        type: array
                        example:
                          -
                            id: 1
                            name: Painting
                            slug: painting
                            description: 'Oil and acrylic paintings'
                          -
                            id: 2
                            name: Photography
                            slug: photography
                            description: 'Digital and film photography'
                        items:
                          type: object
                          properties:
                            id:
                              type: integer
                              example: 1
                            name:
                              type: string
                              example: Painting
                            slug:
                              type: string
                              example: painting
                            description:
                              type: string
                              example: 'Oil and acrylic paintings'
                      category_ids:
                        type: array
                        example:
                          - 1
                          - 2
                        items:
                          type: integer
      tags:
        - 'TV Artists'
    put:
      summary: "Update user's category preferences"
      operationId: updateUsersCategoryPreferences
      description: "Update the authenticated TV user's category preferences. The user can select\nwhich categories they want to see artworks from. At least one category must be selected."
      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:
                    categories:
                      -
                        id: 1
                        name: Painting
                        slug: painting
                        description: 'Oil and acrylic paintings'
                    category_ids:
                      - 1
                  message: 'Preferences updated successfully'
                properties:
                  data:
                    type: object
                    properties:
                      categories:
                        type: array
                        example:
                          -
                            id: 1
                            name: Painting
                            slug: painting
                            description: 'Oil and acrylic paintings'
                        items:
                          type: object
                          properties:
                            id:
                              type: integer
                              example: 1
                            name:
                              type: string
                              example: Painting
                            slug:
                              type: string
                              example: painting
                            description:
                              type: string
                              example: 'Oil and acrylic paintings'
                      category_ids:
                        type: array
                        example:
                          - 1
                        items:
                          type: integer
                  message:
                    type: string
                    example: 'Preferences updated successfully'
        422:
          description: 'Validation Error'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'The given data was invalid.'
                  errors:
                    category_ids:
                      - 'The category_ids field is required.'
                properties:
                  message:
                    type: string
                    example: 'The given data was invalid.'
                  errors:
                    type: object
                    properties:
                      category_ids:
                        type: array
                        example:
                          - 'The category_ids field is required.'
                        items:
                          type: string
      tags:
        - 'TV Artists'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                category_ids:
                  type: array
                  description: 'Array of category IDs to select.'
                  example:
                    - 1
                    - 2
                    - 3
                  items:
                    type: string
              required:
                - category_ids
  /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: page
          description: 'Page number for pagination. Default: 1.'
          example: 1
          required: false
          schema:
            type: integer
            description: 'Page number for pagination. Default: 1.'
            example: 1
        -
          in: query
          name: per_page
          description: 'Number of items per page. Min: 1, Max: 50. Default: 20.'
          example: 20
          required: false
          schema:
            type: integer
            description: 'Number of items per page. Min: 1, Max: 50. Default: 20.'
            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. Default: new.'
          example: new
          required: false
          schema:
            type: string
            description: 'Sort order: new, popular, price_asc, price_desc. Default: new.'
            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:
                        -
                          image_url: 'https://example.com/artworks/1/image.jpg'
                      qr_code:
                        url: 'https://stage.1kosmosfactory.com/web/artist/artwork-detail?id=1'
                        base64: 'data:image/svg+xml;base64,PHN2ZyB...'
                  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:
                          -
                            image_url: 'https://example.com/artworks/1/image.jpg'
                        qr_code:
                          url: 'https://stage.1kosmosfactory.com/web/artist/artwork-detail?id=1'
                          base64: 'data:image/svg+xml;base64,PHN2ZyB...'
                    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:
                            -
                              image_url: 'https://example.com/artworks/1/image.jpg'
                          items:
                            type: object
                            properties:
                              image_url:
                                type: string
                                example: 'https://example.com/artworks/1/image.jpg'
                        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/svg+xml;base64,PHN2ZyB...'
                  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,\ncategory, and 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'
                    views_count: 15
                    images:
                      -
                        id: 456
                        image_url: 'https://example.com/artworks/1/image.jpg'
                    artist:
                      id: 5
                      first_name: John
                      last_name: Doe
                      full_name: 'John Doe'
                      profile_image: 'https://example.com/artist.jpg'
                      bio: 'Contemporary artist specializing in abstract paintings'
                    category:
                      id: 3
                      name: Painting
                      slug: painting
                      description: 'Oil and acrylic paintings'
                    owner:
                      id: 6
                      first_name: Jane
                      last_name: Smith
                      full_name: 'Jane Smith'
                      profile_image: 'https://example.com/collector.jpg'
                    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'
                      views_count:
                        type: integer
                        example: 15
                      images:
                        type: array
                        example:
                          -
                            id: 456
                            image_url: 'https://example.com/artworks/1/image.jpg'
                        items:
                          type: object
                          properties:
                            id:
                              type: integer
                              example: 456
                            image_url:
                              type: string
                              example: 'https://example.com/artworks/1/image.jpg'
                      artist:
                        type: object
                        properties:
                          id:
                            type: integer
                            example: 5
                          first_name:
                            type: string
                            example: John
                          last_name:
                            type: string
                            example: Doe
                          full_name:
                            type: string
                            example: 'John Doe'
                          profile_image:
                            type: string
                            example: 'https://example.com/artist.jpg'
                          bio:
                            type: string
                            example: 'Contemporary artist specializing in abstract paintings'
                      category:
                        type: object
                        properties:
                          id:
                            type: integer
                            example: 3
                          name:
                            type: string
                            example: Painting
                          slug:
                            type: string
                            example: painting
                          description:
                            type: string
                            example: 'Oil and acrylic paintings'
                      owner:
                        type: object
                        properties:
                          id:
                            type: integer
                            example: 6
                          first_name:
                            type: string
                            example: Jane
                          last_name:
                            type: string
                            example: Smith
                          full_name:
                            type: string
                            example: 'Jane Smith'
                          profile_image:
                            type: string
                            example: 'https://example.com/collector.jpg'
                      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
  /api/v1/tv/pair:
    post:
      summary: 'Pair TV From Mobile App'
      operationId: pairTVFromMobileApp
      description: "Called by the authenticated mobile/Flutter app after scanning the TV QR code.\nLinks the pairing session to the authenticated user.\n\nNote: This endpoint requires the mobile user's bearer token (regular Sanctum auth),\nNOT the TV access token, and does NOT require an X-API-Key."
      parameters: []
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'TV paired successfully.'
                  session_code: ABCDEF12
                properties:
                  message:
                    type: string
                    example: 'TV paired successfully.'
                  session_code:
                    type: string
                    example: ABCDEF12
        404:
          description: 'Invalid or Expired'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Invalid or expired session code.'
                properties:
                  message:
                    type: string
                    example: 'Invalid or expired session code.'
      tags:
        - 'TV Authentication'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                session_code:
                  type: string
                  description: 'The pairing session code from the scanned QR code.'
                  example: ABCDEF12
              required:
                - session_code
      security: []
  /api/v1/tv/auth/qr:
    get:
      summary: 'Generate QR Session'
      operationId: generateQRSession
      description: "Creates a new TV pairing session and returns a QR code URL.\nThe TV application should display the QR code and begin polling\n`POST /api/v1/tv/auth/poll` until the user scans and pairs."
      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:
                  session_code: ABCDEF12
                  qr_url: 'onekosmosfactory://tv-pair?code=ABCDEF12'
                  expires_at: '2026-06-26T21:00:00+00:00'
                properties:
                  session_code:
                    type: string
                    example: ABCDEF12
                  qr_url:
                    type: string
                    example: 'onekosmosfactory://tv-pair?code=ABCDEF12'
                  expires_at:
                    type: string
                    example: '2026-06-26T21:00:00+00:00'
      tags:
        - 'TV Authentication'
      security: []
  /api/v1/tv/auth/poll:
    post:
      summary: 'Poll Pairing Status'
      operationId: pollPairingStatus
      description: "Polls the status of a TV pairing session. Returns 202 while waiting,\n200 once paired with the TV access token, 404 if the session is not found,\nand 410 if the session expired."
      parameters:
        -
          in: header
          name: X-API-Key
          description: ''
          example: '{YOUR_API_KEY}'
          schema:
            type: string
      responses:
        200:
          description: Paired
          content:
            application/json:
              schema:
                type: object
                example:
                  access_token: 1|tv_access_token...
                  user:
                    id: 5
                    full_name: 'John Doe'
                    email: john@example.com
                  subscription:
                    has_tv_access: true
                    plan_name: Basic
                    billing_interval: yearly
                    ends_at: '2027-06-26T21:00:00+00:00'
                    artwork_limit: 25
                properties:
                  access_token:
                    type: string
                    example: 1|tv_access_token...
                  user:
                    type: object
                    properties:
                      id:
                        type: integer
                        example: 5
                      full_name:
                        type: string
                        example: 'John Doe'
                      email:
                        type: string
                        example: john@example.com
                  subscription:
                    type: object
                    properties:
                      has_tv_access:
                        type: boolean
                        example: true
                      plan_name:
                        type: string
                        example: Basic
                      billing_interval:
                        type: string
                        example: yearly
                      ends_at:
                        type: string
                        example: '2027-06-26T21:00:00+00:00'
                      artwork_limit:
                        type: integer
                        example: 25
        202:
          description: Waiting
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Waiting for pairing.'
                properties:
                  message:
                    type: string
                    example: 'Waiting for pairing.'
        404:
          description: 'Not Found'
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Session not found.'
                properties:
                  message:
                    type: string
                    example: 'Session not found.'
        410:
          description: Expired
          content:
            application/json:
              schema:
                type: object
                example:
                  message: 'Session expired.'
                properties:
                  message:
                    type: string
                    example: 'Session expired.'
      tags:
        - 'TV Authentication'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                session_code:
                  type: string
                  description: 'The pairing session code shown in the QR code.'
                  example: ABCDEF12
              required:
                - session_code
      security: []
  /api/v1/tv/me/subscription:
    get:
      summary: 'Get TV Subscription'
      operationId: getTVSubscription
      description: "Returns the paired user's subscription status for TV access checks.\nDoes not require an active TV subscription plan, but the paired session must be valid."
      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:
                    has_tv_access: true
                    plan_name: Basic
                    billing_interval: yearly
                    ends_at: '2027-06-26T21:00:00+00:00'
                    artwork_limit: 25
                properties:
                  data:
                    type: object
                    properties:
                      has_tv_access:
                        type: boolean
                        example: true
                      plan_name:
                        type: string
                        example: Basic
                      billing_interval:
                        type: string
                        example: yearly
                      ends_at:
                        type: string
                        example: '2027-06-26T21:00:00+00:00'
                      artwork_limit:
                        type: integer
                        example: 25
        401:
          description: Unauthenticated
          content:
            application/json:
              schema:
                type: object
                example:
                  message: Unauthenticated.
                properties:
                  message:
                    type: string
                    example: Unauthenticated.
      tags:
        - 'TV Me'
  /api/v1/tv/plans:
    get:
      summary: 'List available subscription plans'
      operationId: listAvailableSubscriptionPlans
      description: "Returns active plans with web prices and platform-specific product IDs\n(Apple/Google/Amazon) that the TV app must use when calling the native\nin-app purchase SDK."
      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
                      slug: basic
                      name: Basic
                      monthly_price:
                        currency: USD
                        price: '9.99'
                      yearly_price:
                        currency: USD
                        price: '99.99'
                      all_prices:
                        USD:
                          monthly: '9.99'
                          yearly: '99.99'
                      platform_products:
                        -
                          id: 1
                          platform: apple
                          billing_interval: monthly
                          product_id: com.1kosmosfactory.basic.monthly
                          is_active: true
                      is_current: false
                  currency: USD
                properties:
                  data:
                    type: array
                    example:
                      -
                        id: 1
                        slug: basic
                        name: Basic
                        monthly_price:
                          currency: USD
                          price: '9.99'
                        yearly_price:
                          currency: USD
                          price: '99.99'
                        all_prices:
                          USD:
                            monthly: '9.99'
                            yearly: '99.99'
                        platform_products:
                          -
                            id: 1
                            platform: apple
                            billing_interval: monthly
                            product_id: com.1kosmosfactory.basic.monthly
                            is_active: true
                        is_current: false
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          example: 1
                        slug:
                          type: string
                          example: basic
                        name:
                          type: string
                          example: Basic
                        monthly_price:
                          type: object
                          properties:
                            currency:
                              type: string
                              example: USD
                            price:
                              type: string
                              example: '9.99'
                        yearly_price:
                          type: object
                          properties:
                            currency:
                              type: string
                              example: USD
                            price:
                              type: string
                              example: '99.99'
                        all_prices:
                          type: object
                          properties:
                            USD:
                              type: object
                              properties:
                                monthly:
                                  type: string
                                  example: '9.99'
                                yearly:
                                  type: string
                                  example: '99.99'
                        platform_products:
                          type: array
                          example:
                            -
                              id: 1
                              platform: apple
                              billing_interval: monthly
                              product_id: com.1kosmosfactory.basic.monthly
                              is_active: true
                          items:
                            type: object
                            properties:
                              id:
                                type: integer
                                example: 1
                              platform:
                                type: string
                                example: apple
                              billing_interval:
                                type: string
                                example: monthly
                              product_id:
                                type: string
                                example: com.1kosmosfactory.basic.monthly
                              is_active:
                                type: boolean
                                example: true
                        is_current:
                          type: boolean
                          example: false
                  currency:
                    type: string
                    example: USD
      tags:
        - 'TV Subscriptions'
  /api/v1/tv/subscriptions/verify-apple:
    post:
      summary: 'Verify an Apple In-App Purchase subscription'
      operationId: verifyAnAppleInAppPurchaseSubscription
      description: "The TV app sends the signed transaction info (JWS) after a successful StoreKit 2 purchase.\nThe backend decodes and verifies the JWS, looks up the matching plan from the configured\nplatform products, and activates the subscription."
      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:
                  message: 'Subscription verified and activated.'
                  data:
                    has_tv_access: true
                    plan_name: Basic
                    billing_interval: monthly
                    ends_at: '2026-08-15T12:00:00+00:00'
                    artwork_limit: 0
                properties:
                  message:
                    type: string
                    example: 'Subscription verified and activated.'
                  data:
                    type: object
                    properties:
                      has_tv_access:
                        type: boolean
                        example: true
                      plan_name:
                        type: string
                        example: Basic
                      billing_interval:
                        type: string
                        example: monthly
                      ends_at:
                        type: string
                        example: '2026-08-15T12:00:00+00:00'
                      artwork_limit:
                        type: integer
                        example: 0
      tags:
        - 'TV Subscriptions'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                signedTransactionInfo:
                  type: string
                  description: 'The signed JWS transaction info from StoreKit 2.'
                  example: eyJhbGciOiJFUzI1NiIs...
              required:
                - signedTransactionInfo
  /api/v1/tv/subscriptions/current:
    get:
      summary: 'Get the current TV subscription'
      operationId: getTheCurrentTVSubscription
      description: ''
      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:
                    has_tv_access: true
                    plan_name: Basic
                    billing_interval: monthly
                    ends_at: '2026-08-15T12:00:00+00:00'
                    artwork_limit: 0
                properties:
                  data:
                    type: object
                    properties:
                      has_tv_access:
                        type: boolean
                        example: true
                      plan_name:
                        type: string
                        example: Basic
                      billing_interval:
                        type: string
                        example: monthly
                      ends_at:
                        type: string
                        example: '2026-08-15T12:00:00+00:00'
                      artwork_limit:
                        type: integer
                        example: 0
      tags:
        - 'TV Subscriptions'
  /api/v1/tv/subscriptions/history:
    get:
      summary: 'List TV subscription history'
      operationId: listTVSubscriptionHistory
      description: 'Returns paginated subscription history for the authenticated TV user.'
      parameters:
        -
          in: query
          name: per_page
          description: 'optional Number of records per page (1-50). Default: 20.'
          example: 20
          required: false
          schema:
            type: integer
            description: 'optional Number of records per page (1-50). Default: 20.'
            example: 20
        -
          in: header
          name: X-API-Key
          description: ''
          example: '{YOUR_API_KEY}'
          schema:
            type: string
      responses:
        200:
          description: Success
          content:
            text/plain:
              schema:
                type: string
                example: "{\n  \"data\": [...],\n  \"meta\": {\n    \"current_page\": 1,\n    \"last_page\": 1,\n    \"per_page\": 20,\n    \"total\": 1\n  }\n}"
      tags:
        - 'TV Subscriptions'