whoisgeni-us Correlation API

openapi: 3.2.0
info:
  title: WhoisGenius Correlation 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: correlation
paths:
  /correlate:
    post:
      tags:
      - correlation
      summary: Submit cross-domain correlation
      description: 'Submit 2-100 domains for cross-domain correlation analysis.


        Creates a background job to analyze uncached domains, compute pairwise

        correlation scores, detect clusters, and generate LLM summaries.


        Correlation is a credit-billed product available to any account with

        sufficient credits (no subscription tier required — Gap G, Option A).


        Credit billing: 1 credit per uncached domain + 1 for the correlation

        compute, debited as ONE job-keyed charge (single settlement; exactly-once

        via the ``charge:{job_id}`` ledger idempotency key). The charge is refunded

        via the keyed settle path if dispatch fails or the job ends ``failed``.'
      operationId: submit_correlation_correlate_post
      parameters:
      - name: X-API-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CorrelateRequest'
      responses:
        '202':
          description: Correlation job accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse_CorrelateResponse_'
        '402':
          description: Insufficient credits
        '422':
          description: Invalid request (domain count out of range)
        '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'
  /correlate/{correlation_id}:
    get:
      tags:
      - correlation
      summary: Get correlation job status
      description: 'Poll the status of a correlation job.


        Returns the current job status. When status is "completed", the full

        correlation result (clusters, pairwise scores, summaries) is included.'
      operationId: get_correlation_status_correlate__correlation_id__get
      parameters:
      - name: correlation_id
        in: path
        required: true
        schema:
          type: string
          title: Correlation Id
      - name: X-API-Key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      responses:
        '200':
          description: Correlation job status and result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse_CorrelateStatusResponse_'
        '404':
          description: Correlation 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'
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
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    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.
    PairwiseEvidence:
      properties:
        signals:
          items:
            $ref: '#/components/schemas/EvidenceSignal'
          type: array
          title: Signals
        available_signal_count:
          type: integer
          title: Available Signal Count
          default: 0
        adjustments:
          items:
            type: string
          type: array
          title: Adjustments
        both_cdn:
          type: boolean
          title: Both Cdn
          default: false
        score_pre_round:
          type: number
          maximum: 1.0
          minimum: 0.0
          title: Score Pre Round
          default: 0.0
      type: object
      title: PairwiseEvidence
      description: 'Evidence ledger for one pairwise score.


        The public explainability contract for a pair: WHICH signals matched

        (type + value + strength bucket), how many signal types were available

        to compare (the dilution denominator, as a COUNT), and which scoring

        adjustments fired. Raw weight numbers are never exposed.'
    EvidenceSignal:
      properties:
        signal_type:
          type: string
          title: Signal Type
        value:
          type: string
          title: Value
        strength_bucket:
          type: string
          enum:
          - strong
          - moderate
          - weak
          title: Strength Bucket
      type: object
      required:
      - signal_type
      - value
      - strength_bucket
      title: EvidenceSignal
      description: 'One matched signal in the pairwise evidence ledger.


        Carries the signal type, the concrete matched value, and a coarse

        strength bucket -- never the raw scoring weight (opsec: exact weights

        must not appear in user-facing output).'
    CorrelateResponse:
      properties:
        job_id:
          type: string
          title: Job Id
        correlation_id:
          type: string
          title: Correlation Id
        poll_url:
          type: string
          title: Poll Url
        domain_count:
          type: integer
          title: Domain Count
        domains_cached:
          type: integer
          title: Domains Cached
        domains_to_analyze:
          type: integer
          title: Domains To Analyze
        credits_charged:
          type: integer
          title: Credits Charged
        status:
          type: string
          title: Status
          default: pending
      type: object
      required:
      - job_id
      - correlation_id
      - poll_url
      - domain_count
      - domains_cached
      - domains_to_analyze
      - credits_charged
      title: CorrelateResponse
      description: "Response after submitting a correlation analysis (202 Accepted).\n\nAttributes:\n    job_id: Unique correlation job identifier for polling status.\n    correlation_id: Alias of ``job_id`` -- the value to pass to\n        ``GET /correlate/{correlation_id}``.\n    poll_url: Relative URL to poll for status/results. Correlation jobs are\n        NOT retrievable from ``GET /jobs/{id}`` (that serves single-domain\n        analysis only); this points at the correct endpoint.\n    domain_count: Number of domains submitted.\n    domains_cached: Number of domains with fully cached signals.\n    domains_to_analyze: Number of domains needing fresh analysis.\n    credits_charged: Total credits deducted for this request.\n    status: Initial job status (always \"pending\")."
      example:
        correlation_id: 3f6b8c2a-7a1d-4e5f-9b0c-2d4e6f8a0b1c
        credits_charged: 4
        domain_count: 7
        domains_cached: 4
        domains_to_analyze: 3
        job_id: 3f6b8c2a-7a1d-4e5f-9b0c-2d4e6f8a0b1c
        poll_url: /correlate/3f6b8c2a-7a1d-4e5f-9b0c-2d4e6f8a0b1c
        status: pending
    CorrelateRequest:
      properties:
        domains:
          items:
            type: string
          type: array
          maxItems: 100
          minItems: 2
          title: Domains
        callback_url:
          anyOf:
          - type: string
            maxLength: 2048
            pattern: ^https?://
          - type: 'null'
          title: Callback Url
          description: Optional URL to receive a webhook POST when correlation completes
      type: object
      required:
      - domains
      title: CorrelateRequest
      description: "Request body for submitting a cross-domain correlation analysis.\n\nAttributes:\n    domains: List of domain names to correlate (2-100).\n    callback_url: Optional webhook URL for completion notification."
      example:
        callback_url: https://example.com/webhook
        domains:
        - example.com
        - example.org
    CorrelationResult:
      properties:
        correlation_id:
          type: string
          title: Correlation Id
        domain_count:
          type: integer
          title: Domain Count
        analyzed_at:
          type: string
          title: Analyzed At
        clusters:
          items:
            $ref: '#/components/schemas/CorrelationCluster'
          type: array
          title: Clusters
        unclustered_domains:
          items:
            type: string
          type: array
          title: Unclustered Domains
        pairwise:
          items:
            $ref: '#/components/schemas/PairwiseScore'
          type: array
          title: Pairwise
        correlation_summary:
          anyOf:
          - type: string
          - type: 'null'
          title: Correlation Summary
        excluded_domains:
          items:
            type: string
          type: array
          title: Excluded Domains
        degraded:
          type: boolean
          title: Degraded
          default: false
      type: object
      required:
      - correlation_id
      - domain_count
      - analyzed_at
      - clusters
      - unclustered_domains
      - pairwise
      title: CorrelationResult
      description: 'Top-level correlation engine output.


        Contains clusters, pairwise scores, and unclustered domains for a

        cross-domain correlation analysis. Matches the design partner spec

        shape (Example 3 in output_examples.md).'
    ClusterEvidence:
      properties:
        mean_pairwise_score:
          type: number
          title: Mean Pairwise Score
          default: 0.0
        corroboration_bonus:
          type: number
          title: Corroboration Bonus
          default: 0.0
      type: object
      title: ClusterEvidence
      description: 'Evidence ledger for one cluster''s confidence score.


        Splits the reported confidence into the two components that

        ``ClusterBuilder._compute_confidence`` has always computed and then

        discarded: the mean intra-cluster pairwise score and the capped

        corroboration bonus for distinct owner-relation signal types.'
    ClusterEdge:
      properties:
        from_domain:
          type: string
          title: From Domain
        to_domain:
          type: string
          title: To Domain
        reason:
          type: string
          title: Reason
      type: object
      required:
      - from_domain
      - to_domain
      - reason
      title: ClusterEdge
      description: 'A directed, reason-annotated hop in a cluster''s edge list (R3).


        Expresses the pairwise evidence that caused two domains to be placed in

        the same cluster as a human-readable ``{from_domain, to_domain, reason}``

        triple. Each signal match between a pair produces one edge entry so the

        cluster is explainable hop-by-hop (e.g. domain_a -> domain_b :

        ``"shared analytics_id G-XXXX"``).


        ``from_domain`` / ``to_domain`` are ordered lexicographically (the lower

        comes first) so edges are deterministic and deduplication is trivial.'
    PairwiseScore:
      properties:
        domain_a:
          type: string
          title: Domain A
        domain_b:
          type: string
          title: Domain B
        correlation:
          type: number
          maximum: 1.0
          minimum: 0.0
          title: Correlation
        shared_signals:
          items:
            type: string
          type: array
          title: Shared Signals
        matched_signals:
          items:
            $ref: '#/components/schemas/PairwiseSignalMatch'
          type: array
          title: Matched Signals
        evidence:
          anyOf:
          - $ref: '#/components/schemas/PairwiseEvidence'
          - type: 'null'
      type: object
      required:
      - domain_a
      - domain_b
      - correlation
      - shared_signals
      title: PairwiseScore
      description: 'Pairwise correlation between two domains.


        Captures the computed correlation score and the list of signal types

        that contributed to it.'
    SharedSignal:
      properties:
        signal_type:
          type: string
          title: Signal Type
        value:
          type: string
          title: Value
        domains_sharing:
          type: integer
          title: Domains Sharing
        all_domains:
          type: boolean
          title: All Domains
        relation:
          type: string
          enum:
          - owner
          - host
          - mixed
          title: Relation
          default: host
      type: object
      required:
      - signal_type
      - value
      - domains_sharing
      - all_domains
      title: SharedSignal
      description: 'A signal shared across domains in a cluster or pair.


        Represents aggregate signal evidence within a correlation cluster,

        documenting which signals are shared by how many domains.'
    CorrelationCluster:
      properties:
        cluster_id:
          type: string
          title: Cluster Id
        confidence:
          type: number
          maximum: 1.0
          minimum: 0.0
          title: Confidence
        domain_count:
          type: integer
          title: Domain Count
        domains:
          items:
            type: string
          type: array
          title: Domains
        shared_signals:
          items:
            $ref: '#/components/schemas/SharedSignal'
          type: array
          title: Shared Signals
        edges:
          items:
            $ref: '#/components/schemas/ClusterEdge'
          type: array
          title: Edges
        summary:
          anyOf:
          - type: string
          - type: 'null'
          title: Summary
        evidence:
          anyOf:
          - $ref: '#/components/schemas/ClusterEvidence'
          - type: 'null'
      type: object
      required:
      - cluster_id
      - confidence
      - domain_count
      - domains
      - shared_signals
      title: CorrelationCluster
      description: 'A group of domains with high pairwise correlation.


        Domains within a cluster share sufficient pairwise correlation to be grouped.

        Includes per-cluster confidence and shared signal evidence for transparency.'
    ApiResponse_CorrelateResponse_:
      properties:
        data:
          anyOf:
          - $ref: '#/components/schemas/CorrelateResponse'
          - type: 'null'
        error:
          anyOf:
          - $ref: '#/components/schemas/ErrorDetail'
          - type: 'null'
        meta:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Meta
      type: object
      title: ApiResponse[CorrelateResponse]
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    CorrelateStatusResponse:
      properties:
        correlation_id:
          type: string
          title: Correlation Id
        status:
          type: string
          title: Status
        domain_count:
          type: integer
          title: Domain Count
        result:
          anyOf:
          - $ref: '#/components/schemas/CorrelationResult'
          - type: 'null'
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
        phase:
          anyOf:
          - type: string
          - type: 'null'
          title: Phase
      type: object
      required:
      - correlation_id
      - status
      - domain_count
      title: CorrelateStatusResponse
      description: "Response for polling correlation job status.\n\nAttributes:\n    correlation_id: The correlation job identifier.\n    status: Current job status (pending | processing | completed | failed).\n        Always converges on a terminal value: a job that outlives its budget\n        is reported ``failed`` rather than ``processing`` forever (#363).\n    domain_count: Number of domains in the correlation.\n    result: Correlation result when status is \"completed\".\n    error: Error message when status is \"failed\".\n    phase: Coarse progress hint while non-terminal (``queued`` ->\n        ``analyzing`` -> ``correlating`` -> ``summarizing``). Cosmetic only,\n        and distinct from ``status`` -- it lets a poller show real progress\n        instead of an opaque \"processing\", and distinguishes a job still\n        waiting for a worker (``queued``) from one being worked on."
      example:
        correlation_id: 3f6b8c2a-7a1d-4e5f-9b0c-2d4e6f8a0b1c
        domain_count: 7
        status: completed
    ApiResponse_CorrelateStatusResponse_:
      properties:
        data:
          anyOf:
          - $ref: '#/components/schemas/CorrelateStatusResponse'
          - type: 'null'
        error:
          anyOf:
          - $ref: '#/components/schemas/ErrorDetail'
          - type: 'null'
        meta:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Meta
      type: object
      title: ApiResponse[CorrelateStatusResponse]
    PairwiseSignalMatch:
      properties:
        signal_type:
          type: string
          title: Signal Type
        value:
          type: string
          title: Value
      type: object
      required:
      - signal_type
      - value
      title: PairwiseSignalMatch
      description: 'Enriched signal match record on a PairwiseScore (R3).


        Carries the signal type name and the matched value so callers can

        build human-readable edge reasons without re-inspecting raw collector

        data. Deliberately omits the internal scoring weight (opsec: weights

        must not appear in user-facing output).'
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer