"/admin/auth/schemas":
    get:
        tags: [Moderation]
        operationId: getAuthSchemas
        summary: Auth schema enumerations
        description: Returns auth schema enumerations (e.g. access policies, scopes).
        responses:
            "200":
                description: |
                    Schema enumeration payload — keys are the enum names (`AccessPolicy`,
                    `BigscreenAccountStatus`, etc.); values are the legal members.
                content:
                    application/json:
                        schema:
                            type: object
                            additionalProperties:
                                type: array
                                items: { type: string }
            "401": { $ref: "../admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../admin-api.yaml#/components/responses/Forbidden" }
        x-access-policies: [Moderator, AccountsReadOnly]
        x-scopes: ["admin:all"]

"/admin/profile":
    get:
        tags: [Moderation]
        operationId: getAdminProfile
        summary: Admin profile (OAuth-aware)
        description: |
            Returns the admin profile for the account specified in query params. Also
            accepts OAuth bearers carrying the `profile` scope.
        responses:
            "200":
                description: Sanitized admin account.
                content:
                    application/json:
                        schema: { $ref: "../components/schemas/AdminAccount.yaml" }
            "401": { $ref: "../admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../admin-api.yaml#/components/responses/Forbidden" }
        x-access-policies: [Moderator, AccountsReadOnly]
        x-scopes: ["profile"]

"/admin/account/query/{field}/{value}":
    parameters:
        - in: path
          name: field
          required: true
          schema: { type: string }
          description: Account field to search (e.g. `email`, `id`, `oculusId`).
        - in: path
          name: value
          required: true
          schema: { type: string }
    get:
        tags: [Moderation]
        operationId: queryAccounts
        summary: Query accounts by field/value
        description: Returns accounts matching the supplied field/value pair.
        responses:
            "200":
                description: Matching accounts.
                content:
                    application/json:
                        schema:
                            type: array
                            items: { $ref: "../components/schemas/AdminAccount.yaml" }
            "401": { $ref: "../admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../admin-api.yaml#/components/responses/Forbidden" }
        x-access-policies: [Moderator, AccountsReadOnly]
        x-scopes: ["accounts:read", "admin:all"]

"/admin/search/{field}/{value}":
    parameters:
        - in: path
          name: field
          required: true
          schema: { type: string }
        - in: path
          name: value
          required: true
          schema: { type: string }
    get:
        tags: [Moderation]
        operationId: searchDeviceHistory
        summary: Search device history
        description: Searches device history by field/value.
        responses:
            "200":
                description: Matching accounts (a.k.a. device-history hit list).
                content:
                    application/json:
                        schema:
                            type: array
                            items: { $ref: "../components/schemas/AdminAccount.yaml" }
            "401": { $ref: "../admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../admin-api.yaml#/components/responses/Forbidden" }
        x-access-policies: [Moderator, AccountsReadOnly]
        x-scopes: ["accounts:read", "admin:all"]

"/admin/account/{bigscreenAccountId}":
    parameters:
        - in: path
          name: bigscreenAccountId
          required: true
          schema: { type: string }
    get:
        tags: [Moderation]
        operationId: getAccountForAdmin
        summary: Detailed admin view of an account
        description: Returns the full admin view of a single account.
        responses:
            "200":
                description: Sanitized admin account.
                content:
                    application/json:
                        schema: { $ref: "../components/schemas/AdminAccount.yaml" }
            "401": { $ref: "../admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../admin-api.yaml#/components/responses/Forbidden" }
            "404":
                description: Account not found.
                content:
                    application/json:
                        schema: { $ref: "../admin-api.yaml#/components/schemas/Error" }
        x-access-policies: [Moderator, AccountsReadOnly]
        x-scopes: ["accounts:read", "admin:all"]

"/admin/account/{bigscreenAccountId}/ban":
    parameters:
        - in: path
          name: bigscreenAccountId
          required: true
          schema: { type: string }
    put:
        tags: [Moderation]
        operationId: banAccount
        summary: Ban an account
        description: Bans an account. Cannot ban yourself or accounts with higher privileges.
        requestBody:
            required: true
            content:
                application/json:
                    schema:
                        type: object
                        required: [message]
                        properties:
                            message:
                                type: string
                                description: Ban reason.
        responses:
            "200":
                description: Account banned.
            "401": { $ref: "../admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../admin-api.yaml#/components/responses/Forbidden" }
            "404":
                description: Account not found.
                content:
                    application/json:
                        schema: { $ref: "../admin-api.yaml#/components/schemas/Error" }
        x-access-policies: [Moderator]
        x-scopes: ["accounts:write", "admin:all"]

