GreyNoise Intelligence IP Lookup API

openapi: 3.2.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:
                        - 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:
                          - string
                          destination_country_codes:
                          - US
                          destination_cities:
                          - string
                          destination_asns:
                          - 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:
                          - string
                          recommend_block: false
                          cves:
                          - 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:
                            - expremotekey
                            request_authorization:
                            - Bearer exampletoken
                            - Basic username:password
                            request_cookies:
                            - session_id=1234567890
                            request_header:
                            - 'Content-Type: application/json'
                            - 'Accept: application/json'
                            method:
                            - GET
                            - POST
                            - PUT
                            - DELETE
                            request_origin:
                            - 111.111.1.1
                            host:
                            - example.com
                            - example.com:8080
                            uri:
                            - string
                            path:
                            - /HNAP1/
                            useragent:
                            - Mozilla/5.0 (compatible; GoogleBot/2.1; +http://www.google.com/bot.html)
                            ja4h:
                            - ge11cn060000_4e59edc1297a_4da5efaf0cbd
                          tls:
                            cipher: TLS_AES_128_GCM_SHA256
                            ja4:
                            - t13d1516h2_8daaf6152771_02713d6af862
                          ssh:
                            key:
                            - ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC1234567890
                            ja4ssh:
                            - c76s76_c71s59_c0s0
                          tcp:
                            ja4t:
                            - 64240_2-1-3-1-1-4_1460_8
                            ja4l: '1460_64'
                          source: string
                    request_metadata:
                      restricted_fields:
                      - ip
                      - cve
                      - destination_cities
                      message: ok
                      ips_not_found:
                      - 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:
                        - 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:
                          - string
                          destination_country_codes:
                          - US
                          destination_cities:
                          - string
                          destination_asns:
                          - 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:
                          - string
                          recommend_block: false
                          cves:
                          - 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:
                            - expremotekey
                            request_authorization:
                            - Bearer exampletoken
                            - Basic username:password
                            request_cookies:
                            - session_id=1234567890
                            request_header:
                            - 'Content-Type: application/json'
                            - 'Accept: application/json'
                            method:
                            - GET
                            - POST
                            - PUT
                            - DELETE
                            request_origin:
                            - 111.111.1.1
                            host:
                            - example.com
                            - example.com:8080
                            uri:
                            - string
                            path:
                            - /HNAP1/
                            useragent:
                            - Mozilla/5.0 (compatible; GoogleBot/2.1; +http://www.google.com/bot.html)
                            ja4h:
                            - ge11cn060000_4e59edc1297a_4da5efaf0cbd
                          tls:
                            cipher: TLS_AES_128_GCM_SHA256
                            ja4:
                            - t13d1516h2_8daaf6152771_02713d6af862
                          ssh:
                            key:
                            - ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC1234567890
                            ja4ssh:
                            - c76s76_c71s59_c0s0
                          tcp:
                            ja4t:
                            - 64240_2-1-3-1-1-4_1460_8
                            ja4l: '1460_64'
                          source: string
                    request_metadata:
                      restricted_fields:
                      - ip
                      - cve
                      - destination_cities
                      message: ok
                      ips_not_found:
                      - string
        '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:
                      - 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:
                        - string
                        destination_country_codes:
                        - US
                        destination_cities:
                        - string
                        destination_asns:
                        - 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:
                        - string
                        recommend_block: false
                        cves:
                        - 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:
                          - expremotekey
                          request_authorization:
                          - Bearer exampletoken
                          - Basic username:password
                          request_cookies:
                          - session_id=1234567890
                          request_header:
                          - 'Content-Type: application/json'
                          - 'Accept: application/json'
                          method:
                          - GET
                          - POST
                          - PUT
                          - DELETE
                          request_origin:
                          - 111.111.1.1
                          host:
                          - example.com
                          - example.com:8080
                          uri:
                          - string
                          path:
                          - /HNAP1/
                          useragent:
                          - Mozilla/5.0 (compatible; GoogleBot/2.1; +http://www.google.com/bot.html)
                          ja4h:
                          - ge11cn060000_4e59edc1297a_4da5efaf0cbd
                        tls:
                          cipher: TLS_AES_128_GCM_SHA256
                          ja4:
                          - t13d1516h2_8daaf6152771_02713d6af862
                        ssh:
                          key:
                          - ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC1234567890
                          ja4ssh:
                          - c76s76_c71s59_c0s0
                        tcp:
                          ja4t:
                          - 64240_2-1-3-1-1-4_1460_8
                          ja4l: '1460_64'
                        source: string
                    request_metadata:
                      restricted_fields:
                      - 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:
                      - 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:
                        - string
                        destination_country_codes:
                        - US
                        destination_cities:
                        - string
                        destination_asns:
                        - 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:
                        - string
                        recommend_block: false
                        cves:
                        - 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:
                          - expremotekey
                          request_authorization:
                          - Bearer exampletoken
                          - Basic username:password
                          request_cookies:
                          - session_id=1234567890
                          request_header:
                          - 'Content-Type: application/json'
                          - 'Accept: application/json'
                          method:
                          - GET
                          - POST
                          - PUT
                          - DELETE
                          request_origin:
                          - 111.111.1.1
                          host:
                          - example.com
                          - example.com:8080
                          uri:
                          - string
                          path:
                          - /HNAP1/
                          useragent:
                          - Mozilla/5.0 (compatible; GoogleBot/2.1; +http://www.google.com/bot.html)
                          ja4h:
                          - ge11cn060000_4e59edc1297a_4da5efaf0cbd
                        tls:
                          cipher: TLS_AES_128_GCM_SHA256
                          ja4:
                          - t13d1516h2_8daaf6152771_02713d6af862
                        ssh:
                          key:
                          - ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC1234567890
                          ja4ssh:
                          - c76s76_c71s59_c0s0
                        tcp:
                          ja4t:
                          - 64240_2-1-3-1-1-4_1460_8
                          ja4l: '1460_64'
                        source: string
                    request_metadata:
                      restricted_fields:
                      - ip
                      - cve
                      - destination_cities
        '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:
  parameters:
    ip:
      name: ip
      in: path
      description: IP address to query
      required: true
      schema:
        type: string
      example: 8.8.8.8
    workspaceLabels:
      name: workspace_labels
      in: query
      description: "Comma-separated list of dataset scopes to include in the query.\nWhen omitted, only the default GreyNoise global dataset is queried.\n\nAllowed values:\n- `greynoise`: GreyNoise's global dataset.\n- `community`: Aggregated community-contributed data.\n- `personal`: The authenticated caller's own workspace data.\n  Requires an authenticated workspace.\n\nEnforcement varies by endpoint; see each operation's response codes:\n- `GET /v3/ip/{ip}` and `POST /v3/ip` return `403 Forbidden` when any\n  value is supplied without the Community Dataset entitlement. Values\n  are not validated server-side; unrecognized values yield empty\n  results rather than an error.\n- `GET /v3/noise/ips/{ip}/timeline` returns `400 Bad Request` for\n  unrecognized values and for `personal` without an authenticated\n  workspace. The Community Dataset entitlement is not enforced on\n  this endpoint.\n"
      required: false
      schema:
        type: string
        example: greynoise,community
      example: string
  responses:
    BadRequest:
      description: 'Bad request - request syntax is invalid for the specified endpoint.

        Verify request syntax and try again.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: Invalid parameter
    Forbidden:
      description: 'Forbidden - request is not authorized due to an invalid API key or plan limitations.

        If due to plan limitations, contact sales@greynoise.io to upgrade your plan and unlock full results.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: Forbidden
    Unauthorized:
      description: Unauthorized. Please check your API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: Unauthorized
    ExceededLimit:
      description: Too many requests. You've hit the rate-limit.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: You've hit the rate limit for this endpoint.
  schemas:
    QuickMultiIPResponseV3:
      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/QuickBusinessServiceIntelligence'
              internet_scanner_intelligence:
                $ref: '#/components/schemas/QuickInternetScannerIntelligence'
        request_metadata:
          $ref: '#/components/schemas/IpResponseMetadataV3'
    Error:
      type: object
      properties:
        message:
          type: string
          example: Success
      required:
      - message
    QuickIpProfile:
      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/QuickBusinessServiceIntelligence'
        internet_scanner_intelligence:
          $ref: '#/components/schemas/QuickInternetScannerIntelligence'
    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 r

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