Getting Started with RiskIQ Community API

In order to use the RiskIQ Community API, you must have a RiskIQ Community account. Registration for accounts can be done by visiting our website https://community.riskiq.com. Once registered, you will need to verify your account by clicking the validation token sent to you in the email message. After confirming your account, simply visit your account settings page in order to retrieve your API key. Please note, API keys should be treated like passwords and should not be shared.

The RiskIQ Community API follows much of the best practices and guidelines for REST APIs. Each call below includes a JSON request and response example, as well as an example curl shell command to perform the request. A RiskIQ Community client is in production however you are free to use any client you wish.

To get started using the API from the command line, try these commands in your shell:

USERNAME="your@email.here"
KEY="API key from account settings"
curl -u $USERNAME:$KEY 'https://api.riskiq.net/pt/v2/dns/passive' -XGET -H "Content-Type: application/json" --data '{"query": "passivetotal.org"}'
# You can also pass an URL parameter with most GET queries that only take strings
curl -u $USERNAME:$KEY 'https://api.riskiq.net/pt/v2/dns/passive?query=passivetotal.org'

You will notice that the API takes HTTP basic authentication and requires that you send your request data in the form of JSON, specified with application/json.

import requests

username = 'your@email.here'
key = 'API key from account settings'
auth = (username, key)
base_url = 'https://api.riskiq.net/pt'


def passivetotal_get(path, query):
    url = base_url + path
    data = {'query': query}
    # Important: Specifying json= here instead of data= ensures that the
    # Content-Type header is application/json, which is necessary.
    response = requests.get(url, auth=auth, json=data)
    # This parses the response text as JSON and returns the data representation.
    return response.json()

pdns_results = passivetotal_get('/v2/dns/passive', 'riskiq.net')
for resolve in pdns_results['results']:
    print('Found resolution: {}'.format(resolve['resolve']))


# Alias get_dns_passive to a GET to /v2/dns/passive
from functools import partial
get_dns_passive = partial(passivetotal_get, '/v2/dns/passive')
pdns_results_example = get_dns_passive('example.org')

Following this template, you should be able to perform any request you like. Please note, that if the documentation specifies an input type of UUID, it should be a string in the format: 41e5fe94-e9f5-4009-9081-8b59054fae30 This would be the corresponding ID that you can use in other calls (for example, to delete artifacts you created).

RiskIQ reserves the right to disable any account deemed abusing our system. Abuse-related activity includes, but is not limited to sharing accounts, bulk registrations, abuse of API calls, suspicious/malicious query parameters and accessing restricted resources. Additionally, users are expected to follow our limiting practices as outlined in the HTTP responses.

The RiskIQ Community API uses conventional HTTP response codes to indicate success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information, and codes in the 5xx range indicate an error with our servers.