Simple Search

This API endpoint allows you to search for threat intelligence entities using a simple query language. It’s designed for straightforward searches where you want to find entities matching specific criteria without constructing complex queries. For more sophisticated search capabilities, see the Advanced Search documentation.

Endpoint: https://apis.threatwinds.com/api/search/v1/entities/simple

Parameters

Headers

Header	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.

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

Query Parameters

Parameter	Type	Required	Description
limit	integer	No	Maximum number of results 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 results by. Default is @timestamp
order	string	No	Sort order, either “asc” (ascending) or “desc” (descending). Default is desc

Request Body

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

Field	Type	Required	Description
query	string	Yes	The search term (IP, domain, hash, etc.)
accuracy	integer	No	Exact accuracy level to filter by (0 to 3)
reputation	integer	No	Exact reputation score to filter by (-3 to 3)
source	object	No	Fields to include or exclude in the response. Contains includes and excludes sub-fields

Request

To search for entities, use a POST request with a JSON body containing your search parameters:

curl -X 'POST' \
  'https://apis.threatwinds.com/api/search/v1/entities/simple?limit=10&page=1' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <YOUR_BEARER_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
  "query": "8.8.8.8",
  "accuracy": 1,
  "reputation": -2,
  "source": {
    "includes": ["id", "type", "attributes.value", "reputation", "accuracy"],
    "excludes": []
  }
}'

The request body parameters include:

Parameter	Type	Required	Description
query	string	Yes	The search term (for example, an IP address, domain, hash, etc.). For a comprehensive list of all possible entity types, see the Entity Types page. For all searchable fields, see Entity Mapping. The query is sanitized to allow only alphanumeric characters and dots; all other characters are replaced with spaces.
accuracy	integer	No	Exact accuracy level to filter by (0 to 3)
reputation	integer	No	Exact reputation score to filter by (-3 to 3)
source	object	No	Fields to include or exclude in the response. See the includes and excludes sub-fields below.

Note: Query sanitization replaces any character that is not alphanumeric or a dot (.) with a space.

Response

A successful response will return a JSON object containing the search results:

{
  "items": 1,
  "pages": 1,
  "results": [
    {
      "id": "5f35d2c4-5633-4b16-bbf0-5ca22ef8ea2e",
      "type": "ip",
      "attributes": {
        "ip": "8.8.8.8"
      },
      "reputation": 3,
      "accuracy": 3
    }
  ],
  "aggregations": null
}

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

Response Structure

Field	Type	Description
items	integer	Total number of items matching the query
pages	integer	Total number of pages available
results	array	Array of entities matching the search criteria
aggregations	object	Always null for simple search (aggregations are not supported)

Entity Object Structure

Each entity in the “results” array contains:

Field	Type	Description
id	string	Unique identifier for the entity
type	string	Type of the entity (ip, domain, hash, etc.)
attributes	object	Entity-specific attributes (varies by type)
reputation	integer	Reputation score (-3 to 3, where -3 is malicious and 3 is benign)
accuracy	integer	Accuracy level (0 to 3, where 3 is highest confidence)
tags	array	Optional array of tags associated with the entity
visibleBy	array	Array of visibility settings
wellKnown	boolean	Whether the entity is a well-known entity

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
404	Not Found	No results found matching your query criteria
500	Internal Server Error	Server-side error; please contact support if persistent