SecurityScorecard Search API

openapi: 3.2.0
info:
  title: ASI internal service Search API
  description: Attack surface intelligence service
  version: 0.0.1
servers:
- url: https://api.securityscorecard.io
security:
- Token: []
tags:
- name: Search
  description: Search endpoint
paths:
  /asi/facets:
    post:
      tags:
      - Search
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/asiFacetsRequest'
        required: true
      responses:
        '200':
          description: Facets elements
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/asiFacetsResponse'
      parameters: []
      summary: Attack Surface Intelligence API Facets
      operationId: postAsiFacets
      x-operation-id-source: derived
  /asi/search:
    post:
      tags:
      - Search
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/asiSearchRequest'
        required: true
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/asiSearchResponse'
      parameters: []
      summary: Attack Surface Intelligence API Search
      operationId: postAsiSearch
      x-operation-id-source: derived
components:
  schemas:
    asiSearchResponse:
      type: object
      additionalProperties: false
      properties:
        facets:
          type: object
          properties:
            countries:
              type: array
              items:
                type: object
                properties:
                  name:
                    type: string
                  value:
                    type: string
            threatActors:
              type: array
              items:
                type: object
                properties:
                  name:
                    type: string
                  value:
                    type: string
            cves:
              type: array
              items:
                type: object
                properties:
                  name:
                    type: string
                  value:
                    type: string
            ports:
              type: array
              items:
                type: object
                properties:
                  name:
                    type: string
                  value:
                    type: string
            products:
              type: array
              items:
                type: object
                properties:
                  name:
                    type: string
                  value:
                    type: string
            orgs:
              type: array
              items:
                type: object
                properties:
                  name:
                    type: string
                  value:
                    type: string
        hits:
          type: object
          properties:
            detectedLibraries:
              type: array
              description: Crawling detected libraries Name
              items:
                type: string
            time:
              type: string
              description: Scan time
            cloud:
              type: string
              description: Cloud service
            cloudRegion:
              type: string
              description: Cloud region
            hasMalrep:
              type: boolean
              description: has bad reputation
            maliciousReputation:
              type: array
              description: Malicious reputation
              items:
                type: string
            hasCVE:
              type: boolean
              description: has a CVE
            cves:
              type: array
              description: List of CVEs associated
              items:
                type: string
            maxCVSS:
              type: number
              description: Max CVSS in the CVEs
            cvss:
              type: array
              description: List of CVSS
              items:
                type: string
            deviceType:
              type: array
              description: Device Type
              items:
                type: string
            hasRansomware:
              type: boolean
              description: has ransomware
            ransomwareVictims:
              type: array
              description: Ransomware
              items:
                type: string
            ransomwareGroups:
              type: array
              description: Ransomware groups
              items:
                type: string
            hasSSLCert:
              type: boolean
              description: has a SSL certificate
            ports:
              type: array
              description: Open ports
              items:
                type: string
            services:
              type: array
              description: Services running
              items:
                type: string
            minGrade:
              type: string
              description: Minimum Scorecard Grade
            hostnames:
              type: array
              description: Hostnames associated with this IP
              items:
                type: string
            hasScorecard:
              type: boolean
              description: has a Scorecard associated
            products:
              type: array
              description: Products running on this host
              items:
                type: string
            country:
              type: string
              description: Country
            organizations:
              type: array
              description: Organizations associated to this IP
              items:
                type: string
            hasCVEExploited:
              type: boolean
              description: has a CVE exploited
            ips:
              type: array
              description: IPs associated to this host
              items:
                type: string
            sslValid:
              type: boolean
              description: SSL Certificate Chain is Valid
            hasThreatActor:
              type: boolean
              description: has a Threat Actor Campaign associated
            threatActors:
              type: array
              description: IPs associated to this host
              items:
                type: string
            hasInfection:
              type: boolean
              description: has a infection
            infections:
              type: array
              description: Active infections
              items:
                type: string
            countryCode:
              type: string
              description: Country Code
            industries:
              type: array
              description: Industries associated
              items:
                type: string
            cpe:
              type: string
              description: cpe
            dnsRecords:
              type: array
              description: Crawling DNS Records Types
              items:
                type: string
            grade:
              type: string
              description: Current Scorecard Grade
            mainAttribution:
              type: array
              description: Primary Attribution details
              items:
                type: string
            detectedLibraryVersion:
              type: string
              description: Crawling detected library version
            domains:
              type: array
              description: Attributed domains
              items:
                type: string
            osTypes:
              type: array
              description: Types of Operating Systems
              items:
                type: string
            id:
              type: string
              description: IP
        found:
          type: number
          description: Amount of documents found
        isError:
          type: boolean
          description: True if error, false otherwise
        errorType:
          type: string
          description: Type of error
        errorMessage:
          type: string
          description: Error message
        errorCode:
          type: number
          description: HTTP status code of error if error is True
        cursor:
          type: string
          description: Cursor identifier to paginate over more than 10K results
    asiFacetsRequest:
      type: object
      properties:
        names:
          type: array
          description: name of the facets to get values
          items:
            type: string
        index:
          type: string
          description: search index to query
          default: ipv4
        size:
          type: number
          description: number of elements per facet to return
      additionalProperties: false
    asiSearchRequest:
      type: object
      properties:
        query:
          type: string
          description: search query
        sort:
          type: string
          description: 'values for ipv4 are:'
          enum:
          - scan_date
          - max_cvss_score
          - min_scorecard_grade
          - _score
          - avd_grade
          - city
          - cloud_provider
          - cloud_region
          - country_name
          - has_cve
          - has_cve_been_exploited
          - has_infection
          - has_malhash
          - has_malrep
          - has_ransomware
          - has_scorecard
          - has_screenshot
          - has_ssl_cert
          - has_threatactor
          - hostname
          - max_cvss_score
          - min_scorecard_grade
          - postal
          - scan_time
          - ssl_is_certificate_chain_valid
          - state
          - _score
          - has_ransomware
        sortDir:
          type: string
          description: asc or desc
          enum:
          - asc
          - desc
          x-enumDescriptions:
            asc: Ascending
            desc: Descending
        page:
          type: number
          default: 0
          example: 0
          description: Search result page number
        index:
          type: string
          default: ipv4
          example: ipv4
          description: Search index to query
        parser:
          type: string
          default: structured
          example: ipv4
          description: 'Search query parser. Options are: simple, structured, lucence, dismax'
          enum:
          - simple
          - structured
          - lucence
          - dismax
        size:
          type: number
          default: 10
          example: 10
          description: Size of the search resultset page
        cursor:
          type: string
          description: Cursor identifier (or "initial" for first request) needed to paginate over more than 10K results
      additionalProperties: false
    asiFacetsResponse:
      type: object
      additionalProperties: false
      properties:
        facets:
          type: object
          properties: {}
          additionalProperties: true
  securitySchemes:
    Token:
      type: apiKey
      in: header
      name: Authorization
      description: "SecurityScorecard API endpoints require an authentication token to be passed\nin an authorization header in order to return data. If you do not already\nhave a token, you can create one by going to the API Access area in your\n[Settings page](https://platform.securityscorecard.io/#/settings/api) and then\nclicking Generate New Token. Please note this tokens have no expiration\nso they can be used until manually revoked. If you have a token and generate\na new one, the previous token will be revoked and can no longer be used.\n\nAdministrators can also revoke API tokens for any user in their account.\n\nOnce you have your token you can pass it in using the `Authorization` http header like this:\n\n```\ncurl -X GET \\\n  https://api.securityscorecard.io/portfolios \\\n  -H 'authorization: Token <your token>'\n```\n"
x-provenance:
  method: searched
  source: https://securityscorecard.readme.io/reference
  harvested: '2026-10-14'
  tool: harvest-readme-openapi.py
  note: Assembled verbatim from the OpenAPI definition ReadMe embeds in each operation page of the provider's developer portal; paths and components merged by API title, nothing authored.
  assembled_from:
  - https://securityscorecard.readme.io/reference/get_asi-details-active-infections-family.md
  - https://securityscorecard.readme.io/reference/get_asi-details-asset-asset-port-port.md
  - https://securityscorecard.readme.io/reference/get_asi-details-asset-ip.md
  - https://securityscorecard.readme.io/reference/get_asi-details-cve-cve.md
  - https://securityscorecard.readme.io/reference/get_asi-details-cve-domain-domain.md
  - https://securityscorecard.readme.io/reference/get_asi-details-ransomware-ransomware.md
  - https://securityscorecard.readme.io/reference/get_asi-details-threat-actor-threatactor.md
  - https://securityscorecard.readme.io/reference/post_asi-facets.md
  - https://securityscorecard.readme.io/reference/post_asi-search.md
  merge:
    pages: 9
    deduped: 8
    conflicts_kept_first: 0