Entity Lookup

This API endpoint allows you to retrieve a threat intelligence entity by specifying its type and value, rather than its ID.

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

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 shouldn’t be provided by the client.

Request Body

The request body is required and must contain a JSON object with the following fields:

Property	Type	Required	Description
type	string	Yes	The entity type (e.g., “ip”, “domain”)
value	any	Yes	The entity value (string or number)

Note: Authentication is optional. Unauthenticated requests work with reduced quotas.

Request

To retrieve an entity by its type and value, use a POST request with a JSON body containing the entity details:

curl -X 'POST' \
  'https://apis.threatwinds.com/api/search/v1/entity' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <YOUR_BEARER_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "type": "ip",
  "value": "8.8.8.8"
}'

The request body parameters include:

Parameter	Type	Required	Description
type	string	Yes	The type of entity (e.g., “ip”, “domain”, “hash”, etc.). See Entity Types for all supported types
value	any	Yes	The value to look up. Must match the declared type format (e.g., valid IP for type “ip”). Mismatch returns 400 “validation error”

Response

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

{
  "id": "ip-abc123",
  "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. Entity IDs follow a [type]-[hash] format. See Entity Types for details.
type	Type of the entity (e.g., “ip”, “domain”, “hash”)
@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
attributes	Object containing entity-specific attributes

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