GreyNoise Intelligence IP Lookup API

openapi: 3.0.0
info:
  title: GreyNoise Callback IP Lookup API
  version: 3.0.0
  description: GreyNoise is a cybersecurity company that collects and analyzes Internet-wide scan and attack traffic. Use GreyNoise to contextualize existing alerts, filter false-positives, identify compromised devices, and track emerging threats.
  contact:
    email: hello@greynoise.io
  license:
    name: Proprietary
    url: https://www.greynoise.io/terms
servers:
- url: https://api.greynoise.io
  description: Production
security:
- APIKeyHeaderAuth: []
tags:
- name: IP Lookup
  description: Calls to identify whether or not an IP address is noise, or get more information about a given IP address.
paths:
  /v3/ip:
    post:
      tags:
      - IP Lookup
      summary: IP Lookup - Multi
      operationId: V3MultiIP
      description: 'Retrieves information about the submitted set of IP addresses

        from the Internet Scanner and Business Service intelligence datasets

        (consolidated response based on subscription entitlements).

        Returns time ranges, IP metadata (network owner, ASN, reverse DNS pointer, country),

        associated actors, tags, raw port scan data, web request information,

        classification and/or trust level, and provider information.


        Use the `quick` parameter to return a subset of the response fields, for a faster response time.


        Can process up to 10,000 IPs per request.

        '
      requestBody:
        $ref: '#/components/requestBodies/MultiIpRequest'
      parameters:
      - in: query
        name: quick
        description: If true, the response will only include the IP address and the classification or trust level.
        required: false
        schema:
          type: boolean
          default: false
      - $ref: '#/components/parameters/workspaceLabels'
      responses:
        '200':
          description: OK - request successful.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/MultiIPResponseV3'
                - $ref: '#/components/schemas/QuickMultiIPResponseV3'
              examples:
                V3MultiIP200Example:
                  summary: Default V3MultiIP 200 response
                  x-microcks-default: true
                  value:
                    data:
                    - ip: 8.8.8.8
                      business_service_intelligence:
                        found: true
                        category: hosting
                        name: example.com
                        description: example.com
                        explanation: string
                        last_updated: '2025-01-15T12:30:45Z'
                        reference: https://example.com
                        trust_level: '1'
                      internet_scanner_intelligence:
                        ip: 71.6.135.131
                        seen: true
                        classification: benign
                        first_seen: '2018-01-28'
                        last_seen: '2018-02-28'
                        last_seen_timestamp: '2025-01-15T12:30:45Z'
                        found: true
                        actor: Shodan.io
                        spoofable: true
                        cves: &id001
                        - CVE-2020-1234
                        - CVE-2021-2345
                        tor: false
                        vpn: true
                        vpn_service: IPVANISH_VPN
                        metadata:
                          mobile: false
                          source_country: United States
                          source_country_code: US
                          source_city: Seattle
                          region: Seattle
                          organization: DigitalOcean, LLC
                          rdns: crawl-66-249-79-17.googlebot.com
                          asn: AS521
                          category: education
                          os: Windows 7/8
                          destination_countries: &id002
                          - string
                          destination_country_codes: &id003
                          - US
                          destination_cities: &id004
                          - string
                          destination_asns: &id005
                          - string
                          single_destination: true
                          carrier: AIS
                          datacenter: us-west-1
                          domain: example.com
                          rdns_parent: example.com
                          rdns_validated: true
                          latitude: 37.7749
                          longitude: -122.4194
                          sensor_count: 10
                          sensor_hits: 10
                        tags:
                          id: ef0cc90d-d80c-436f-92c5-3d8f8665c9ac
                          slug: mirai
                          name: Mirai
                          category: worm
                          intention: malicious
                          description: This IP address exhibits behavior that indicates it is infected with Mirai or a Mirai-like variant of malware.
                          references: &id006
                          - string
                          recommend_block: false
                          cves: &id007
                          - CVE-2021-44228
                          created_at: '2020-04-07'
                          updated_at: '2020-04-07'
                        raw_data:
                          scan:
                          - port: 80
                            protocol: TCP
                          ja3:
                          - fingerprint: c3a6cf0bf2e690ac8e1ecf6081f17a50
                            port: 443
                          hassh:
                          - fingerprint: 51cba57125523ce4b9db67714a90bf6e
                            port: 2222
                          http:
                            md5: 9764955b67107eeb9edfae76f429e783
                            cookie_keys: &id008
                            - expremotekey
                            request_authorization: &id009
                            - Bearer exampletoken
                            - Basic username:password
                            request_cookies: &id010
                            - session_id=1234567890
                            request_header: &id011
                            - 'Content-Type: application/json'
                            - 'Accept: application/json'
                            method: &id012
                            - GET
                            - POST
                            - PUT
                            - DELETE
                            request_origin: &id013
                            - 111.111.1.1
                            host: &id014
                            - example.com
                            - example.com:8080
                            uri: &id015
                            - string
                            path: &id016
                            - /HNAP1/
                            useragent: &id017
                            - Mozilla/5.0 (compatible; GoogleBot/2.1; +http://www.google.com/bot.html)
                            ja4h: &id018
                            - ge11cn060000_4e59edc1297a_4da5efaf0cbd
                          tls:
                            cipher: TLS_AES_128_GCM_SHA256
                            ja4: &id019
                            - t13d1516h2_8daaf6152771_02713d6af862
                          ssh:
                            key: &id020
                            - ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC1234567890
                            ja4ssh: &id021
                            - c76s76_c71s59_c0s0
                          tcp:
                            ja4t: &id022
                            - 64240_2-1-3-1-1-4_1460_8
                            ja4l: '1460_64'
                          source: string
                    request_metadata:
                      restricted_fields: &id023
                      - ip
                      - cve
                      - destination_cities
                      message: ok
                      ips_not_found: &id024
                      - string
        '206':
          description: 'Partial content - request partially successful.

            Due to plan limitations, your request only returned a subset of

            fields and/or data. Contact sales@greynoise.io to upgrade your

            plan and unlock full results.

            '
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/MultiIPResponseV3'
                - $ref: '#/components/schemas/QuickMultiIPResponseV3'
              examples:
                V3MultiIP206Example:
                  summary: Default V3MultiIP 206 response
                  x-microcks-default: true
                  value:
                    data:
                    - ip: 8.8.8.8
                      business_service_intelligence:
                        found: true
                        category: hosting
                        name: example.com
                        description: example.com
                        explanation: string
                        last_updated: '2025-01-15T12:30:45Z'
                        reference: https://example.com
                        trust_level: '1'
                      internet_scanner_intelligence:
                        ip: 71.6.135.131
                        seen: true
                        classification: benign
                        first_seen: '2018-01-28'
                        last_seen: '2018-02-28'
                        last_seen_timestamp: '2025-01-15T12:30:45Z'
                        found: true
                        actor: Shodan.io
                        spoofable: true
                        cves: *id001
                        tor: false
                        vpn: true
                        vpn_service: IPVANISH_VPN
                        metadata:
                          mobile: false
                          source_country: United States
                          source_country_code: US
                          source_city: Seattle
                          region: Seattle
                          organization: DigitalOcean, LLC
                          rdns: crawl-66-249-79-17.googlebot.com
                          asn: AS521
                          category: education
                          os: Windows 7/8
                          destination_countries: *id002
                          destination_country_codes: *id003
                          destination_cities: *id004
                          destination_asns: *id005
                          single_destination: true
                          carrier: AIS
                          datacenter: us-west-1
                          domain: example.com
                          rdns_parent: example.com
                          rdns_validated: true
                          latitude: 37.7749
                          longitude: -122.4194
                          sensor_count: 10
                          sensor_hits: 10
                        tags:
                          id: ef0cc90d-d80c-436f-92c5-3d8f8665c9ac
                          slug: mirai
                          name: Mirai
                          category: worm
                          intention: malicious
                          description: This IP address exhibits behavior that indicates it is infected with Mirai or a Mirai-like variant of malware.
                          references: *id006
                          recommend_block: false
                          cves: *id007
                          created_at: '2020-04-07'
                          updated_at: '2020-04-07'
                        raw_data:
                          scan:
                          - port: 80
                            protocol: TCP
                          ja3:
                          - fingerprint: c3a6cf0bf2e690ac8e1ecf6081f17a50
                            port: 443
                          hassh:
                          - fingerprint: 51cba57125523ce4b9db67714a90bf6e
                            port: 2222
                          http:
                            md5: 9764955b67107eeb9edfae76f429e783
                            cookie_keys: *id008
                            request_authorization: *id009
                            request_cookies: *id010
                            request_header: *id011
                            method: *id012
                            request_origin: *id013
                            host: *id014
                            uri: *id015
                            path: *id016
                            useragent: *id017
                            ja4h: *id018
                          tls:
                            cipher: TLS_AES_128_GCM_SHA256
                            ja4: *id019
                          ssh:
                            key: *id020
                            ja4ssh: *id021
                          tcp:
                            ja4t: *id022
                            ja4l: '1460_64'
                          source: string
                    request_metadata:
                      restricted_fields: *id023
                      message: ok
                      ips_not_found: *id024
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/ExceededLimit'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v3/ip/{ip}:
    get:
      tags:
      - IP Lookup
      summary: IP Lookup
      operationId: V3IP
      description: 'Get more information about a given IP address. Returns time ranges,

        IP metadata (network owner, ASN, reverse DNS pointer, country),

        associated actors, activity tags, and raw port scan and web

        request information.


        Use the `quick` parameter to return a subset of the response fields, for a faster response time.

        '
      parameters:
      - $ref: '#/components/parameters/ip'
      - in: query
        name: quick
        description: If true, the response will only include the IP address and the classification or trust level.
        required: false
        schema:
          type: boolean
          default: false
      - $ref: '#/components/parameters/workspaceLabels'
      responses:
        '200':
          description: OK - request successful.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/IPResponseV3'
                - $ref: '#/components/schemas/QuickIpProfile'
              examples:
                V3IP200Example:
                  summary: Default V3IP 200 response
                  x-microcks-default: true
                  value:
                    ip: 8.8.8.8
                    business_service_intelligence:
                      found: true
                      category: hosting
                      name: example.com
                      description: example.com
                      explanation: string
                      last_updated: '2025-01-15T12:30:45Z'
                      reference: https://example.com
                      trust_level: '1'
                    internet_scanner_intelligence:
                      ip: 71.6.135.131
                      seen: true
                      classification: benign
                      first_seen: '2018-01-28'
                      last_seen: '2018-02-28'
                      last_seen_timestamp: '2025-01-15T12:30:45Z'
                      found: true
                      actor: Shodan.io
                      spoofable: true
                      cves: &id025
                      - CVE-2020-1234
                      - CVE-2021-2345
                      tor: false
                      vpn: true
                      vpn_service: IPVANISH_VPN
                      metadata:
                        mobile: false
                        source_country: United States
                        source_country_code: US
                        source_city: Seattle
                        region: Seattle
                        organization: DigitalOcean, LLC
                        rdns: crawl-66-249-79-17.googlebot.com
                        asn: AS521
                        category: education
                        os: Windows 7/8
                        destination_countries: &id026
                        - string
                        destination_country_codes: &id027
                        - US
                        destination_cities: &id028
                        - string
                        destination_asns: &id029
                        - string
                        single_destination: true
                        carrier: AIS
                        datacenter: us-west-1
                        domain: example.com
                        rdns_parent: example.com
                        rdns_validated: true
                        latitude: 37.7749
                        longitude: -122.4194
                        sensor_count: 10
                        sensor_hits: 10
                      tags:
                        id: ef0cc90d-d80c-436f-92c5-3d8f8665c9ac
                        slug: mirai
                        name: Mirai
                        category: worm
                        intention: malicious
                        description: This IP address exhibits behavior that indicates it is infected with Mirai or a Mirai-like variant of malware.
                        references: &id030
                        - string
                        recommend_block: false
                        cves: &id031
                        - CVE-2021-44228
                        created_at: '2020-04-07'
                        updated_at: '2020-04-07'
                      raw_data:
                        scan:
                        - port: 80
                          protocol: TCP
                        ja3:
                        - fingerprint: c3a6cf0bf2e690ac8e1ecf6081f17a50
                          port: 443
                        hassh:
                        - fingerprint: 51cba57125523ce4b9db67714a90bf6e
                          port: 2222
                        http:
                          md5: 9764955b67107eeb9edfae76f429e783
                          cookie_keys: &id032
                          - expremotekey
                          request_authorization: &id033
                          - Bearer exampletoken
                          - Basic username:password
                          request_cookies: &id034
                          - session_id=1234567890
                          request_header: &id035
                          - 'Content-Type: application/json'
                          - 'Accept: application/json'
                          method: &id036
                          - GET
                          - POST
                          - PUT
                          - DELETE
                          request_origin: &id037
                          - 111.111.1.1
                          host: &id038
                          - example.com
                          - example.com:8080
                          uri: &id039
                          - string
                          path: &id040
                          - /HNAP1/
                          useragent: &id041
                          - Mozilla/5.0 (compatible; GoogleBot/2.1; +http://www.google.com/bot.html)
                          ja4h: &id042
                          - ge11cn060000_4e59edc1297a_4da5efaf0cbd
                        tls:
                          cipher: TLS_AES_128_GCM_SHA256
                          ja4: &id043
                          - t13d1516h2_8daaf6152771_02713d6af862
                        ssh:
                          key: &id044
                          - ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC1234567890
                          ja4ssh: &id045
                          - c76s76_c71s59_c0s0
                        tcp:
                          ja4t: &id046
                          - 64240_2-1-3-1-1-4_1460_8
                          ja4l: '1460_64'
                        source: string
                    request_metadata:
                      restricted_fields: &id047
                      - ip
                      - cve
                      - destination_cities
        '206':
          description: 'Partial content - request partially successful.

            Due to plan limitations, your request only returned a subset of

            fields and/or data. Contact sales@greynoise.io to upgrade your

            plan and unlock full results.

            '
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/IPResponseV3'
                - $ref: '#/components/schemas/QuickIpProfile'
              examples:
                V3IP206Example:
                  summary: Default V3IP 206 response
                  x-microcks-default: true
                  value:
                    ip: 8.8.8.8
                    business_service_intelligence:
                      found: true
                      category: hosting
                      name: example.com
                      description: example.com
                      explanation: string
                      last_updated: '2025-01-15T12:30:45Z'
                      reference: https://example.com
                      trust_level: '1'
                    internet_scanner_intelligence:
                      ip: 71.6.135.131
                      seen: true
                      classification: benign
                      first_seen: '2018-01-28'
                      last_seen: '2018-02-28'
                      last_seen_timestamp: '2025-01-15T12:30:45Z'
                      found: true
                      actor: Shodan.io
                      spoofable: true
                      cves: *id025
                      tor: false
                      vpn: true
                      vpn_service: IPVANISH_VPN
                      metadata:
                        mobile: false
                        source_country: United States
                        source_country_code: US
                        source_city: Seattle
                        region: Seattle
                        organization: DigitalOcean, LLC
                        rdns: crawl-66-249-79-17.googlebot.com
                        asn: AS521
                        category: education
                        os: Windows 7/8
                        destination_countries: *id026
                        destination_country_codes: *id027
                        destination_cities: *id028
                        destination_asns: *id029
                        single_destination: true
                        carrier: AIS
                        datacenter: us-west-1
                        domain: example.com
                        rdns_parent: example.com
                        rdns_validated: true
                        latitude: 37.7749
                        longitude: -122.4194
                        sensor_count: 10
                        sensor_hits: 10
                      tags:
                        id: ef0cc90d-d80c-436f-92c5-3d8f8665c9ac
                        slug: mirai
                        name: Mirai
                        category: worm
                        intention: malicious
                        description: This IP address exhibits behavior that indicates it is infected with Mirai or a Mirai-like variant of malware.
                        references: *id030
                        recommend_block: false
                        cves: *id031
                        created_at: '2020-04-07'
                        updated_at: '2020-04-07'
                      raw_data:
                        scan:
                        - port: 80
                          protocol: TCP
                        ja3:
                        - fingerprint: c3a6cf0bf2e690ac8e1ecf6081f17a50
                          port: 443
                        hassh:
                        - fingerprint: 51cba57125523ce4b9db67714a90bf6e
                          port: 2222
                        http:
                          md5: 9764955b67107eeb9edfae76f429e783
                          cookie_keys: *id032
                          request_authorization: *id033
                          request_cookies: *id034
                          request_header: *id035
                          method: *id036
                          request_origin: *id037
                          host: *id038
                          uri: *id039
                          path: *id040
                          useragent: *id041
                          ja4h: *id042
                        tls:
                          cipher: TLS_AES_128_GCM_SHA256
                          ja4: *id043
                        ssh:
                          key: *id044
                          ja4ssh: *id045
                        tcp:
                          ja4t: *id046
                          ja4l: '1460_64'
                        source: string
                    request_metadata:
                      restricted_fields: *id047
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/ExceededLimit'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    IpResponseMetadataV3:
      type: object
      properties:
        restricted_fields:
          type: array
          description: 'The fields that were restricted due to plan limitations.

            '
          example:
          - ip
          - cve
          - destination_cities
          items:
            type: string
        message:
          type: string
          example: ok
          description: A status message indicating if there were issues with the request
        ips_not_found:
          type: array
          description: 'The list of IPs not found

            '
          items:
            type: string
          example:
          - string
    IPResponseV3Tags:
      type: object
      properties:
        id:
          type: string
          example: ef0cc90d-d80c-436f-92c5-3d8f8665c9ac
          description: 'The unique identifier for the tag.

            '
        slug:
          type: string
          example: mirai
          description: 'The slugified version of the tag name.

            '
        name:
          type: string
          example: Mirai
          description: 'The human-readable name for the tag.

            '
        category:
          type: string
          example: worm
          description: 'Category of the IP address such as hosting or ISP.

            '
        intention:
          type: string
          example: malicious
          description: 'The intent of the tag, either suspicious, malicious, benign, or unknown.

            '
        description:
          type: string
          example: This IP address exhibits behavior that indicates it is infected with Mirai or a Mirai-like variant of malware.
          description: 'A detailed description of the tag, including the observed activity

            and any relevant context or details.

            '
        references:
          type: array
          items:
            type: string
            example: https://en.wikipedia.org/wiki/Mirai_(malware)
            description: 'A list of URLs or references that provide additional information

              about the tag and its associated activity.

              '
          example:
          - string
        recommend_block:
          type: boolean
          example: false
          description: 'A boolean value indicating whether the tag should be recommended

            for blocking or filtering purposes.

            '
        cves:
          type: array
          items:
            type: string
            example: CVE-2020-1234
            description: 'A list of CVEs associated with the tag.

              '
          example:
          - CVE-2021-44228
        created_at:
          type: string
          example: '2020-04-07'
          description: 'The date and time when the tag was created.

            '
        updated_at:
          type: string
          example: '2020-04-07'
          description: 'The date and time when the tag was last updated.

            '
    BusinessServiceIntelligence:
      properties:
        found:
          type: boolean
          description: 'Indicates if an IP is part of the RIOT dataset or not.

            '
          example: true
        category:
          type: string
          description: 'RIOT category the provider belongs to, identifying the type of service provided.

            '
          example: hosting
        name:
          type: string
          description: 'The name of the provider and/or service.

            '
          example: example.com
        description:
          type: string
          description: 'A description of the provider and what they do.

            '
          example: example.com
        explanation:
          type: string
          description: 'An explanation of the category type and what may be expected from this provider and category.

            '
          example: string
        last_updated:
          type: string
          description: 'Date and time when this record was last updated from its source (format: YYYY-MM-DDTHH:MM:SSZ).

            '
          example: '2025-01-15T12:30:45Z'
        reference:
          type: string
          description: 'Reference URL for information about this provider and/or service.

            '
          example: https://example.com
        trust_level:
          type: string
          description: "Trust level assigned to this IP/provider. One of:\n  - \"1\" — high trust; broadly used legitimate provider where end-user attribution is high.\n  - \"2\" — moderate trust; common business service infrastructure where end-user attribution is limited.\n  - \"3\" — label only; cloud compute or bulk hosting provider with no inherent trust signal.\n"
          example: '1'
    QuickInternetScannerIntelligence:
      type: object
      properties:
        found:
          type: boolean
          description: 'Indicates if the IP was observed scanning the GreyNoise sensor network. Also referred to as ''noise''.

            '
          example: false
        classification:
          type: string
          description: 'The classification of the IP address, either "benign", "malicious",

            or "unknown", based on the activity observed by GreyNoise.

            '
          enum:
          - benign
          - malicious
          - unknown
          example: benign
    MultiIPResponseV3:
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              ip:
                type: string
                example: 8.8.8.8
                description: IP address that the information is about.
              business_service_intelligence:
                $ref: '#/components/schemas/BusinessServiceIntelligence'
              internet_scanner_intelligence:
                $ref: '#/components/schemas/InternetScannerIntelligence'
        request_metadata:
          $ref: '#/components/schemas/IpResponseMetadataV3'
    IPResponseV3:
      type: object
      properties:
        ip:
          type: string
          example: 8.8.8.8
          description: 'IP address that the information is about.

            '
        business_service_intelligence:
          $ref: '#/components/schemas/BusinessServiceIntelligence'
        internet_scanner_intelligence:
          $ref: '#/components/schemas/InternetScannerIntelligence'
        request_metadata:
          type: object
      

# --- truncated at 32 KB (54 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/greynoise/refs/heads/main/openapi/greynoise-ip-lookup-api-openapi.yml