🚨NOTICE 🚨

Hoxhunt GraphQL API is still experimental. This feature is not covered by any SLA or deprecation policy and might be subject to backward-incompatible changes.


Why is Hoxhunt using GraphQL

We chose GraphQL as our API layer as it gives significant flexibility to our developers and to our partners. It enables user of the API to query a strongly typed API and get exactly the data and only the data is required for the task at hand.

About GraphQL

The GraphQL data query language is:

How do I use Hoxhunt GraphQL API?

First you need to aquire Auth token from your user settings page. This is referred as AUTH_TOKEN in examples below. After you’ve got your auth token, you can start querying the API. Let's do a simple example with Python and Curl on command-line.

Python

# An example to get the current user information using Hoxhunt API

import requests

headers = {"Authorization": "Authtoken AUTH_TOKEN"}
# A simple function to use requests.post to make the API call.
# Note the json= section.
def run_query(query, variables={}):
    request = requests.post(
        'https://api.hoxhunt.com/graphql-external',
        json={'query': query,
              'variables': variables},
        headers=headers)
    if request.status_code == 200:
        return request.json()
    else:
        raise Exception(
            "Query failed to run by returning code of {}. {}"
            .format(request.status_code, query))


# The GraphQL query defined as a multi-line string.
query = """
{
  currentUser {
    emails {
      address
    }
  }
}

"""

result = run_query(query)  # Execute the query
print(result)
# {'data': {'currentUser': {'emails': [{'address':
#  '[email protected]'}]}}}

Curl

curl https://api.hoxhunt.com/graphql-external \
-X POST \
-H "Authorization: Authtoken AUTH_TOKEN" \
-H "Content-Type: application/json" \
--data-binary \
'{"query":"{\n  currentUser {\n    emails {\n      address\n    }\n  }\n}\n","variables":null,"operationName":null}'

Example queries

Below we have example queries that might get you started building your integration. Use your preferred client to execute the actual queries.

Fetch first three threat observables and reporting users

List objects such as threat observables comes with powerful filter and sorting mechanisms:

{
  threatObservables(
    first: 3
    filter: { ip_exists: true, updatedAt_gt: "2019-01-23T12:20:05.991Z" }
    sort: updatedAt_DESC
  ) {
    updatedAt
    createdAt
    ip
    threat {
      reporterUser {
        emails {
          address
        }
      }
    }
  }
}