openapi: 3.0.3
info:
    title: Customer Enterprise API
    version: "1.0.0"
    description: >
        APIs for Enterprise customers to fetch their screens, playlists, reports, and channels.
        Authentication is via `X-API-KEY` header. Rate limits apply.
    tags:
        -   name: Whitelabel
            description: All endpoints related to your whitelabel account and its clients.
        -   name: Profile
            description: Endpoints related to your user profile and admin management.
        -   name: Billing
            description: Endpoints related to your billing info and addresses.
        -   name: Screens
            description: Access your screens and status.
        -   name: Playlists
            description: Manage and fetch playlists.
        -   name: Reports
            description: API endpoints for reporting.
        -   name: Channels
            description: API endpoints for managing channels.
        -   name: Images
            description: List or manage images/videos.
servers:
    - url: /api/customer
security:
    - ApiKeyAuth: []

components:
    securitySchemes:
        ApiKeyAuth:
            type: apiKey
            in: header
            name: X-API-KEY

    parameters:
        Limit:
            name: limit
            in: query
            description: Records per page
            required: false
            schema: { type: integer, default: 20 }
        Page:
            name: page
            in: query
            description: Page number
            required: false
            schema: { type: integer, default: 1 }
        DateFrom:
            name: date_from
            in: query
            description: Start date (YYYY-MM-DD). Defaults to 7 days ago if not provided.
            required: false
            schema:
                type: string
                format: date
        DateTo:
            name: date_to
            in: query
            description: End date (YYYY-MM-DD). Defaults to today if not provided.
            required: false
            schema:
                type: string
                format: date

    responses:
        Unauthorized:
            description: Unauthorized - invalid or missing API key, or plan is not Enterprise.
            content:
                application/json:
                    schema:
                        $ref: '#/components/schemas/Error'
        TooManyRequests:
            description: Rate limit exceeded.
            content:
                application/json:
                    schema:
                        $ref: '#/components/schemas/Error'

    schemas:
        Error:
            type: object
            properties:
                message: { type: string }

        Screen:
            type: object
            properties:
                name: { type: string }
                code: { type: string }
                active: { type: boolean }
                created_at: { type: string, format: date-time }
                rotation: { type: integer }
                last_active: { type: string, format: date-time }
                tags: { type: array, items: { type: string } }
                app_name: { type: string }
                app_version: { type: string }
                animation: { type: string }
                music: { type: boolean }
                random: { type: boolean }
                device_info:
                    type: object
                    properties:
                        brand: { type: string }
                        model: { type: string }
                playlists:
                    type: array
                    items:
                        $ref: '#/components/schemas/PlaylistSimple'
                    nullable: true
                channel:
                    type: object
                    nullable: true
                    properties:
                        name: { type: string }
                        orientation: { type: string }
                        layout: { type: string }

        PlaylistSimple:
            type: object
            properties:
                name: { type: string }

        ScreenSimple:
            type: object
            properties:
                name: { type: string }

        Playlist:
            type: object
            properties:
                name: { type: string }
                description: { type: string }
                count: { type: integer }
                date_from: { type: string, format: date }
                date_to: { type: string, format: date }
                time_from: { type: string }
                time_to: { type: string }
                days: { type: string }
                schedule_status: { type: string }
                default: { type: boolean }
                images:
                    type: array
                    items:
                        type: object
                        properties:
                            full_path: { type: string }
                            duration: { type: integer }
                            position: { type: integer }
                            url:
                                type: object
                                nullable: true
                                properties:
                                    name: { type: string }
                                    url: { type: string }
                                    refresh: { type: string }
                                    news: { type: string }
                                    region: { type: string }
                                    weather: { type: string }
                screens:
                    type: array
                    items:
                        $ref: '#/components/schemas/ScreenSimple'

        Report:
            type: object
            properties:
                playlist: { type: string }
                screen: { type: string }
                total_impressions: { type: integer }

        ImageSimple:
            type: object
            properties:
                name: { type: string }
                full_path: { type: string }
                thumbnail: { type: string }

        Channel:
            type: object
            properties:
                name: { type: string }
                orientation: { type: string }
                layout: { type: string }
                screens:
                    type: array
                    items:
                        $ref: '#/components/schemas/ScreenSimple'
                playlists:
                    type: array
                    items:
                        $ref: '#/components/schemas/PlaylistSimple'
                created_at: { type: string, format: date-time }

        Image:
            type: object
            properties:
                title: { type: string }
                type: { type: string, example: "image" }
                link: { type: string }
                thumbnail: { type: string }
                size_bytes: { type: integer }
                size_in_kb: { type: number }
                duration: { type: integer, nullable: true }
                uploaded_at: { type: string, format: date-time }
                is_ai: { type: boolean }
                prompt: { type: string, nullable: true }

        Whitelabel:
            type: object
            properties:
                name: { type: string }
                url: { type: string }
                logo: { type: string }
                primary_colour: { type: string }
                secondary_colour: { type: string }
                tertiary_colour: { type: string }
                cancel_colour: { type: string }
                setup_link: { type: string }
                custom_app: { type: boolean }
                register: { type: boolean }
                number_of_customers: { type: integer }
                created_at: { type: string, format: date-time }

        WhitelabelClient:
            type: object
            properties:
                name: { type: string }
                email: { type: string }
                phone: { type: string }
                active: { type: boolean }
                max_screens: { type: integer }
                notes: { type: string }
                created_at: { type: string, format: date-time }
                last_login: { type: string, format: date-time }

        Profile:
            type: object
            properties:
                name: { type: string }
                email: { type: string }
                company: { type: string }
                phone: { type: string }
                timezone: { type: string }
                created_at: { type: string, format: date-time }
                last_login: { type: string, format: date-time }

        ProfileAdmin:
            type: object
            properties:
                name: { type: string }
                email: { type: string }
                active: { type: boolean }
                created_at: { type: string, format: date-time }

        BillingInfo:
            type: object
            properties:
                plan_name: { type: string }
                pro_services:
                    type: object
                    properties:
                        reports: { type: boolean }
                        monitoring: { type: boolean }
                        large_upload: { type: boolean }
                        watermark_removed: { type: boolean }
                        music: { type: boolean }
                        high_quality: { type: boolean }
                        downtime: { type: boolean }

        BillingAddress:
            type: object
            properties:
                name: { type: string }
                last_name: { type: string }
                mobile: { type: string }
                address_line1: { type: string }
                address_line2: { type: string }
                city: { type: string }
                postcode: { type: string }
                country: { type: string }
                tax_id: { type: string }
                default: { type: boolean }
                created_at: { type: string, format: date-time }

paths:
    /screens:
        get:
            tags: [Screens]
            summary: Get all screens for the current customer
            security: [ { ApiKeyAuth: [] } ]
            parameters:
                - $ref: '#/components/parameters/Limit'
                - $ref: '#/components/parameters/Page'
            responses:
                '200':
                    description: List of screens
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    data:
                                        type: array
                                        items: { $ref: '#/components/schemas/Screen' }
                                    meta:
                                        type: object
                '401': { $ref: '#/components/responses/Unauthorized' }
                '429': { $ref: '#/components/responses/TooManyRequests' }

    /playlists:
        get:
            tags: [Playlists]
            summary: Get all playlists for the current customer
            security: [ { ApiKeyAuth: [] } ]
            parameters:
                - $ref: '#/components/parameters/Limit'
                - $ref: '#/components/parameters/Page'
            responses:
                '200':
                    description: List of playlists
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    data:
                                        type: array
                                        items: { $ref: '#/components/schemas/Playlist' }
                                    meta:
                                        type: object
                '401': { $ref: '#/components/responses/Unauthorized' }
                '429': { $ref: '#/components/responses/TooManyRequests' }

    /reports:
        get:
            tags: [Reports]
            summary: Get all reports for the current customer
            security: [ { ApiKeyAuth: [] } ]
            parameters:
                - $ref: '#/components/parameters/Limit'
                - $ref: '#/components/parameters/Page'
                - $ref: '#/components/parameters/DateFrom'
                - $ref: '#/components/parameters/DateTo'
            responses:
                '200':
                    description: List of reports
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    data:
                                        type: array
                                        items: { $ref: '#/components/schemas/Report' }
                                    meta:
                                        type: object
                '401': { $ref: '#/components/responses/Unauthorized' }
                '429': { $ref: '#/components/responses/TooManyRequests' }

    /channels:
        get:
            tags: [Channels]
            summary: Get all channels for the current customer
            security: [ { ApiKeyAuth: [] } ]
            parameters:
                - $ref: '#/components/parameters/Limit'
                - $ref: '#/components/parameters/Page'
            responses:
                '200':
                    description: List of channels
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    data:
                                        type: array
                                        items: { $ref: '#/components/schemas/Channel' }
                                    meta:
                                        type: object
                '401': { $ref: '#/components/responses/Unauthorized' }
                '429': { $ref: '#/components/responses/TooManyRequests' }
    /whitelabel:
        get:
            tags: [Whitelabel]
            summary: Get whitelabel info
            security: [ { ApiKeyAuth: [ ] } ]
            parameters:
                -   $ref: '#/components/parameters/Limit'
                -   $ref: '#/components/parameters/Page'
            responses:
                '200':
                    description: Whitelabel info
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Whitelabel'

    /clients:
        get:
            tags: [Whitelabel]
            summary: List whitelabel clients (sub-users)
            security: [ { ApiKeyAuth: [ ] } ]
            parameters:
                -   $ref: '#/components/parameters/Limit'
                -   $ref: '#/components/parameters/Page'
            responses:
                '200':
                    description: List of whitelabel clients
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    data:
                                        type: array
                                        items:
                                            $ref: '#/components/schemas/WhitelabelClient'
                                    meta:
                                        type: object

    /images:
        get:
            tags: [Images]
            summary: List all images and videos for user
            security: [ { ApiKeyAuth: [ ] } ]
            parameters:
                -   $ref: '#/components/parameters/Limit'
                -   $ref: '#/components/parameters/Page'
            responses:
                '200':
                    description: List of images/videos
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    data:
                                        type: array
                                        items: { $ref: '#/components/schemas/Image' }
                                    meta:
                                        type: object

    /profile:
        get:
            tags: [Profile]
            summary: Get current user profile
            security: [ { ApiKeyAuth: [ ] } ]
            parameters:
                -   $ref: '#/components/parameters/Limit'
                -   $ref: '#/components/parameters/Page'
            responses:
                '200':
                    description: User profile info
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Profile'

    /admins:
        get:
            tags: [Profile]
            summary: List profile admins and their status
            security: [ { ApiKeyAuth: [ ] } ]
            parameters:
                -   $ref: '#/components/parameters/Limit'
                -   $ref: '#/components/parameters/Page'
            responses:
                '200':
                    description: List of profile admins
                    content:
                        application/json:
                            schema:
                                type: object
                                properties:
                                    data:
                                        type: array
                                        items: { $ref: '#/components/schemas/ProfileAdmin' }
                                    meta:
                                        type: object

    /billing-info:
        get:
            tags: [Billing]
            summary: Get current billing info and pro services
            security: [ { ApiKeyAuth: [ ] } ]
            parameters:
                -   $ref: '#/components/parameters/Limit'
                -   $ref: '#/components/parameters/Page'
            responses:
                '200':
                    description: Billing info
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/BillingInfo'

    /billing-addresses:
        get:
            tags: [Billing]
            summary: Get the user's billing address
            security: [ { ApiKeyAuth: [ ] } ]
            parameters:
                -   $ref: '#/components/parameters/Limit'
                -   $ref: '#/components/parameters/Page'
            responses:
                '200':
                    description: Billing address info
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/BillingAddress'