"/admin/account/{bigscreenAccountId}/unban":
    parameters:
        - in: path
          name: bigscreenAccountId
          required: true
          schema: { type: string }
    put:
        tags: [Moderation]
        operationId: unbanAccount
        summary: Unban an account
        responses:
            "200":
                description: Account unbanned.
            "401": { $ref: "../admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../admin-api.yaml#/components/responses/Forbidden" }
            "404":
                description: Account not found.
                content:
                    application/json:
                        schema: { $ref: "../admin-api.yaml#/components/schemas/Error" }
        x-access-policies: [Moderator]
        x-scopes: ["accounts:write", "admin:all"]

"/admin/account/{bigscreenAccountId}/disable":
    parameters:
        - in: path
          name: bigscreenAccountId
          required: true
          schema: { type: string }
    put:
        tags: [Moderation]
        operationId: disableAccount
        summary: Disable an account
        responses:
            "200":
                description: Account disabled.
            "401": { $ref: "../admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../admin-api.yaml#/components/responses/Forbidden" }
            "404":
                description: Account not found.
                content:
                    application/json:
                        schema: { $ref: "../admin-api.yaml#/components/schemas/Error" }
        x-access-policies: [Moderator]
        x-scopes: ["accounts:write", "admin:all"]

"/admin/account/{bigscreenAccountId}/note":
    parameters:
        - in: path
          name: bigscreenAccountId
          required: true
          schema: { type: string }
    post:
        tags: [Moderation]
        operationId: createAdminNote
        summary: Create an admin note on an account
        requestBody:
            required: true
            content:
                application/json:
                    schema:
                        type: object
                        required: [text]
                        properties:
                            text: { type: string, description: Note body. }
                            isPinned: { type: boolean, default: false }
        responses:
            "200":
                description: Note created.
            "401": { $ref: "../admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../admin-api.yaml#/components/responses/Forbidden" }
        x-access-policies: [Moderator]
        x-scopes: ["accounts:write", "admin:all"]

"/admin/account/{bigscreenAccountId}/email_update_ticket":
    parameters:
        - in: path
          name: bigscreenAccountId
          required: true
          schema: { type: string }
    get:
        tags: [Moderation]
        operationId: getEmailUpdateTicket
        summary: Email update ticket
        description: Returns an email update ticket the account holder can use to confirm an email change.
        responses:
            "200":
                description: Ticket payload.
                content:
                    application/json:
                        schema: { $ref: "../components/schemas/EmailUpdateTicket.yaml" }
            "401": { $ref: "../admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../admin-api.yaml#/components/responses/Forbidden" }
        x-access-policies: [Moderator]
        x-scopes: ["accounts:read", "admin:all"]

"/admin/account/{bigscreenAccountId}/token":
    parameters:
        - in: path
          name: bigscreenAccountId
          required: true
          schema: { type: string }
    get:
        tags: [Moderation]
        operationId: createLoginToken
        summary: Create a login token (v1)
        description: Creates a single-use login token that an admin can hand to the account holder.
        responses:
            "200":
                description: Token payload.
                content:
                    application/json:
                        schema: { $ref: "../components/schemas/LoginToken.yaml" }
            "401": { $ref: "../admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../admin-api.yaml#/components/responses/Forbidden" }
        x-access-policies: [Moderator]
        x-scopes: ["accounts:read", "admin:all"]

"/admin/account/{bigscreenAccountId}/token2":
    parameters:
        - in: path
          name: bigscreenAccountId
          required: true
          schema: { type: string }
    get:
        tags: [Moderation]
        operationId: createLoginTokenV2
        summary: Create a login token (v2)
        description: Newer-style login token; prefer this over v1 for new integrations.
        responses:
            "200":
                description: Token payload.
                content:
                    application/json:
                        schema: { $ref: "../components/schemas/LoginToken2.yaml" }
            "401": { $ref: "../admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../admin-api.yaml#/components/responses/Forbidden" }
        x-access-policies: [Moderator]
        x-scopes: ["accounts:read", "admin:all"]

"/admin/account/{bigscreenAccountId}/device_history":
    parameters:
        - in: path
          name: bigscreenAccountId
          required: true
          schema: { type: string }
    get:
        tags: [Moderation]
        operationId: getAccountDeviceHistory
        summary: Device history for an account
        responses:
            "200":
                description: Device-history payload.
                content:
                    application/json:
                        schema:
                            type: object
                            properties:
                                bigscreenAccountId: { type: string }
                                devices:
                                    type: array
                                    items: { $ref: "../components/schemas/DeviceStatus.yaml" }
                                ips:
                                    type: array
                                    items: { $ref: "../components/schemas/IPStatus.yaml" }
            "401": { $ref: "../admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../admin-api.yaml#/components/responses/Forbidden" }
        x-access-policies: [Moderator]
        x-scopes: ["accounts:read", "admin:all"]

"/admin/device/{deviceUniqueIdentifier}":
    parameters:
        - in: path
          name: deviceUniqueIdentifier
          required: true
          schema: { type: string }
    get:
        tags: [Moderation]
        operationId: getDeviceStatus
        summary: Device status
        responses:
            "200":
                description: Device status record.
                content:
                    application/json:
                        schema: { $ref: "../components/schemas/DeviceStatus.yaml" }
            "401": { $ref: "../admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../admin-api.yaml#/components/responses/Forbidden" }
        x-access-policies: [Moderator]
        x-scopes: ["accounts:read", "admin:all"]
    put:
        tags: [Moderation]
        operationId: updateDeviceStatus
        summary: Update device status
        requestBody:
            required: true
            content:
                application/json:
                    schema:
                        type: object
                        properties:
                            status:
                                type: string
                                description: New status value (must match `AuthSchemas.AccessStatusCodes`).
                            notes: { type: string }
        responses:
            "200":
                description: Status updated.
            "401": { $ref: "../admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../admin-api.yaml#/components/responses/Forbidden" }
        x-access-policies: [Moderator]
        x-scopes: ["accounts:write", "admin:all"]

"/admin/ip/{ip}":
    parameters:
        - in: path
          name: ip
          required: true
          schema: { type: string }
    get:
        tags: [Moderation]
        operationId: getIPStatus
        summary: IP address status
        responses:
            "200":
                description: IP status record.
                content:
                    application/json:
                        schema: { $ref: "../components/schemas/IPStatus.yaml" }
            "401": { $ref: "../admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../admin-api.yaml#/components/responses/Forbidden" }
        x-access-policies: [Moderator]
        x-scopes: ["accounts:read", "admin:all"]
    put:
        tags: [Moderation]
        operationId: updateIPStatus
        summary: Update IP status
        requestBody:
            required: true
            content:
                application/json:
                    schema:
                        type: object
                        properties:
                            status:
                                type: string
                                description: New status value (must match `AuthSchemas.AccessStatusCodes`).
                            notes: { type: string }
        responses:
            "200":
                description: Status updated.
            "401": { $ref: "../admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../admin-api.yaml#/components/responses/Forbidden" }
        x-access-policies: [Moderator]
        x-scopes: ["accounts:read", "admin:all"]

"/admin/account/{bigscreenAccountId}/reports":
    parameters:
        - in: path
          name: bigscreenAccountId
          required: true
          schema: { type: string }
    get:
        tags: [Moderation]
        operationId: getReports
        summary: Reports for an account
        description: Returns user-submitted reports involving the supplied account, broken down by direction.
        responses:
            "200":
                description: Reports payload.
                content:
                    application/json:
                        schema:
                            type: object
                            required: [reportsAgainst, reportsBy, roomReportsAgainst]
                            properties:
                                reportsAgainst:
                                    type: array
                                    items: { $ref: "../components/schemas/AccountReport.yaml" }
                                    description: Account reports filed against this account.
                                reportsBy:
                                    type: array
                                    items: { $ref: "../components/schemas/AccountReport.yaml" }
                                    description: Account reports this account filed.
                                roomReportsAgainst:
                                    type: array
                                    items: { $ref: "../components/schemas/RoomReport.yaml" }
                                    description: Room reports against rooms this account created.
            "401": { $ref: "../admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../admin-api.yaml#/components/responses/Forbidden" }
        x-access-policies: [Moderator]
        x-scopes: ["accounts:read", "admin:all"]

"/admin/account_reports":
    get:
        tags: [Moderation]
        operationId: getAllAccountReports
        summary: All account reports
        responses:
            "200":
                description: Array of account reports.
                content:
                    application/json:
                        schema:
                            type: array
                            items: { $ref: "../components/schemas/AccountReport.yaml" }
            "401": { $ref: "../admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../admin-api.yaml#/components/responses/Forbidden" }
        x-access-policies: [Moderator]
        x-scopes: ["reports:read", "admin:all"]

"/admin/room_reports":
    get:
        tags: [Moderation]
        operationId: getAllRoomReports
        summary: All room reports
        responses:
            "200":
                description: Array of room reports.
                content:
                    application/json:
                        schema:
                            type: array
                            items: { $ref: "../components/schemas/RoomReport.yaml" }
            "401": { $ref: "../admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../admin-api.yaml#/components/responses/Forbidden" }
        x-access-policies: [Moderator]
        x-scopes: ["reports:read", "admin:all"]

"/admin/account_report/{accountReportId}":
    parameters:
        - in: path
          name: accountReportId
          required: true
          schema: { type: string }
    get:
        tags: [Moderation]
        operationId: getAccountReport
        summary: Fetch one account report
        responses:
            "200":
                description: Account report.
                content:
                    application/json:
                        schema: { $ref: "../components/schemas/AccountReport.yaml" }
            "401": { $ref: "../admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../admin-api.yaml#/components/responses/Forbidden" }
            "404":
                description: Report not found.
                content:
                    application/json:
                        schema: { $ref: "../admin-api.yaml#/components/schemas/Error" }
        x-access-policies: [Moderator]
        x-scopes: ["reports:read", "admin:all"]

"/admin/room_report/{roomReportId}":
    parameters:
        - in: path
          name: roomReportId
          required: true
          schema: { type: string }
    get:
        tags: [Moderation]
        operationId: getRoomReport
        summary: Fetch one room report
        responses:
            "200":
                description: Room report.
                content:
                    application/json:
                        schema: { $ref: "../components/schemas/RoomReport.yaml" }
            "401": { $ref: "../admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../admin-api.yaml#/components/responses/Forbidden" }
            "404":
                description: Report not found.
                content:
                    application/json:
                        schema: { $ref: "../admin-api.yaml#/components/schemas/Error" }
        x-access-policies: [Moderator]
        x-scopes: ["reports:read", "admin:all"]

"/admin/account/{bigscreenAccountId}/history":
    parameters:
        - in: path
          name: bigscreenAccountId
          required: true
          schema: { type: string }
    get:
        tags: [Moderation]
        operationId: getLoginHistory
        summary: Login history for an account
        responses:
            "200":
                description: Login history.
                content:
                    application/json:
                        schema:
                            type: object
                            properties:
                                bigscreenAccountId: { type: string }
                                logins:
                                    type: array
                                    items:
                                        type: object
                                        properties:
                                            timestamp: { type: string, format: date-time }
                                            ip: { type: string }
                                            deviceUniqueIdentifier: { type: string }
                                            userAgent: { type: string }
                                            authMethod:
                                                type: string
                                                description: "e.g. `email-password`, `oculus`, `steam`."
                                            success: { type: boolean }
                                        additionalProperties: true
            "401": { $ref: "../admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../admin-api.yaml#/components/responses/Forbidden" }
        x-access-policies: [Moderator]
        x-scopes: ["accounts:read", "admin:all"]

"/admin/account/{bigscreenAccountId}/event/{event}":
    parameters:
        - in: path
          name: bigscreenAccountId
          required: true
          schema: { type: string }
        - in: path
          name: event
          required: true
          schema: { type: string }
    get:
        tags: [Moderation]
        operationId: getAnalyticsEvent
        summary: Analytics event data for an account
        description: Returns analytics event data for the specified account/event combo.
        responses:
            "200":
                description: Event data.
                content:
                    application/json:
                        schema:
                            type: object
                            properties:
                                bigscreenAccountId: { type: string }
                                event: { type: string }
                                events:
                                    type: array
                                    items:
                                        type: object
                                        properties:
                                            timestamp: { type: string, format: date-time }
                                            metaData:
                                                type: object
                                                additionalProperties: true
                                        additionalProperties: true
                                count: { type: integer }
            "401": { $ref: "../admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../admin-api.yaml#/components/responses/Forbidden" }
        x-access-policies: [Moderator]
        x-scopes: ["accounts:read", "admin:all"]

"/admin/account/{bigscreenAccountId}/stats":
    parameters:
        - in: path
          name: bigscreenAccountId
          required: true
          schema: { type: string }
    get:
        tags: [Moderation]
        operationId: getAccountStats
        summary: Account statistics
        responses:
            "200":
                description: Stats payload.
                content:
                    application/json:
                        schema:
                            type: object
                            properties:
                                bigscreenAccountId: { type: string }
                                totalLogins: { type: integer }
                                totalSessions: { type: integer }
                                totalRoomsCreated: { type: integer }
                                totalReportsAgainst: { type: integer }
                                totalReportsBy: { type: integer }
                                totalEntitlements: { type: integer }
                                firstSeenAt: { type: string, format: date-time }
                                lastSeenAt: { type: string, format: date-time }
            "401": { $ref: "../admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../admin-api.yaml#/components/responses/Forbidden" }
        x-access-policies: [Moderator, AccountsReadOnly]
        x-scopes: ["accounts:read", "admin:all"]

"/admin/account/{bigscreenAccountId}/logs":
    parameters:
        - in: path
          name: bigscreenAccountId
          required: true
          schema: { type: string }
    get:
        tags: [Moderation]
        operationId: getAccountLogs
        summary: Log database entries for an account
        responses:
            "200":
                description: Log entries.
                content:
                    application/json:
                        schema:
                            type: object
                            properties:
                                bigscreenAccountId: { type: string }
                                logs:
                                    type: array
                                    items:
                                        type: object
                                        properties:
                                            id: { type: string }
                                            timestamp: { type: string, format: date-time }
                                            level:
                                                type: string
                                                description: "e.g. `info`, `warn`, `error`."
                                            logType: { type: string }
                                            message: { type: string }
                                            details:
                                                type: object
                                                additionalProperties: true
                                count: { type: integer }
            "401": { $ref: "../admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../admin-api.yaml#/components/responses/Forbidden" }
        x-access-policies: [Moderator]
        x-scopes: ["accounts:read", "admin:all"]

"/admin/logs/{logType}":
    parameters:
        - in: path
          name: logType
          required: true
          schema: { type: string }
          description: |
              Log type to filter on. The trailing segment is optional in the underlying route
              (`/admin/logs{/:logType}`) — when omitted, all log types are returned.
    get:
        tags: [Moderation]
        operationId: getLogDatabaseQuery
        summary: Log database entries
        description: Returns log database entries, optionally filtered by log type.
        responses:
            "200":
                description: Log entries.
                content:
                    application/json:
                        schema:
                            type: object
                            properties:
                                logs:
                                    type: array
                                    items:
                                        type: object
                                        properties:
                                            id: { type: string }
                                            timestamp: { type: string, format: date-time }
                                            level: { type: string }
                                            logType: { type: string }
                                            bigscreenAccountId: { type: string }
                                            message: { type: string }
                                            details:
                                                type: object
                                                additionalProperties: true
                                count: { type: integer }
            "401": { $ref: "../admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../admin-api.yaml#/components/responses/Forbidden" }
        x-access-policies: [Admin]
        x-scopes: ["admin:all"]

"/admin/alert":
    post:
        tags: [Moderation]
        operationId: sendAlert
        summary: Send a Discord alert
        description: Posts a message to a Discord alert channel.
        requestBody:
            required: true
            content:
                application/json:
                    schema:
                        type: object
                        required: [source, message]
                        properties:
                            source: { type: string }
                            message: { type: string }
        responses:
            "200":
                description: Alert sent.
            "401": { $ref: "../admin-api.yaml#/components/responses/Unauthorized" }
            "403": { $ref: "../admin-api.yaml#/components/responses/Forbidden" }
        x-access-policies: [Moderator]
        x-scopes: ["admin:all"]
