🚨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:

A specification. The spec determines the validity of the schema on the API server. The schema determines the validity of client calls.
Strongly typed. The schema defines an API's type system and all object relationships.
Introspective. A client can query the schema for details about the schema.
Hierarchical. The shape of a GraphQL call mirrors the shape of the JSON data it returns. Nested fields let you query for and receive only the data you specify in a single round trip.
An application layer. GraphQL is not a storage model or a database query language. The graph refers to graph structures defined in the schema, where nodes define objects and edges define relationships between objects. The API traverses and returns application data based on the schema definitions, independent of how the data is stored.

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:

We query first 3 matches
We filter that threat observables must be of ip type (ip exists)
We filter threats that has been updated or created after certain date (maybe last query)
We sort them to be in descending order based on updatedAt field

{
  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
        }
      }
    }
  }
}