Entity Endpoints

The Entity endpoints allow you to submit and manage threat intelligence entities in the ThreatWinds platform.

Insert Entity

This endpoint allows you to insert a new entity with optional associations.

Endpoint

POST /api/ingest/v1/entity

Request Headers

Header	Description
`Authorization`	Bearer token from an active session.
`api-key`	API key.
`api-secret`	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.

Required Roles

Access to this endpoint is controlled by role-based permissions defined in the gateway. Users must have at least one of the required roles assigned to their account to access this endpoint.

Required role: reporter

This endpoint requires the reporter role, which allows users to submit threat intelligence data to the platform.

Request Body

The request body should be a JSON object with the following structure:

{
  "type": "string",
  "attributes": {
    "...": "...",
    "...": "..."
  },
  "associations": [
    {
      "mode": "string",
      "type": "string",
      "attributes": {
        "...": "...",
        "...": "..."
      },
      "associations": [
        {
          "mode": "string",
          "type": "string",
          "attributes": {
            "...": "...",
            "...": "..."
          },
          "associations": []
        }
      ]
    }
  ],
  "reputation": 0,
  "correlate": ["string"],
  "tags": ["string"],
  "visibleBy": ["string"]
}

Parameters

Parameter	Type	Description
`type`	string	The type of the entity (e.g., “ip”, “domain”, “url”)
`attributes`	object	Attributes for the entity. Must include a key matching the entity type. More information about available attributes in Entity Types and Entity Mapping
`associations`	array	Optional associations with other entities (see Association Modes below)
`reputation`	integer	Reputation score for the entity (range: -3 to 3, where negative is malicious, 0 is neutral, positive is benign)
`correlate`	array	Optional list of attribute names to create linked child entities from. When specified, each matching attribute value becomes a separate entity with inherited reputation, associations, tags, and `visibleBy`, connected to the parent via an `aggregation` relation. Use `type` values from the “Get Definitions” section on this page. The parent’s type is excluded automatically.
`tags`	array	Optional tags to categorize the entity
`visibleBy`	array	Optional list of groups that can see the entity (defaults to user’s groups if not provided)

Note: The main attribute must exist, and its key is the same as the type of the entity. For example, an IP entity with the value “203.0.113.1” must have a field “attributes.ip” with the value “203.0.113.1” otherwise the request returns error code 400.

Association Modes

When creating associations between entities, you can specify the mode of the association. The mode defines the type of relationship between the entities. The following modes are supported:

Mode	Description
`aggregation`	Indicates that the associated entity is a component or part of the main entity. This is used when one entity contains or is composed of other entities. For example, a file entity might have an aggregation association with a malware entity to indicate that the file contains malware.
`association`	Indicates a general relationship between two entities without implying containment or composition. This is used for looser connections between entities. For example, an IP address might have an association with a domain name to indicate that the domain resolves to that IP.

Note: If an invalid mode is provided, the API silently defaults to association.

Note: Both the parent entity and any associated entity must share at least one security group, otherwise a 403 Forbidden response is returned.

Response

Success Response (202 Accepted)

{
  "message": "acknowledged"
}

Error Responses

Status Code	Description
400	Bad Request - Invalid input data
401	Unauthorized - Authentication failed
403	Forbidden - `visibleBy` group validation failure or insufficient permissions
500	Internal Server Error - Malformed `user-id` header value

Note: When creating an entity of type ip, domain, or hostname, a background scan is automatically triggered on a best-effort basis.

Example

curl -X POST "https://apis.threatwinds.com/api/ingest/v1/entity" \
  -H "Content-Type: application/json" \
  -H "api-key: <YOUR_API_KEY>" \
  -H "api-secret: <YOUR_API_SECRET>" \
  -d '{
    "type": "ip",
    "attributes": {
      "ip": "203.0.113.1",
      "text": "manual",
      "value": "high"
    },
    "reputation": -1,
    "tags": ["malicious", "scanner"],
    "visibleBy": ["group1", "group2"]
  }'

Get Definitions

This endpoint returns entity definitions.

Endpoint

GET /api/ingest/v1/definitions

Request Headers

Header	Description
`Authorization`	Bearer token from an active session.
`api-key`	API key.
`api-secret`	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.

