whoisgeni-us Entities API

openapi: 3.2.0
info:
  title: WhoisGenius Entities 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: Entities
paths:
  /entities/search:
    get:
      tags:
      - Entities
      summary: Search entities by name
      description: 'Search entities by name with relevance ranking.


        Returns entities matching the query ranked by relevance (exact > prefix

        > substring), with associated domains and per-domain attribution

        confidence from entity signals.


        Query is normalized using the same function used to store entity names,

        so searches like "Google LLC" and "google" both match the same entities.


        When ``include_portfolio`` is true, top 5 results are enriched with a

        ``portfolio_count`` field from Reverse WHOIS preview mode (free, adds

        1-3 seconds latency per entity).


        Requires API key authentication via X-API-Key header.'
      operationId: search_entities_entities_search_get
      parameters:
      - name: q
        in: query
        required: true
        schema:
          type: string
          minLength: 2
          maxLength: 255
          description: Entity name search query
          title: Q
        description: Entity name search query
      - 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
          minimum: 0
          default: 0
          title: Offset
      - name: include_portfolio
        in: query
        required: false
        schema:
          type: boolean
          description: Include portfolio count from Reverse WHOIS (adds latency)
          default: false
          title: Include Portfolio
        description: Include portfolio count from Reverse WHOIS (adds latency)
      - 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_EntitySearchResponse_'
        '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'
  /entities/{name}/portfolio:
    get:
      tags:
      - Entities
      summary: Get entity domain portfolio
      description: 'Discover all domains associated with an entity via Reverse WHOIS.


        Queries the Reverse WHOIS API to find domains registered

        to or associated with the given entity name. Results are capped at 50

        domains and cached for 7 days.


        Returns HTTP 503 when the Reverse WHOIS service is unavailable or

        not configured. This endpoint is independent of the main analysis

        pipeline and never degrades analysis performance.


        Requires API key authentication via X-API-Key header.'
      operationId: get_entity_portfolio_entities__name__portfolio_get
      parameters:
      - name: name
        in: path
        required: true
        schema:
          type: string
          minLength: 2
          maxLength: 255
          description: Entity name to query (2-255 chars, no control characters)
          title: Name
        description: Entity name to query (2-255 chars, no control characters)
      - 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_PortfolioResponse_'
        '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_EntitySearchResponse_:
      properties:
        data:
          anyOf:
          - $ref: '#/components/schemas/EntitySearchResponse'
          - type: 'null'
        error:
          anyOf:
          - $ref: '#/components/schemas/ErrorDetail'
          - type: 'null'
        meta:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Meta
      type: object
      title: ApiResponse[EntitySearchResponse]
    EntityMatch:
      properties:
        entity_id:
          type: string
          title: Entity Id
        name:
          type: string
          title: Name
        display_name:
          type: string
          title: Display Name
        entity_type:
          type: string
          title: Entity Type
        domain_count:
          type: integer
          title: Domain Count
        domains:
          items:
            $ref: '#/components/schemas/DomainAttribution'
          type: array
          title: Domains
        relevance:
          type: number
          maximum: 1.0
          minimum: 0.0
          title: Relevance
        portfolio_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Portfolio Count
      type: object
      required:
      - entity_id
      - name
      - display_name
      - entity_type
      - domain_count
      - relevance
      title: EntityMatch
      description: "A single entity matching the search query.\n\nAttributes:\n    entity_id: UUID of the entity record.\n    name: Normalized canonical entity name.\n    display_name: Human-readable entity name (first alias or name).\n    entity_type: Entity classification (organization, person, unknown).\n    domain_count: Total number of associated domains.\n    domains: Top domains by confidence (capped at 10 in search results).\n    relevance: Search relevance score (1.0=exact, 0.8=prefix, 0.5=substring).\n    portfolio_count: Domain count from Reverse WHOIS preview (None when unavailable)."
    ApiResponse_PortfolioResponse_:
      properties:
        data:
          anyOf:
          - $ref: '#/components/schemas/PortfolioResponse'
          - type: 'null'
        error:
          anyOf:
          - $ref: '#/components/schemas/ErrorDetail'
          - type: 'null'
        meta:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Meta
      type: object
      title: ApiResponse[PortfolioResponse]
    EntitySearchResponse:
      properties:
        query:
          type: string
          title: Query
        total:
          type: integer
          title: Total
        entities:
          items:
            $ref: '#/components/schemas/EntityMatch'
          type: array
          title: Entities
        limit:
          type: integer
          title: Limit
        offset:
          type: integer
          title: Offset
        has_more:
          type: boolean
          title: Has More
      type: object
      required:
      - query
      - total
      - entities
      - limit
      - offset
      - has_more
      title: EntitySearchResponse
      description: "Paginated entity search results.\n\nAttributes:\n    query: Original search query string.\n    total: Total number of matching entities.\n    entities: List of matched entities with relevance and domains.\n    limit: Maximum results per page.\n    offset: Number of results skipped.\n    has_more: Whether more results exist beyond this page."
    PortfolioResponse:
      properties:
        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
        cache_expires_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Cache Expires At
      type: object
      required:
      - entity_name
      - portfolio_count
      - domains
      - cached
      title: PortfolioResponse
      description: "Response for the entity portfolio endpoint.\n\nContains the domains associated with an entity via Reverse WHOIS API,\ncapped at 50 results.\n\nAttributes:\n    entity_name: The queried entity name.\n    portfolio_count: Total domain count (may exceed len(domains) if > 50).\n    domains: List of domains (up to 50).\n    cached: Whether the result was served from cache.\n    cache_expires_at: ISO 8601 timestamp when cache entry expires, if cached."
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    DomainAttribution:
      properties:
        domain:
          type: string
          title: Domain
        domain_id:
          type: string
          title: Domain Id
        confidence:
          type: number
          maximum: 1.0
          minimum: 0.0
          title: Confidence
        signal_count:
          type: integer
          title: Signal Count
        last_seen:
          type: string
          title: Last Seen
      type: object
      required:
      - domain
      - domain_id
      - confidence
      - signal_count
      - last_seen
      title: DomainAttribution
      description: "A domain linked to an entity with attribution confidence.\n\nAttributes:\n    domain: Domain name (e.g., \"example.com\").\n    domain_id: UUID of the domain record.\n    confidence: Maximum attribution confidence for this entity-domain pair.\n    signal_count: Number of distinct signals linking entity to domain.\n    last_seen: ISO 8601 timestamp of the most recent signal."
    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."
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer