Bulk URL Checker Reviews API

openapi: 3.2.0
info:
  title: Reception Desk Reviews API
  description: API Gateway for URL Checker Engine
  version: 1.0.0
tags:
- name: Reviews
paths:
  /api/v2/reviews/prompt-shown:
    post:
      tags:
      - Reviews
      summary: Prompt Shown
      description: 'Idempotent upsert: mark that the user was shown the prompt via

        `source_trigger`. If a row already exists for this (user, trigger),

        keep the earliest `prompt_shown_at` (don''t churn the funnel timing).'
      operationId: prompt_shown_api_v2_reviews_prompt_shown_post
      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/PromptShownRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v2/reviews/prompt-clicked:
    post:
      tags:
      - Reviews
      summary: Prompt Clicked
      description: Mark the moment the user tapped through to the form.
      operationId: prompt_clicked_api_v2_reviews_prompt_clicked_post
      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/PromptClickedRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v2/reviews/mine:
    get:
      tags:
      - Reviews
      summary: My Review
      description: 'Has the current user already submitted? Used by /review to

        short-circuit re-submissions without a race.'
      operationId: my_review_api_v2_reviews_mine_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:
                $ref: '#/components/schemas/MyReviewResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v2/reviews/eligibility:
    get:
      tags:
      - Reviews
      summary: Eligibility
      description: 'Should the in-product panel render for this user right now?


        Criteria (composite AND):

        * ≥14 days since signup

        * ≥2 completed jobs (v1+v2, per v2_jobs_v1_shape)

        * ≥100 URLs cumulatively checked

        * No existing customer_reviews row in a blocking status

        (pending / approved / published / unpublished)'
      operationId: eligibility_api_v2_reviews_eligibility_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:
                $ref: '#/components/schemas/EligibilityResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v2/reviews/reward:
    get:
      tags:
      - Reviews
      summary: Review Reward
      description: What an approved review would give this account, for the intake copy.
      operationId: review_reward_api_v2_reviews_reward_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'
  /api/v2/reviews:
    post:
      tags:
      - Reviews
      summary: Submit Review
      description: 'Submit a review (intake v2, Carlos 2026-09-16).


        Every review says who wrote it: name, job title, company and the review

        itself are required, and the photo comes from the reviewer''s account.

        Anonymous reviews are no longer offered (they cost trust), so the name is

        always shown in full. The reviewer confirms the details are real.


        NOTHING is granted here: the reward (one more month of their free plan, or

        credits for subscribers) is given when the review is APPROVED

        (admin_moderate), so made-up details never earn it. Fraud flags are still

        computed now, for the moderation queue.'
      operationId: submit_review_api_v2_reviews_post
      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/SubmitReviewRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubmitReviewResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v2/reviews/published:
    get:
      tags:
      - Reviews
      summary: Published Reviews
      description: 'Public endpoint feeding marketing pages. Returns approved+published

        reviews only, plus an aggregate for the "N.N stars from M reviews"

        hero number. Never exposes user_id / email / fraud metadata.


        `offset` pages past the newest 100, so /reviews can keep every review

        reachable once there are more than one page of them.'
      operationId: published_reviews_api_v2_reviews_published_get
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          default: 20
          title: Limit
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          maximum: 1000000
          minimum: 0
          default: 0
          title: Offset
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /admin/reviews:
    get:
      tags:
      - Reviews
      summary: Admin List Reviews
      description: 'Moderation queue + list. `hide_high_fraud=true` (default) drops

        fraud_score >= 5 out of the default view but they remain queryable

        with `hide_high_fraud=false`.'
      operationId: admin_list_reviews_admin_reviews_get
      parameters:
      - name: status
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Status
      - name: trigger
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Trigger
      - name: hide_high_fraud
        in: query
        required: false
        schema:
          type: boolean
          default: true
          title: Hide High Fraud
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 200
          minimum: 1
          default: 50
          title: Limit
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          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:
                $ref: '#/components/schemas/AdminListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /admin/reviews/{review_id}:
    patch:
      tags:
      - Reviews
      summary: Admin Moderate
      description: 'State machine transitions. See migration 077 for the allowed edges:

        pending → approved | rejected

        approved → published | rejected

        published → unpublished

        unpublished → published

        Rejected is terminal (a re-ask goes through a new row).


        Intake v2 (2026-09-16, migration 093): the reward is granted HERE, when a

        review is approved, once. `grant_reward` retries it if billing was down.

        Reject before approving: a reward already given is not taken back.'
      operationId: admin_moderate_admin_reviews__review_id__patch
      parameters:
      - name: review_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Review Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ModerationRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /admin/reviews/analytics:
    get:
      tags:
      - Reviews
      summary: Admin Reviews Analytics
      description: 'Funnel + segmentation metrics. Everything drillable via

        /admin/reviews with a matching filter.'
      operationId: admin_reviews_analytics_admin_reviews_analytics_get
      parameters:
      - name: days
        in: query
        required: false
        schema:
          type: integer
          maximum: 365
          minimum: 1
          default: 30
          title: Days
      - 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'
  /api/v2/reviews/extract-role:
    post:
      tags:
      - Reviews
      summary: Extract Role
      description: 'Turn a freeform ''what do you do'' answer into a normalized

        {role_type, is_agency, industry} triple, so the /review form can

        pre-fill those fields without a dropdown-heavy intake.


        role_type is one of VALID_ROLE_TYPES (constrained by the tool

        schema, so Claude can''t invent a new value).'
      operationId: extract_role_api_v2_reviews_extract_role_post
      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/ExtractRoleRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExtractRoleResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v2/reviews/generate-drafts:
    post:
      tags:
      - Reviews
      summary: Generate Drafts
      description: 'Generate 3 short suggested review quotes grounded in the user''s

        actual usage. The user picks, edits, or ignores them — none of

        these strings hits the database unless the user submits.


        Grounding data (jobs completed, URLs checked, agency status, longest-

        running monitor) comes from v2_jobs_v1_shape + broken_link_monitors.

        The `grounded_in` field in the response mirrors what the model saw

        so we can audit later if a draft feels wrong.'
      operationId: generate_drafts_api_v2_reviews_generate_drafts_post
      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/GenerateDraftsRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerateDraftsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    PromptShownRequest:
      properties:
        source_trigger:
          type: string
          title: Source Trigger
          description: monitor_catch|dashboard_prompt|backfill_email|manual
      type: object
      required:
      - source_trigger
      title: PromptShownRequest
    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
    PublicReviewRow:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        rating:
          anyOf:
          - type: integer
          - type: 'null'
          title: Rating
        content:
          anyOf:
          - type: string
          - type: 'null'
          title: Content
        display_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Display Name
        display_title:
          anyOf:
          - type: string
          - type: 'null'
          title: Display Title
        display_company:
          anyOf:
          - type: string
          - type: 'null'
          title: Display Company
        image_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Image Url
        role_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Role Type
        written_on:
          anyOf:
          - type: string
          - type: 'null'
          title: Written On
        rewarded:
          type: boolean
          title: Rewarded
          default: false
      type: object
      required:
      - id
      - rating
      - content
      - display_name
      - display_company
      - role_type
      title: PublicReviewRow
    ExtractRoleResponse:
      properties:
        role_type:
          type: string
          title: Role Type
        is_agency:
          type: boolean
          title: Is Agency
        industry:
          anyOf:
          - type: string
          - type: 'null'
          title: Industry
      type: object
      required:
      - role_type
      - is_agency
      title: ExtractRoleResponse
    AdminListResponse:
      properties:
        reviews:
          items:
            $ref: '#/components/schemas/AdminReviewRow'
          type: array
          title: Reviews
        total:
          type: integer
          title: Total
        limit:
          type: integer
          title: Limit
        offset:
          type: integer
          title: Offset
        hidden_by_fraud:
          type: integer
          title: Hidden By Fraud
          default: 0
      type: object
      required:
      - reviews
      - total
      - limit
      - offset
      title: AdminListResponse
    GenerateDraftsRequest:
      properties:
        role_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Role Type
        industry:
          anyOf:
          - type: string
          - type: 'null'
          title: Industry
        user_context:
          anyOf:
          - type: string
            maxLength: 500
          - type: 'null'
          title: User Context
          description: Freeform 'what did you use it for' — optional
        rating:
          anyOf:
          - type: integer
            maximum: 5.0
            minimum: 1.0
          - type: 'null'
          title: Rating
          description: Star rating — biases quote tone (5 = celebrate; ≤3 = honest/critical)
      type: object
      title: GenerateDraftsRequest
    ExtractRoleRequest:
      properties:
        text:
          type: string
          maxLength: 2000
          minLength: 2
          title: Text
          description: Freeform 'what do you do?' answer from the user
      type: object
      required:
      - text
      title: ExtractRoleRequest
    MyReviewResponse:
      properties:
        exists:
          type: boolean
          title: Exists
        id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Id
        status:
          anyOf:
          - type: string
          - type: 'null'
          title: Status
        submitted_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Submitted At
      type: object
      required:
      - exists
      title: MyReviewResponse
    AdminReviewRow:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        user_id:
          type: string
          title: User Id
        user_email:
          anyOf:
          - type: string
          - type: 'null'
          title: User Email
        user_plan:
          anyOf:
          - type: string
          - type: 'null'
          title: User Plan
        lifetime_jobs:
          type: integer
          title: Lifetime Jobs
          default: 0
        lifetime_urls:
          type: integer
          title: Lifetime Urls
          default: 0
        source_trigger:
          type: string
          title: Source Trigger
        prompt_shown_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Prompt Shown At
        submitted_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Submitted At
        rating:
          anyOf:
          - type: integer
          - type: 'null'
          title: Rating
        content:
          anyOf:
          - type: string
          - type: 'null'
          title: Content
        role_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Role Type
        is_agency:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Is Agency
        display_name_choice:
          anyOf:
          - type: string
          - type: 'null'
          title: Display Name Choice
        display_company:
          anyOf:
          - type: string
          - type: 'null'
          title: Display Company
        display_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Display Name
        display_title:
          anyOf:
          - type: string
          - type: 'null'
          title: Display Title
        display_image_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Display Image Url
        details_confirmed_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Details Confirmed At
        reward:
          anyOf:
          - type: string
          - type: 'null'
          title: Reward
        reward_granted_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Reward Granted At
        status:
          type: string
          title: Status
        fraud_flags:
          items: {}
          type: array
          title: Fraud Flags
          default: []
        fraud_score:
          type: integer
          title: Fraud Score
          default: 0
        credits_awarded:
          type: integer
          title: Credits Awarded
          default: 0
        moderated_by:
          anyOf:
          - type: string
          - type: 'null'
          title: Moderated By
        moderated_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Moderated At
        rejection_reason:
          anyOf:
          - type: string
          - type: 'null'
          title: Rejection Reason
        published_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Published At
      type: object
      required:
      - id
      - user_id
      - source_trigger
      - status
      title: AdminReviewRow
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    GenerateDraftsResponse:
      properties:
        drafts:
          items:
            type: string
          type: array
          title: Drafts
        grounded_in:
          type: object
          title: Grounded In
      type: object
      required:
      - drafts
      - grounded_in
      title: GenerateDraftsResponse
    PublicListResponse:
      properties:
        reviews:
          items:
            $ref: '#/components/schemas/PublicReviewRow'
          type: array
          title: Reviews
        aggregate:
          type: object
          title: Aggregate
        all_rewarded:
          type: boolean
          title: All Rewarded
          default: false
        disclosure:
          anyOf:
          - type: string
          - type: 'null'
          title: Disclosure
      type: object
      required:
      - reviews
      - aggregate
      title: PublicListResponse
    SubmitReviewResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        credits_awarded:
          type: integer
          title: Credits Awarded
        new_balance:
          anyOf:
          - type: integer
          - type: 'null'
          title: New Balance
        message:
          type: string
          title: Message
      type: object
      required:
      - id
      - credits_awarded
      - message
      title: SubmitReviewResponse
    SubmitReviewRequest:
      properties:
        rating:
          type: integer
          maximum: 5.0
          minimum: 1.0
          title: Rating
        content:
          anyOf:
          - type: string
            maxLength: 1000
          - type: 'null'
          title: Content
          description: Optional written quote — triggers the higher payout when >= MIN_QUOTE_LENGTH chars
        role_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Role Type
          description: AI-extracted or user-provided ('agency','marketer','seo','dev','other',...)
        is_agency:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Is Agency
        industry:
          anyOf:
          - type: string
          - type: 'null'
          title: Industry
        display_name_choice:
          anyOf:
          - type: string
            pattern: ^(full|first|anon)$
          - type: 'null'
          title: Display Name Choice
        display_company:
          anyOf:
          - type: string
          - type: 'null'
          title: Display Company
        ai_transcript:
          anyOf:
          - items: {}
            type: array
          - type: 'null'
          title: Ai Transcript
        ai_drafted:
          type: boolean
          title: Ai Drafted
          default: false
        source_trigger:
          type: string
          title: Source Trigger
          description: How the user got here — must match an existing prompt row when applicable
          default: manual
        display_name:
          anyOf:
          - type: string
            maxLength: 80
          - type: 'null'
          title: Display Name
        display_title:
          anyOf:
          - type: string
            maxLength: 80
          - type: 'null'
          title: Display Title
        display_image_url:
          anyOf:
          - type: string
            maxLength: 500
          - type: 'null'
          title: Display Image Url
        details_confirmed:
          type: boolean
          title: Details Confirmed
          default: false
      type: object
      required:
      - rating
      title: SubmitReviewRequest
    EligibilityResponse:
      properties:
        eligible:
          type: boolean
          title: Eligible
        reason:
          type: string
          title: Reason
        already_submitted:
          type: boolean
          title: Already Submitted
      type: object
      required:
      - eligible
      - reason
      - already_submitted
      title: EligibilityResponse
    PromptClickedRequest:
      properties:
        source_trigger:
          type: string
          title: Source Trigger
      type: object
      required:
      - source_trigger
      title: PromptClickedRequest
    ModerationRequest:
      properties:
        action:
          type: string
          pattern: ^(approve|reject|publish|unpublish|grant_reward)$
          title: Action
        rejection_reason:
          anyOf:
          - type: string
          - type: 'null'
          title: Rejection Reason
      type: object
      required:
      - action
      title: ModerationRequest