Bulk URL Checker User API

openapi: 3.2.0
info:
  title: Reception Desk User API
  description: API Gateway for URL Checker Engine
  version: 1.0.0
tags:
- name: User
paths:
  /user/preferences:
    get:
      summary: Get User Preferences
      description: 'Return the caller''s preferences dict.


        ai_mode resolution order (highest wins):

        1. stored value in user_preferences.ai_mode (explicit override)

        2. new-user default: users.created_at >= settings.ai_mode_launch_ts

        3. legacy default: False (classic dashboard)


        The default is computed at read time — we never persist a "default

        true" row. Admin PUTs still overwrite. Legacy users always see false

        because their created_at pre-dates the cutoff; new signups land in

        AI Mode without a migration.


        toggle_available stays admin-only: new users don''t need a switch back

        to classic (they''re AI-native by definition), and legacy users keep

        the current no-toggle experience.'
      operationId: get_user_preferences_user_preferences_get
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - User
    put:
      summary: Update User Preferences
      description: 'Upsert the caller''s preferences. Any field left None is untouched.

        ai_mode is admin-gated until we open the feature — non-admin flips

        are rejected 403.'
      operationId: update_user_preferences_user_preferences_put
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserPreferencesPatch'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - User
  /user/preferences/rewards-drawer:
    put:
      summary: Set Rewards Drawer Pref
      description: 'Remember whether this customer closed the gift drawer (2026-09-18).


        Not admin-gated, unlike ai_mode: it is the customer''s own choice about

        their own screen, and it lives on the account so closing it on a laptop

        also closes it on a phone.'
      operationId: set_rewards_drawer_pref_user_preferences_rewards_drawer_put
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RewardsDrawerPref'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - User
  /user/preferences/trial-banner:
    put:
      summary: Set Trial Banner Pref
      description: 'Remember that this customer dismissed the trial banner (2026-09-19).


        Dismissed while the trial runs: hidden for good. The "ends in N days"

        version in the last 7 days shows once more; dismissing that hides it

        until the trial ends. A different trial (new period end) shows again.

        The frontend (components/shell/TrialBanner.tsx) applies the rule; this

        only stores which stage was dismissed for which trial.'
      operationId: set_trial_banner_pref_user_preferences_trial_banner_put
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TrialBannerPref'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - User
  /user/preferences/ui-state:
    put:
      summary: Set Ui State Pref
      description: 'Remember one UI choice on the account, e.g. the last tab on a screen

        (Carlos, 2026-10-04). Stored in user_preferences.ui_state (migration 102)

        so it follows the person across devices.


        Validated and capped: a signed-in user can call this, so the map must not

        become a free-form store. A new key beyond the cap is refused; an existing

        key can always be updated.'
      operationId: set_ui_state_pref_user_preferences_ui_state_put
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UiStatePref'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - User
  /user/ai-assistant/sessions:
    get:
      summary: List User Ai Sessions
      description: 'List the calling user''s AI-assistant sessions, most-recent-turn

        first. Powers the past-chats sidebar in AI Mode.'
      operationId: list_user_ai_sessions_user_ai_assistant_sessions_get
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 25
          title: Limit
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          default: 0
          title: Offset
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - User
components:
  schemas:
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    UiStatePref:
      properties:
        key:
          type: string
          title: Key
        value:
          type: string
          title: Value
      type: object
      required:
      - key
      - value
      title: UiStatePref
    RewardsDrawerPref:
      properties:
        closed:
          type: boolean
          title: Closed
      type: object
      required:
      - closed
      title: RewardsDrawerPref
    TrialBannerPref:
      properties:
        stage:
          type: string
          title: Stage
        period_end:
          type: string
          format: date-time
          title: Period End
      type: object
      required:
      - stage
      - period_end
      title: TrialBannerPref
    UserPreferencesPatch:
      properties:
        ai_mode:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Ai Mode
      type: object
      title: UserPreferencesPatch
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError