Bulk URL Checker Jobs API

openapi: 3.2.0
info:
  title: Reception Desk Jobs API
  description: API Gateway for URL Checker Engine
  version: 1.0.0
tags:
- name: Jobs
paths:
  /jobs:
    post:
      summary: Create Job With Csv
      description: 'Direct CSV upload. Creates a single job regardless of user balance.


        Credit model: deduct min(unique_urls, balance) up front. If the user

        doesn''t have enough to cover the whole upload, the job pauses at the

        credit ceiling and the user can buy more credits to resume via the

        progress page.


        Query Parameters:

        auto_add_prefix: If true, auto-add https:// to URLs missing prefix

        skip_blocked: If true, skip URLs from blocked domains

        skip_invalid: If true, skip malformed URLs


        **Authentication Required:** User must be signed in.'
      operationId: create_job_with_csv_jobs_post
      parameters:
      - name: auto_add_prefix
        in: query
        required: false
        schema:
          type: boolean
          default: true
          title: Auto Add Prefix
      - name: skip_blocked
        in: query
        required: false
        schema:
          type: boolean
          default: true
          title: Skip Blocked
      - name: skip_invalid
        in: query
        required: false
        schema:
          type: boolean
          default: true
          title: Skip Invalid
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_create_job_with_csv_jobs_post'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Jobs
    get:
      summary: List Jobs
      description: 'Proxy endpoint: List jobs for a user.

        Forwards request to job-service.


        Uses httpx params= kwarg rather than string-concat so plus signs

        in the email (foo+alias@example.com) survive — string-concat sends

        a literal ''+'', which the receiving server decodes as a space and

        fails to match any user.'
      operationId: list_jobs_jobs_get
      parameters:
      - name: email
        in: query
        required: true
        schema:
          type: string
          title: Email
      - name: status
        in: query
        required: false
        schema:
          type: string
          title: Status
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 20
          title: Limit
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          default: 0
          title: Offset
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Jobs
  /jobs/{job_id}/resume:
    post:
      summary: Resume Job
      description: 'Bump the job''s credits_allocated by what the user can afford and publish

        the next batch of URLs to workers. Idempotent via an optimistic-lock

        UPDATE on jobs (concurrent resume requests from the same user will

        either both succeed serialized or one returns 409 without double-charging).


        Requires ownership.'
      operationId: resume_job_jobs__job_id__resume_post
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          title: Job Id
      - 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:
      - Jobs
  /jobs/{job_id}/pause:
    post:
      summary: Pause Job Endpoint
      description: User-initiated pause. Only transitions a 'processing' job.
      operationId: pause_job_endpoint_jobs__job_id__pause_post
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          title: Job Id
      - 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:
      - Jobs
  /jobs/{job_id}/domain-issues:
    get:
      summary: Get Job Domain Issues
      description: 'Per-domain rate-limit signal for a customer''s job. Called by the

        job details page every few seconds while the job is processing.


        Returns `{issues: [{domain, pending_count, refusal_count, first_seen,

        last_seen}]}` — an empty list when nothing is stuck.'
      operationId: get_job_domain_issues_jobs__job_id__domain_issues_get
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          title: Job Id
      - 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:
      - Jobs
  /jobs/{job_id}/skip-domain:
    post:
      summary: Skip Job Domain
      description: 'Cancel pending URLs on the specified domain of this job + refund

        the equivalent credits. Customer''s escape hatch when a target is

        aggressively rate-limiting.


        Body: `{"domain": "www.example.com"}`.


        Safety guards:

        * Caller must own the job.

        * Domain must actually meet the detection threshold — no bypassing

        the check to force-cancel arbitrary URLs.

        * Job must not already have credits_refunded > 0 (billing-service''s

        refund idempotency uses job_id; a second refund would silently

        no-op, so we block instead of confuse the user).'
      operationId: skip_job_domain_jobs__job_id__skip_domain_post
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          title: Job Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              title: Body
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Jobs
  /jobs/{job_id}:
    get:
      summary: Get Job Status
      description: 'Get job status and progress.


        **Authentication Required:** User must be signed in and own the job.'
      operationId: get_job_status_jobs__job_id__get
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          title: Job Id
      - 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/src__api__routes__JobStatusResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Jobs
    delete:
      summary: Delete Job
      description: 'Delete a job permanently.


        Authorization: the requester must either own the job (clerk_user_id

        match) OR have the admin role. Anyone else gets 403.


        Status gate: only terminal-state jobs can be deleted (completed,

        cancelled, failed). Running or paused jobs return 409 with a clear

        message that they must be cancelled first. This is enforced

        server-side regardless of how the request arrives — the dashboard

        UI also hides the delete affordance for non-terminal jobs as a

        second-line UX guardrail.


        Refund policy on delete: only refund unused credits when the job

        ended in `failed` (system-side error). For `completed` the math is

        moot (completed_urls equals credits_allocated, refund = 0). For

        `cancelled` we deliberately do NOT refund — the user already chose

        to abandon at cancel time, and refunding here would backdoor the

        no-refund cancel policy (cancel-then-delete becomes a hidden

        refund button).'
      operationId: delete_job_jobs__job_id__delete
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          title: Job Id
      - 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:
      - Jobs
  /jobs/{job_id}/cancel:
    post:
      summary: Cancel Job
      description: 'Cancel a running or paused job.


        Authentication required. The user must own the job (job-service''s

        cancel endpoint does the ownership check via clerk_user_id, and

        auth here gates access to this proxy in the first place).


        Policy: cancel REFUNDS unused credits. credits_allocated - completed_urls

        goes back to the owner''s balance. Without this, users have no

        incentive to stop a runaway job — they''d rather let it consume

        credits than cancel for nothing. Standard SaaS cancellation

        semantics (Stripe, ride-share, prepaid services).


        Abuse vector ("submit big job, cancel for full refund, repeat"):

        not actually possible. Cancel doesn''t let the user re-upload

        different URLs — the job''s URL list is already in the database.

        The previous no-refund concern was about iteration via DELETE,

        which is now blocked entirely (delete requires terminal status).


        Refund is idempotent on (transaction_type=''refund'',

        reference_id=job_id), so a retry after a partial failure won''t

        double-credit.


        Effects:

        - Job status → ''cancelled'' (jobs row preserved)

        - Workers honor the job.cancelled event and stop processing

        - Already-completed URL results kept for download/export

        - max(0, credits_allocated - completed_urls) refunded to owner'
      operationId: cancel_job_jobs__job_id__cancel_post
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          title: Job Id
      - 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:
      - Jobs
  /jobs/{job_id}/download:
    get:
      summary: Get Download Link
      description: 'Get download link for completed job results with optional filters.


        **Authentication Required:** User must be signed in and own the job.


        Query Parameters:

        - status_codes: Comma-separated status codes (e.g., "404,500")

        - non_2xx: Filter for non-2xx status codes

        - url_contains: Filter URLs containing this text'
      operationId: get_download_link_jobs__job_id__download_get
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          title: Job Id
      - name: status_codes
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Status Codes
      - name: non_2xx
        in: query
        required: false
        schema:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Non 2Xx
      - name: url_contains
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Url Contains
      - 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/DownloadLinkResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Jobs
  /jobs/{job_id}/export:
    get:
      summary: Export Job Results
      description: 'Export job results as CSV or XLSX (proxies to export-service).


        **Authentication Required:** User must be signed in and own the job.


        Query Parameters:

        - format: Export format - "csv" (default) or "xlsx"

        - status_codes: Comma-separated status codes (e.g., "404,500")

        - non_2xx: Filter for non-2xx status codes

        - url_contains: Filter URLs containing this text'
      operationId: export_job_results_jobs__job_id__export_get
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          title: Job Id
      - name: format
        in: query
        required: false
        schema:
          type: string
          default: csv
          title: Format
      - name: status_codes
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Status Codes
      - name: non_2xx
        in: query
        required: false
        schema:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Non 2Xx
      - name: url_contains
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Url Contains
      - 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:
      - Jobs
  /jobs/bulk-delete:
    post:
      summary: Bulk Delete Jobs
      description: 'Bulk delete jobs.


        Authorization (per-job): owner OR admin. Non-authorized jobs are

        reported in `errors`, never silently dropped.


        Status gate (per-job): only terminal statuses (completed, cancelled,

        failed) are deletable. Non-terminal jobs are reported in `errors`

        with a clear "cancel first" message.


        Refund policy (per-job): only refund unused credits when the job

        ended in `failed`. completed = math-moot, cancelled = policy-moot

        (no-refund-on-cancel must apply through delete too).


        Note: Using POST instead of DELETE for better HTTP client compatibility.'
      operationId: bulk_delete_jobs_jobs_bulk_delete_post
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              title: Body
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Jobs
  /jobs/{job_id}/share:
    post:
      summary: Create Job Share
      description: Create a public share token for a job. Owner-only.
      operationId: create_job_share_jobs__job_id__share_post
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          title: Job Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        content:
          application/json:
            schema:
              type: object
              default: {}
              title: Body
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Jobs
  /jobs/{job_id}/shares:
    get:
      summary: List Job Shares
      description: List all share tokens for a job. Owner-only.
      operationId: list_job_shares_jobs__job_id__shares_get
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          title: Job Id
      - 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:
      - Jobs
  /jobs/{job_id}/share/{token}:
    delete:
      summary: Revoke Job Share
      description: Revoke a share token. Owner-only.
      operationId: revoke_job_share_jobs__job_id__share__token__delete
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          title: Job Id
      - name: token
        in: path
        required: true
        schema:
          type: string
          title: Token
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Jobs
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
    src__api__routes__JobStatusResponse:
      properties:
        id:
          type: string
          title: Id
        user_email:
          type: string
          title: User Email
        csv_path:
          type: string
          title: Csv Path
        total_urls:
          type: integer
          title: Total Urls
        completed_urls:
          type: integer
          title: Completed Urls
        status:
          type: string
          title: Status
        created_at:
          type: string
          title: Created At
        started_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Started At
        completed_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Completed At
        credits_allocated:
          type: integer
          title: Credits Allocated
          default: 0
        paused_by_user:
          type: boolean
          title: Paused By User
          default: false
        domain:
          anyOf:
          - type: string
          - type: 'null'
          title: Domain
        audit_source:
          anyOf:
          - type: string
          - type: 'null'
          title: Audit Source
      type: object
      required:
      - id
      - user_email
      - csv_path
      - total_urls
      - completed_urls
      - status
      - created_at
      title: JobStatusResponse
    DownloadLinkResponse:
      properties:
        downloadUrl:
          type: string
          title: Downloadurl
      type: object
      required:
      - downloadUrl
      title: DownloadLinkResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    Body_create_job_with_csv_jobs_post:
      properties:
        file:
          type: string
          format: binary
          title: File
      type: object
      required:
      - file
      title: Body_create_job_with_csv_jobs_post