Bulk URL Checker Internal API

openapi: 3.2.0
info:
  title: Reception Desk Internal API
  description: API Gateway for URL Checker Engine
  version: 1.0.0
tags:
- name: Internal
paths:
  /internal/clerk-webhook:
    post:
      summary: Clerk Webhook Proxy
      description: 'Proxy Clerk webhook to billing-service.


        Clerk sends user.created and user.updated events here.

        This endpoint forwards the webhook to billing-service for processing.'
      operationId: clerk_webhook_proxy_internal_clerk_webhook_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      tags:
      - Internal
  /internal/sitemap-preview:
    post:
      summary: Internal Sitemap Preview
      description: 'Read-only: how many pages does this site publish?


        THE SAME discovery the job uses. The public pre-signup scan calls this so

        the number quoted on the button is the number the job will deliver.


        They used to be different code. On 2026-09-04 a customer was shown

        "1,110 pages found" (one locale''s sitemap, duplicates included) and given a

        284-URL job (a different locale). The true figure is 959 unique. A quote and

        a delivery produced by two implementations will always drift, and the

        customer meets the drift as a broken promise.


        Creates nothing, charges nothing, needs no account.'
      operationId: internal_sitemap_preview_internal_sitemap_preview_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/_SitemapPreviewBody'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Internal
  /internal/operator-notify:
    post:
      summary: Operator Notify
      description: 'Fire a Pushover to the operator (Carlos).


        Rate-limited to 10 notifications per rolling UTC hour to prevent a

        runaway cron loop or hostile actor with the token from flooding

        the phone. Enforcement is best-effort — Redis blip → allow.


        priority 0 = normal, 1 = high (bypasses quiet hours), 2 = emergency

        (Pushover retries every 60s for 1h until acknowledged).


        Optional `url` + `url_title` render as a tappable action on the

        phone notification (Pushover convention).'
      operationId: operator_notify_internal_operator_notify_post
      parameters:
      - name: x-operator-notify-token
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Operator-Notify-Token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OperatorNotifyBody'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Internal
  /internal/ai-mode-snapshot:
    get:
      summary: Ai Mode Snapshot
      description: 'Return AI Mode activity + delta since a timestamp.


        Called by the launch-monitoring cron agent. Everything needed to

        decide "is anything worth reporting?" in one round-trip: the

        baseline cohort snapshot + a delta window of new signups, new

        sessions (with tool summaries), new paid events, and any loop

        failures. Deliberately does NOT include full user emails — the

        agent sees only the domain part for privacy.


        Read-only. No side effects.


        Default `since` = 1h ago (matches the hourly cron cadence). Pass

        ISO 8601 UTC to override.'
      operationId: ai_mode_snapshot_internal_ai_mode_snapshot_get
      parameters:
      - name: since
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Since
      - name: x-operator-notify-token
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Operator-Notify-Token
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Internal
components:
  schemas:
    OperatorNotifyBody:
      properties:
        title:
          type: string
          title: Title
        message:
          type: string
          title: Message
        priority:
          type: integer
          title: Priority
          default: 0
        url:
          anyOf:
          - type: string
          - type: 'null'
          title: Url
        url_title:
          anyOf:
          - type: string
          - type: 'null'
          title: Url Title
      type: object
      required:
      - title
      - message
      title: OperatorNotifyBody
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    _SitemapPreviewBody:
      properties:
        domain:
          type: string
          maxLength: 255
          title: Domain
        max_urls:
          anyOf:
          - type: integer
            minimum: 1.0
          - type: 'null'
          title: Max Urls
        choice:
          anyOf:
          - type: string
          - type: 'null'
          title: Choice
        include_urls:
          type: boolean
          title: Include Urls
          default: false
      type: object
      required:
      - domain
      title: _SitemapPreviewBody
    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