Entity Relations

This API endpoint provides relationship information about a specific threat intelligence entity in a graph format, showing how the entity is connected to other entities in the ThreatWinds platform.

Endpoint: https://apis.threatwinds.com/api/analytics/v1/entity/{id}/relations

Parameters

Headers

Header	Type	Required	Description
Authorization	string	Optional	Bearer token from an active session. Authentication is optional but improves rate limits.
api-key	string	Optional	API key. Authentication is optional but improves rate limits.
api-secret	string	Optional	API secret. Authentication is optional but improves rate limits.

Parameter	Type	Required	Description
id	string	Yes	The unique identifier of the entity you want to retrieve relations for

Query Parameters

Parameter	Type	Required	Description
limit	integer	No	Maximum number of related entities to return (default: 50, max: 100)
levels	integer	No	Number of relationship levels to include in the graph (default: 3, max: 5)

Note: Out-of-range limit and levels values are silently clamped to their respective defaults rather than rejected with a 400 error. Non-numeric or negative values are treated as missing parameters and fall back to defaults. Maximum values are clamped to limit=100 and levels=5.

Request

To get relations for a specific entity, use a GET request, for example:

curl -X 'GET' \
  'https://apis.threatwinds.com/api/analytics/v1/entity/ip-ad0c2ed9a0a9b23822e5907b0d009bcaf8f969db793cd1d94c40e17e0287c04b/relations?limit=10&levels=2' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <YOUR_BEARER_TOKEN>'

Or using API key and secret:

curl -X 'GET' \
  'https://apis.threatwinds.com/api/analytics/v1/entity/ip-ad0c2ed9a0a9b23822e5907b0d009bcaf8f969db793cd1d94c40e17e0287c04b/relations?limit=10&levels=2' \
  -H 'accept: application/json' \
  -H 'api-key: <YOUR_API_KEY>' \
  -H 'api-secret: <YOUR_API_SECRET>'

Response

A successful response returns a JSON object containing graph data with nodes and relations:

Field	Description
nodes	Array of entity objects representing the nodes in the graph. Each node includes id, type, @timestamp, bestReputation, worstReputation, lastSeen, reputation, accuracy, tags, visibleBy, wellKnown, and attributes (entity-specific attributes, keys vary by entity type). The value field within attributes can be any valid JSON type
relations	Array of relationship objects connecting the nodes. Each relation has a source and target entity ID

Example response for levels=2 (two hops from the target entity):

{
  "nodes": [
    {
      "id": "ip-ad0c2ed9a0a9b23822e5907b0d009bcaf8f969db793cd1d94c40e17e0287c04b",
      "type": "ip",
      "reputation": 3,
      "accuracy": 3,
      "wellKnown": true,
      "lastSeen": "2023-06-15T14:30:00Z",
      "tags": ["dns", "google", "public"],
      "visibleBy": ["public"],
      "attributes": { "ip": "8.8.8.8" }
    },
    {
      "id": "domain-b7c3e81a4f2d9c05e6a1f0d38b2c47e9a1b5c8d0f3e6a9c2b4d7f0e1",
      "type": "domain",
      "reputation": 3,
      "accuracy": 3,
      "wellKnown": false,
      "lastSeen": "2023-06-10T12:00:00Z",
      "tags": ["dns", "google"],
      "visibleBy": ["public"],
      "attributes": { "domain": "dns.google" }
    },
    {
      "id": "ip-3f8a1c6e9d2b4a70c5e8f1a3b6d9c2e4a7f0b3c8d1e5a9f2c4b6e0d8f3a",
      "type": "ip",
      "reputation": 2,
      "accuracy": 3,
      "wellKnown": false,
      "lastSeen": "2023-06-11T08:00:00Z",
      "tags": ["dns", "google"],
      "visibleBy": ["public"],
      "attributes": { "ip": "8.8.4.4" }
    }
  ],
  "relations": [
    {
      "source": "ip-ad0c2ed9a0a9b23822e5907b0d009bcaf8f969db793cd1d94c40e17e0287c04b",
      "target": "domain-b7c3e81a4f2d9c05e6a1f0d38b2c47e9a1b5c8d0f3e6a9c2b4d7f0e1"
    },
    {
      "source": "domain-b7c3e81a4f2d9c05e6a1f0d38b2c47e9a1b5c8d0f3e6a9c2b4d7f0e1",
      "target": "ip-3f8a1c6e9d2b4a70c5e8f1a3b6d9c2e4a7f0b3c8d1e5a9f2c4b6e0d8f3a"
    }
  ]
}

In this example the IP 8.8.8.8 is the target (hop 0). dns.google is one hop away (level 1). 8.8.4.4 is two hops away — it is connected to dns.google, not directly to the target. With levels=1 the 8.8.4.4 node and its edge would be absent.

Note: limit bounds how many relations are fetched per entity at each level, not the total node count. At level 1 it caps the target’s direct neighbors; at each further level it caps how many new neighbors are explored from each node added in the previous level. A highly connected graph therefore grows the result set quickly — keep levels low (the default is 3) when exploring.

Error Response Headers

For responses with error status codes, the following headers are included:

Header	Description
x-error	Human-readable error message describing what went wrong
x-error-id	Unique identifier for error tracking and support

Error Codes

Status Code	Description	Possible Cause
400	Bad Request	Invalid entity ID or invalid query parameters
401	Unauthorized	Invalid authentication credentials
404	Not Found	Entity ID does not exist — entity could not be found in the database
500	Internal Server Error	Server-side error; please contact support if persistent

Note: If the entity exists but has no relations, the response returns 200 with an empty graph containing only the root entity node.