Entity Retrieval

This API endpoint allows you to retrieve detailed information about a specific threat intelligence entity by its ID. If you don’t know the entity ID, you can use the Simple Search or Advanced Search endpoints to find entities based on various criteria.

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

Parameters

Headers

Parameter	Type	Required	Description
Authorization	string	Optional*	Bearer token from an active session.
api-key	string	Optional*	Your API key
api-secret	string	Optional*	Your API secret

Note: The user-id and groups headers are added automatically by the API gateway when required and should not be provided by the client.

Path Parameters

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

Note: Authentication is optional. Unauthenticated requests work with reduced quotas. For more details on authentication, see the Authentication documentation.

Request

To retrieve an entity by its ID, use a GET request:

curl -X 'GET' \
  'https://apis.threatwinds.com/api/search/v1/entity/5f35d2c4-5633-4b16-bbf0-5ca22ef8ea2e' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <YOUR_BEARER_TOKEN>'

Or using API key and secret:

curl -X 'GET' \
  'https://apis.threatwinds.com/api/search/v1/entity/5f35d2c4-5633-4b16-bbf0-5ca22ef8ea2e' \
  -H 'accept: application/json' \
  -H 'api-key: <YOUR_API_KEY>' \
  -H 'api-secret: <YOUR_API_SECRET>'

Response

A successful response will return a JSON object containing the entity details:

{
  "id": "5f35d2c4-5633-4b16-bbf0-5ca22ef8ea2e",
  "type": "ip",
  "@timestamp": "2023-06-15T10:00:00Z",
  "lastSeen": "2023-06-15T14:30:00Z",
  "reputation": 3,
  "bestReputation": 3,
  "worstReputation": -1,
  "accuracy": 3,
  "tags": ["dns", "google", "public"],
  "visibleBy": ["public"],
  "wellKnown": true,
  "attributes": {
    "ip": "8.8.8.8",
    "asn": 15169,
    "aso": "Google LLC",
    "country": "United States"
  }
}

The response includes all available information about the entity, including:

Field	Description
id	Unique identifier of the entity
type	Type of the entity (e.g., “ip”, “domain”, “hash”). For a comprehensive list of all possible entity types, see the Entity Types page
@timestamp	ISO 8601 timestamp of the entity first being created
reputation	Current reputation score (-3 to 3; negative is malicious, positive is benign)
bestReputation	Highest reputation score ever recorded for this entity
worstReputation	Lowest reputation score ever recorded for this entity
accuracy	Accuracy score (0-3; higher means more trustworthy sources)
lastSeen	ISO 8601 timestamp of the most recent update or sighting
tags	Array of tags associated with the entity
visibleBy	Array of visibility settings
wellKnown	Whether the entity is a well-known entity (e.g., public DNS servers, major search engines)
attributes	Object containing entity-specific attributes

For detailed information about the entity structure and attributes, see the Entity Mapping documentation.

Entity Relations

To retrieve the relations of an entity, you can use the related endpoint:

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

This endpoint accepts the same authentication parameters as the entity retrieval endpoint, plus additional query parameters:

Parameter	Type	Required	Description
limit	integer	No	Maximum number of relations to return. Default is 10, maximum is 1000
page	integer	No	Page number for pagination. Default is 1. Values ≤ 1 default to 1
sort	string	No	Field to sort relations by. Default is @timestamp.
order	string	No	Sort order, either “asc” (ascending) or “desc” (descending). Default is desc.
types	string	No	Filter relations by entity types (comma-separated list)

Example request:

curl -X 'GET' \
  'https://apis.threatwinds.com/api/search/v1/entity/5f35d2c4-5633-4b16-bbf0-5ca22ef8ea2e/relations?limit=10&types=domain,url' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <YOUR_BEARER_TOKEN>'

Response

A successful response will return a JSON object matching the standard Results structure:

{
  "pages": 1,
  "items": 1,
  "results": [
    {
      "id": "ip-abc123",
      "type": "ip",
      "lastSeen": "2023-06-15T14:30:00Z",
      "reputation": 3,
      "accuracy": 3,
      "tags": ["dns", "google", "public"],
      "visibleBy": ["public"],
      "wellKnown": true,
      "attributes": {
        "ip": "8.8.8.8"
      }
    }
  ],
  "aggregations": null
}

The response includes:

Field	Type	Description
pages	integer	Total number of pages available
items	integer	Total number of related entities
results	array	Array of related entity objects
aggregations	object	Always null for relations

Each related entity in the results array contains the same structure as the entity retrieval response, with fields such as id, type, attributes, reputation, accuracy, tags, visibleBy, wellKnown, and lastSeen.

See also: Entity Details (Analytics API) and Entity Relations for enriched analytics.

Note: Search results may include additional metadata fields (such as version, score, sort, or fields) that can be safely ignored.

Error Response Headers

Responses with status codes 400, 401, and 403 include the following custom headers:

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 request parameters or malformed JSON
401	Unauthorized	Missing or invalid authentication credentials
403	Forbidden	Authenticated user lacks permission for this operation
404	Not Found	Entity not found
500	Internal Server Error	Server-side error; please contact support if persistent