Required Roles

Access to this endpoint is controlled by role-based permissions defined in the gateway. Users must have at least one of the required roles assigned to their account to access this endpoint.

Required role: reporter

This endpoint requires the reporter role, which allows access to ingest endpoints.

Response

Success Response (200 OK)

Returns a JSON array of entity definitions. Each definition may include the following fields:

[
  {
    "type": "file",
    "description": "An object identifying a file, the value can be a UUID, a deterministic hash, or a message digest",
    "dataType": "UUID|Message Digest|Deterministic Hash",
    "example": {
      "type": "file",
      "attributes": {
        "file": "21a1610ce915d5d5a8ab5b1f5b6d6715cf4f4e3bc0c868352a175279b1881afe",
        "md5": "fb92636db83298a4215a2f5ffa2527b1",
        "sha1": "93a8f022b553f786bf077ff55616350727f8764a",
        "sha256": "202492bdd391deac6c1e72eba9d039a7c60bcc61f1afa0d85269d8c4c5af1284",
        "sha3-256": "21a1610ce915d5d5a8ab5b1f5b6d6715cf4f4e3bc0c868352a175279b1881afe"
      },
      "associations": [
        {
          "mode": "aggregation",
          "type": "malware",
          "attributes": {
            "malware": "pdf dropper agent",
            "malware-family": "pdf",
            "malware-type": "dropper"
          },
          "reputation": -3
        }
      ],
      "reputation": -3,
      "tags": ["malware", "common-file"],
      "correlate": ["md5", "sha1", "sha256", "sha3-256"]
    },
    "attributes": [
      {
        "type": "md5",
        "description": "A 128-bit fingerprint",
        "dataType": "Deterministic Hash",
        "label": "128-bit Hash"
      },
      {
        "type": "sha1",
        "description": "A 160-bit fingerprint",
        "dataType": "SHA-1",
        "label": "SHA-1"
      }
    ],
    "associations": [
      {
        "type": "filename",
        "description": "A filename or email attachment name",
        "dataType": "String",
        "label": "File Name"
      }
    ],
    "tags": ["malware", "common-file", "system-file"],
    "correlate": ["md5", "sha1", "sha256", "sha3-256", "file-data"],
    "label": "File"
  },
  {
    "type": "ip",
    "description": "An unique numerical identifier assigned to every device connected to a network that uses the internet protocol",
    "dataType": "IP",
    "attributes": [
      {
        "type": "subnet",
        "description": "A public network segment",
        "dataType": "CIDR"
      }
    ],
    "label": "IP"
  }
]

Response Fields

Field	Type	Description
`type`	string	The entity type identifier (e.g., “file”, “ip”, “domain”, “malware”)
`description`	string	A human-readable description of what the entity type represents
`dataType`	string	The data type constraint for the entity’s main attribute (e.g., “IP”, “FQDN”, “Deterministic Hash”, “UUID”, “String”)
`example`	object	Optional example entity instantiation showing how to construct entities of this type, including attributes, associations, reputation, tags, and correlate
`attributes`	array	Optional array of nested definition objects describing sub-attributes specific to this entity type
`associations`	array	Optional array of definition objects describing associated entity types that can be linked via aggregation mode
`tags`	array	Optional array of predefined tag strings commonly used with this entity type
`correlate`	array	Optional array of attribute type names that will be auto-correlated into linked child entities
`label`	string	Optional display label for the entity type (e.g., “IP”, “File”, “Malware Name”)

Note: Both attributes[] and associations[] child definitions can recursively define their own attributes, associations, labels, and dataTypes — there is no depth limit to this nesting.

Example

curl -X GET "https://apis.threatwinds.com/api/ingest/v1/definitions" \
  -H "api-key: <YOUR_API_KEY>" \
  -H "api-secret: <YOUR_API_SECRET>"

Error Response Headers

For responses with status codes other than 200 and 202, 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
401	Unauthorized	Missing or invalid authentication credentials
403	Forbidden	Insufficient permissions, or `visibleBy` contains groups the user is not a member of
404	Not Found	The requested resource does not exist
500	Internal Server Error	Server-side error; please contact support if persistent