whoisgeni-us Jobs API

openapi: 3.2.0
info:
  title: WhoisGenius Jobs API
  description: 'Domain intelligence platform with AI-powered operator attribution Responses are JSON by default; request the compact, token-efficient TOON format with the `Accept: application/toon` header.'
  version: 0.1.0
tags:
- name: Jobs
paths:
  /jobs:
    get:
      tags:
      - Jobs
      summary: List jobs
      description: 'List the authenticated user''s analysis jobs, newest first.


        Accepts both Cognito JWT (dashboard) and API key auth. ``duration_ms`` is

        measured to ``completed_at``; for failed jobs persisted before

        ``completed_at`` was stamped on failure it falls back to ``updated_at``.

        Declared before ``/{job_id}`` so the literal path wins.'
      operationId: list_jobs_jobs_get
      security:
      - HTTPBearer: []
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          description: Max jobs to return (1-100).
          default: 20
          title: Limit
        description: Max jobs to return (1-100).
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          description: Rows to skip for pagination.
          default: 0
          title: Offset
        description: Rows to skip for pagination.
      - name: X-API-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse_JobListResponse_'
        '401':
          description: Missing or invalid credentials
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /jobs/{job_id}:
    get:
      tags:
      - Jobs
      summary: Get job status
      description: 'Poll a job''s current status.


        Returns the current job state (Postgres-first, with live progress

        overlaid from the Redis hash). When the job is completed or partial, the

        scoring_result from PostgreSQL is included in the response for immediate

        access to results.'
      operationId: get_job_status_jobs__job_id__get
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          title: Job Id
      - name: X-API-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse_JobStatusResponse_'
        '404':
          description: Job not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '401':
          description: Unauthorized — missing or invalid API key/JWT.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: 'null'
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: UNAUTHORIZED
                      message:
                        type: string
                  meta:
                    type: 'null'
  /jobs/{job_id}/signals:
    get:
      tags:
      - Jobs
      summary: Get per-signal breakdown
      description: 'Get the per-entity signal breakdown for a completed job.


        Provides full transparency into how entities were scored. Each entity

        includes its individual signal contributions and cross-signal correlations

        from the scoring engine output stored in the AnalysisRun JSONB.


        Available to all tiers (output is no longer tier-gated). Returns 404 if

        the job does not exist, 409 if the analysis is still in progress, and the

        full signal breakdown when complete. Internal signal weights are never

        included in the response schema.'
      operationId: get_job_signals_jobs__job_id__signals_get
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          title: Job Id
      - name: X-API-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse_SignalsResponse_'
        '404':
          description: Job not found
        '409':
          description: Analysis not yet complete
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '401':
          description: Unauthorized — missing or invalid API key/JWT.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: 'null'
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: UNAUTHORIZED
                      message:
                        type: string
                  meta:
                    type: 'null'
  /jobs/{job_id}/subdomains:
    get:
      tags:
      - Jobs
      summary: Get discovered subdomains
      description: 'Get subdomains discovered for the domain in this job.


        Triggers subdomain enumeration on first call (CT SAN extraction + DNS brute-force).

        Subsequent calls within the cache TTL return cached results.


        Returns 404 if the job does not exist, 409 if the analysis is still in progress.'
      operationId: get_job_subdomains_jobs__job_id__subdomains_get
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          title: Job Id
      - name: X-API-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse_SubdomainsResponse_'
        '404':
          description: Job not found
        '409':
          description: Analysis not yet complete
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '401':
          description: Unauthorized — missing or invalid API key/JWT.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: 'null'
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: UNAUTHORIZED
                      message:
                        type: string
                  meta:
                    type: 'null'
  /jobs/{job_id}/certificate:
    get:
      tags:
      - Jobs
      summary: Get attribution certificate
      description: 'Get a signed attribution certificate for a completed job.


        Returns a deterministic, HMAC-signed certificate containing the full

        analysis results, chain-of-evidence, and cryptographic metadata for

        independent verification.


        Implements generate-once/serve-forever: the first request creates and

        persists the certificate, subsequent requests return the stored version.


        Returns 404 if the job does not exist, 409 if the analysis is still

        in progress, and the signed certificate envelope when complete.'
      operationId: get_job_certificate_jobs__job_id__certificate_get
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          title: Job Id
      - name: format
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: 'Response format: ''pdf'', ''csv'', or ''json'''
          title: Format
        description: 'Response format: ''pdf'', ''csv'', or ''json'''
      - name: accept
        in: header
        required: false
        schema:
          type: string
          default: application/json
          title: Accept
      - name: X-API-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      responses:
        '200':
          description: Certificate as JSON envelope or PDF document
          content:
            application/json:
              schema: {}
            application/pdf: {}
        '404':
          description: Job not found or no scoring data
        '409':
          description: Analysis not yet complete
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '401':
          description: Unauthorized — missing or invalid API key/JWT.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: 'null'
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        example: UNAUTHORIZED
                      message:
                        type: string
                  meta:
                    type: 'null'
components:
  schemas:
    ErrorDetail:
      properties:
        code:
          type: string
          title: Code
        message:
          type: string
          title: Message
        details:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Details
      type: object
      required:
      - code
      - message
      title: ErrorDetail
      description: "Structured error information for API error responses.\n\nAttributes:\n    code: Machine-readable error code (e.g. \"JOB_NOT_FOUND\").\n    message: Human-readable error description.\n    details: Optional additional context for debugging."
      example:
        code: JOB_NOT_FOUND
        message: No job found with the given ID.
    SubdomainsResponse:
      properties:
        job_id:
          type: string
          title: Job Id
        domain:
          type: string
          title: Domain
        subdomains:
          items:
            $ref: '#/components/schemas/SubdomainEntry'
          type: array
          title: Subdomains
        total:
          type: integer
          title: Total
        sources_used:
          items:
            type: string
          type: array
          title: Sources Used
        cached:
          type: boolean
          title: Cached
        wildcard_detected:
          type: boolean
          title: Wildcard Detected
      type: object
      required:
      - job_id
      - domain
      - subdomains
      - total
      - sources_used
      - cached
      - wildcard_detected
      title: SubdomainsResponse
      description: "Response for the subdomain enumeration endpoint.\n\nContains all discovered subdomains with per-entry source attribution,\ncaching metadata, and wildcard detection status.\n\nAttributes:\n    job_id: The job that triggered subdomain enumeration.\n    domain: The target domain whose subdomains were discovered.\n    subdomains: List of discovered subdomains with source attribution.\n    total: Total number of unique subdomains found.\n    sources_used: Which discovery methods were used (e.g., [\"ct_san\", \"dns_brute\"]).\n    cached: Whether the result was served from Redis cache.\n    wildcard_detected: Whether the domain has a wildcard DNS record."
      example:
        cached: false
        domain: example.com
        job_id: 550e8400-e29b-41d4-a716-446655440000
        sources_used:
        - ct_san
        - dns_brute
        subdomains:
        - source: ct_san
          subdomain: mail.example.com
        - source: dns_brute
          subdomain: api.example.com
        total: 2
        wildcard_detected: false
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    JobListItem:
      properties:
        job_id:
          type: string
          title: Job Id
        domain:
          type: string
          title: Domain
        status:
          type: string
          enum:
          - pending
          - processing
          - completed
          - failed
          - partial
          title: Status
        created_at:
          type: string
          format: date-time
          title: Created At
        completed_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Completed At
        duration_ms:
          anyOf:
          - type: integer
          - type: 'null'
          title: Duration Ms
      type: object
      required:
      - job_id
      - domain
      - status
      - created_at
      title: JobListItem
      description: "A single job in the per-user job history list.\n\nAttributes:\n    job_id: Unique job identifier.\n    domain: Domain that was analyzed.\n    status: Current job status (pending, processing, completed, failed, partial).\n    created_at: When the job was submitted.\n    completed_at: When the job reached a terminal state, or None while in flight.\n    duration_ms: Wall-clock time from submission to ``completed_at`` (falling\n        back to ``updated_at`` for failed jobs persisted before the fix that\n        stamped ``completed_at``), in milliseconds."
    EntitySignalBreakdown:
      properties:
        entity:
          $ref: '#/components/schemas/EntitySummary'
        signals:
          items:
            $ref: '#/components/schemas/SignalDetail'
          type: array
          title: Signals
        correlations:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Correlations
      type: object
      required:
      - entity
      - signals
      title: EntitySignalBreakdown
      description: "Full signal breakdown for a single entity.\n\nAttributes:\n    entity: Summary of the entity being examined.\n    signals: List of individual signal contributions.\n    correlations: Cross-signal correlation evidence."
    JobListResponse:
      properties:
        items:
          items:
            $ref: '#/components/schemas/JobListItem'
          type: array
          title: Items
        total:
          type: integer
          title: Total
        limit:
          type: integer
          title: Limit
        offset:
          type: integer
          title: Offset
      type: object
      required:
      - total
      - limit
      - offset
      title: JobListResponse
      description: "Paginated per-user job history, newest first.\n\nAttributes:\n    items: The page of jobs.\n    total: Total number of jobs owned by the caller.\n    limit: Page size used for this response.\n    offset: Rows skipped for this response."
    SubdomainEntry:
      properties:
        subdomain:
          type: string
          title: Subdomain
        source:
          type: string
          enum:
          - ct_san
          - dns_brute
          title: Source
      type: object
      required:
      - subdomain
      - source
      title: SubdomainEntry
      description: "A single discovered subdomain with source attribution.\n\nAttributes:\n    subdomain: Fully qualified subdomain name (e.g., \"mail.example.com\").\n    source: Discovery method that found this subdomain."
      example:
        source: ct_san
        subdomain: mail.example.com
    SignalsResponse:
      properties:
        job_id:
          type: string
          title: Job Id
        domain:
          anyOf:
          - type: string
          - type: 'null'
          title: Domain
        entities:
          items:
            $ref: '#/components/schemas/EntitySignalBreakdown'
          type: array
          title: Entities
        missing_signals:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Missing Signals
      type: object
      required:
      - job_id
      - entities
      title: SignalsResponse
      description: "Top-level response for the signal breakdown endpoint.\n\nProvides full transparency into how entities were scored for\na given domain analysis.\n\nAttributes:\n    job_id: The job whose signals are being displayed.\n    domain: The domain that was analyzed.\n    entities: Per-entity signal breakdowns.\n    missing_signals: Signals that could not be collected."
    ApiResponse_SignalsResponse_:
      properties:
        data:
          anyOf:
          - $ref: '#/components/schemas/SignalsResponse'
          - type: 'null'
        error:
          anyOf:
          - $ref: '#/components/schemas/ErrorDetail'
          - type: 'null'
        meta:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Meta
      type: object
      title: ApiResponse[SignalsResponse]
    ApiResponse_JobStatusResponse_:
      properties:
        data:
          anyOf:
          - $ref: '#/components/schemas/JobStatusResponse'
          - type: 'null'
        error:
          anyOf:
          - $ref: '#/components/schemas/ErrorDetail'
          - type: 'null'
        meta:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Meta
      type: object
      title: ApiResponse[JobStatusResponse]
    SignalDetail:
      properties:
        signal_type:
          type: string
          title: Signal Type
        field:
          type: string
          title: Field
        raw_value:
          type: string
          title: Raw Value
        collector_confidence:
          type: number
          title: Collector Confidence
        contribution:
          type: number
          title: Contribution
        redacted:
          type: boolean
          title: Redacted
          default: false
      type: object
      required:
      - signal_type
      - field
      - raw_value
      - collector_confidence
      - contribution
      title: SignalDetail
      description: "Individual signal contribution within a signal breakdown.\n\nAttributes:\n    signal_type: Collector that produced this signal.\n    field: Specific field within the collector output.\n    raw_value: Original value from the collector.\n    collector_confidence: Collector's self-assessed data quality.\n    contribution: Effective contribution to entity score.\n    redacted: Whether the value was detected as privacy-protected."
    ApiResponse_JobListResponse_:
      properties:
        data:
          anyOf:
          - $ref: '#/components/schemas/JobListResponse'
          - type: 'null'
        error:
          anyOf:
          - $ref: '#/components/schemas/ErrorDetail'
          - type: 'null'
        meta:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Meta
      type: object
      title: ApiResponse[JobListResponse]
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    EntitySummary:
      properties:
        name:
          type: string
          title: Name
        display_name:
          type: string
          title: Display Name
        entity_type:
          type: string
          title: Entity Type
        confidence:
          type: number
          title: Confidence
      type: object
      required:
      - name
      - display_name
      - entity_type
      - confidence
      title: EntitySummary
      description: "Compact entity representation for signal breakdown responses.\n\nAttributes:\n    name: Canonical normalized entity name.\n    display_name: Best raw entity name preserving original casing.\n    entity_type: Classification (organization, person, unknown).\n    confidence: Computed confidence score from 0.0 to 1.0."
    JobStatusResponse:
      properties:
        job_id:
          type: string
          title: Job Id
        status:
          type: string
          enum:
          - pending
          - processing
          - completed
          - failed
          - partial
          title: Status
        domain:
          anyOf:
          - type: string
          - type: 'null'
          title: Domain
        phase:
          anyOf:
          - type: string
          - type: 'null'
          title: Phase
        collectors_done:
          anyOf:
          - type: integer
          - type: 'null'
          title: Collectors Done
        collectors_total:
          anyOf:
          - type: integer
          - type: 'null'
          title: Collectors Total
        analysis_run_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Analysis Run Id
        started_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Started At
        completed_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Completed At
        scoring_result:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Scoring Result
      type: object
      required:
      - job_id
      - status
      title: JobStatusResponse
      description: "Response for polling a job's current status.\n\nWhen the job is completed, ``scoring_result`` contains the full\nScoringResult dict from the scoring engine.\n\nWhen LLM enrichment is enabled and the ambiguity gate triggers,\nthe scoring_result dict includes additional fields:\nenriched_conclusion, entity_resolution_notes, arbitration_reasoning.\nThese fields are null/absent when LLM was not invoked.\n\nAttributes:\n    job_id: Unique job identifier.\n    status: Current job status (pending, processing, completed, failed).\n    domain: Domain being analyzed.\n    collectors_done: Number of collectors that have finished.\n    collectors_total: Total number of collectors in the pipeline.\n    analysis_run_id: Database analysis run ID.\n    started_at: ISO 8601 timestamp when the job started processing.\n    completed_at: ISO 8601 timestamp when the job finished.\n    scoring_result: Full scoring result dict when completed. May include\n        enriched_conclusion, entity_resolution_notes, and\n        arbitration_reasoning when LLM enrichment was invoked."
      example:
        analysis_run_id: 660e8400-e29b-41d4-a716-446655440001
        collectors_done: 3
        collectors_total: 7
        domain: example.com
        job_id: 550e8400-e29b-41d4-a716-446655440000
        started_at: '2026-03-18T12:00:00Z'
        status: processing
    ApiResponse_SubdomainsResponse_:
      properties:
        data:
          anyOf:
          - $ref: '#/components/schemas/SubdomainsResponse'
          - type: 'null'
        error:
          anyOf:
          - $ref: '#/components/schemas/ErrorDetail'
          - type: 'null'
        meta:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Meta
      type: object
      title: ApiResponse[SubdomainsResponse]
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer