whoisgeni-us Domains API

openapi: 3.2.0
info:
  title: WhoisGenius Domains 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: Domains
paths:
  /domains/{domain}/history:
    get:
      tags:
      - Domains
      summary: Get domain analysis history
      description: 'Get chronological analysis history for a domain.


        Returns paginated analysis runs with entity attribution, confidence

        scores, and diffs between consecutive runs showing entity, registrar,

        nameserver, and confidence changes.


        Supports cursor-based pagination via the ``before`` parameter (ISO 8601

        timestamp from ``next_cursor`` in a previous response).


        When ``include_external`` is True, merges pre-WhoisGenius ownership

        history from the WHOIS History API into the timeline. External entries

        are labeled ``source: external`` and only include records that predate

        the earliest local analysis. Costs 50 credits per call.


        Returns 404 if the domain has never been analyzed.'
      operationId: get_domain_history_domains__domain__history_get
      parameters:
      - name: domain
        in: path
        required: true
        schema:
          type: string
          title: Domain
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          default: 20
          title: Limit
      - name: before
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: 'Cursor: ISO 8601 timestamp for pagination'
          title: Before
        description: 'Cursor: ISO 8601 timestamp for pagination'
      - name: include_external
        in: query
        required: false
        schema:
          type: boolean
          description: Include pre-WhoisGenius ownership history from WHOIS History API (50 credits)
          default: false
          title: Include External
        description: Include pre-WhoisGenius ownership history from WHOIS History API (50 credits)
      - 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_HistoryResponse_'
        '404':
          description: Domain 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'
  /domains/{domain}/portfolio:
    get:
      tags:
      - Domains
      summary: Get domain entity portfolio
      description: 'Discover related domains via the top entity''s Reverse WHOIS portfolio.


        Looks up the most recent analysis for the given domain, extracts the

        top-ranked entity, and queries the Reverse WHOIS API

        to find all domains associated with that entity.


        Returns HTTP 404 if the domain has not been analyzed or has no entity.

        Returns HTTP 503 when the Reverse WHOIS service is unavailable.


        Requires API key authentication via X-API-Key header.'
      operationId: get_domain_portfolio_domains__domain__portfolio_get
      parameters:
      - name: domain
        in: path
        required: true
        schema:
          type: string
          title: Domain
      - 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_DomainPortfolioResponse_'
        '404':
          description: Domain not analyzed or no entity found
        '503':
          description: Reverse WHOIS service unavailable
        '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.
    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
    ApiResponse_DomainPortfolioResponse_:
      properties:
        data:
          anyOf:
          - $ref: '#/components/schemas/DomainPortfolioResponse'
          - type: 'null'
        error:
          anyOf:
          - $ref: '#/components/schemas/ErrorDetail'
          - type: 'null'
        meta:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Meta
      type: object
      title: ApiResponse[DomainPortfolioResponse]
    PortfolioDomain:
      properties:
        domain_name:
          type: string
          title: Domain Name
      type: object
      required:
      - domain_name
      title: PortfolioDomain
      description: "A single domain from Reverse WHOIS portfolio results.\n\nAttributes:\n    domain_name: Fully qualified domain name."
    HistoryResponse:
      properties:
        domain:
          type: string
          title: Domain
        total_runs:
          type: integer
          title: Total Runs
        entries:
          items:
            $ref: '#/components/schemas/HistoryEntry'
          type: array
          title: Entries
        next_cursor:
          anyOf:
          - type: string
          - type: 'null'
          title: Next Cursor
        has_more:
          type: boolean
          title: Has More
          default: false
      type: object
      required:
      - domain
      - total_runs
      - entries
      title: HistoryResponse
      description: "Paginated history of analysis runs for a domain.\n\nAttributes:\n    domain: The domain name queried.\n    total_runs: Total number of completed/partial runs for this domain.\n    entries: List of history entries (newest first).\n    next_cursor: Cursor for the next page (completed_at ISO timestamp).\n    has_more: Whether more entries exist beyond this page."
    HistoryEntry:
      properties:
        analysis_run_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Analysis Run Id
        completed_at:
          type: string
          title: Completed At
        status:
          type: string
          title: Status
        entity:
          type: string
          title: Entity
        entity_type:
          type: string
          title: Entity Type
        confidence:
          type: number
          title: Confidence
        registrar:
          anyOf:
          - type: string
          - type: 'null'
          title: Registrar
        nameservers:
          items:
            type: string
          type: array
          title: Nameservers
        verdict:
          anyOf:
          - type: string
          - type: 'null'
          title: Verdict
        verdict_operator:
          anyOf:
          - type: string
          - type: 'null'
          title: Verdict Operator
        diff:
          anyOf:
          - $ref: '#/components/schemas/RunDiff'
          - type: 'null'
        source:
          type: string
          title: Source
          default: local
      type: object
      required:
      - completed_at
      - status
      - entity
      - entity_type
      - confidence
      title: HistoryEntry
      description: "A single analysis run in the domain's history timeline.\n\nAttributes:\n    analysis_run_id: UUID of the analysis run, or None for external entries.\n    completed_at: ISO 8601 timestamp when the run completed.\n    status: Run status (completed, partial, or historical).\n    entity: Top attributed entity display name.\n    entity_type: Entity classification (organization, person, unknown).\n    confidence: Top entity confidence score (0.0 to 1.0).\n    registrar: Domain registrar from WHOIS data.\n    nameservers: Sorted list of nameservers.\n    verdict: Attribution verdict tier for this run, or None for runs\n        persisted before verdicts existed and external entries.\n    verdict_operator: Operator named by the verdict, when present.\n    diff: Changes from the previous run, or None for the first run.\n    source: Source of this entry: \"local\" (WhoisGenius analysis) or\n        \"external\" (upstream WHOIS History provider)."
    VerdictChange:
      properties:
        from:
          type: string
          title: From
        to:
          type: string
          title: To
        direction:
          type: string
          enum:
          - upgrade
          - downgrade
          - lateral
          title: Direction
        operator:
          anyOf:
          - $ref: '#/components/schemas/FieldChange'
          - type: 'null'
      type: object
      required:
      - from
      - to
      - direction
      title: VerdictChange
      description: "A change in the attribution verdict between consecutive runs.\n\nPopulated only when both runs carry an attribution verdict (runs\npersisted before verdicts existed have ``verdict=None`` and produce no\nVerdictChange). ``direction`` is relative to the tier ordinal:\n``upgrade`` when attribution strengthened, ``downgrade`` when it weakened,\n``lateral`` when the tier held but the operator identity changed.\n\nAttributes:\n    from_tier: Previous verdict tier (serialized as \"from\").\n    to_tier: Current verdict tier (serialized as \"to\").\n    direction: upgrade, downgrade, or lateral.\n    operator: Operator identity change, when the named operator differs."
    RunDiff:
      properties:
        entity:
          anyOf:
          - $ref: '#/components/schemas/FieldChange'
          - type: 'null'
        confidence_delta:
          anyOf:
          - type: number
          - type: 'null'
          title: Confidence Delta
        registrar:
          anyOf:
          - $ref: '#/components/schemas/FieldChange'
          - type: 'null'
        nameservers:
          anyOf:
          - $ref: '#/components/schemas/NameserverDiff'
          - type: 'null'
        verdict:
          anyOf:
          - $ref: '#/components/schemas/VerdictChange'
          - type: 'null'
        significance:
          type: string
          enum:
          - material
          - minor
          - none
          title: Significance
          default: none
        significance_reasons:
          items:
            type: string
          type: array
          title: Significance Reasons
      type: object
      title: RunDiff
      description: "Diff between this run and the previous run.\n\nAll change fields are None when unchanged. The entire diff is None for\nthe first run in a domain's history (no previous run to compare).\n\nAttributes:\n    entity: Entity attribution change (from/to display names).\n    confidence_delta: Change in top-entity confidence score.\n    registrar: Registrar change (from/to).\n    nameservers: Nameserver additions and removals.\n    verdict: Attribution verdict transition, when both runs have a verdict.\n    significance: Whether this change is worth acting on -- ``material``\n        (an operator/verdict/registrar/NS-migration event a monitor would\n        alert on), ``minor`` (a timeline detail), or ``none``.\n    significance_reasons: Ordered, human-readable reasons for the\n        significance classification (most significant first)."
    ApiResponse_HistoryResponse_:
      properties:
        data:
          anyOf:
          - $ref: '#/components/schemas/HistoryResponse'
          - type: 'null'
        error:
          anyOf:
          - $ref: '#/components/schemas/ErrorDetail'
          - type: 'null'
        meta:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Meta
      type: object
      title: ApiResponse[HistoryResponse]
    FieldChange:
      properties:
        from:
          type: string
          title: From
        to:
          type: string
          title: To
      type: object
      required:
      - from
      - to
      title: FieldChange
      description: "A single field that changed between consecutive runs.\n\nAttributes:\n    from_value: Previous value (serialized as \"from\").\n    to_value: Current value (serialized as \"to\")."
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    NameserverDiff:
      properties:
        added:
          items:
            type: string
          type: array
          title: Added
        removed:
          items:
            type: string
          type: array
          title: Removed
      type: object
      title: NameserverDiff
      description: "Nameserver additions and removals between consecutive runs.\n\nAttributes:\n    added: Nameservers present in current but not previous run.\n    removed: Nameservers present in previous but not current run."
    DomainPortfolioResponse:
      properties:
        domain:
          type: string
          title: Domain
        entity_name:
          type: string
          title: Entity Name
        portfolio_count:
          type: integer
          title: Portfolio Count
        domains:
          items:
            $ref: '#/components/schemas/PortfolioDomain'
          type: array
          title: Domains
        cached:
          type: boolean
          title: Cached
      type: object
      required:
      - domain
      - entity_name
      - portfolio_count
      - domains
      - cached
      title: DomainPortfolioResponse
      description: "Portfolio of domains owned by the same entity as the queried domain.\n\nAttributes:\n    domain: The queried domain name.\n    entity_name: The top entity found for this domain from scoring.\n    portfolio_count: Total domains in portfolio (may exceed len(domains)).\n    domains: Up to 50 domains from the entity's Reverse WHOIS portfolio.\n    cached: Whether the result was served from cache."
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer