Association Endpoint

The Association endpoint allows you to create relationships between entities in the ThreatWinds platform.

Insert Association

This endpoint allows you to insert an association between two entities.

Note: This endpoint always creates an association-mode relation. For aggregation-mode relations, use nested associations within the POST /entity endpoint instead.

Endpoint

POST /api/ingest/v1/association

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 shouldn’t 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:

{
  "entityID": "string",
  "relatedEntityID": "string"
}

Parameters

Parameter	Type	Description
entityID	string	The ID of the source entity in the association
relatedEntityID	string	The ID of the target entity in the association

Note: You need to provide valid entities IDs that already exist in the system. Entity IDs in ThreatWinds follow the format [type]-[hash] where type is the entity type and hash is a deterministic hash of the entity’s main attribute. You can get entity IDs by first creating entities using the /entity endpoint and/or by querying entities through the Search API or Simple Search.

Security Group Requirement: Both entityID and relatedEntityID must share at least one security group. If the entities do not share a security group, the API returns a 403 Forbidden error.

Response

Success Response (202 Accepted)

{
  "message": "acknowledged"
}

Error Responses

Status Code	Description
400	Bad Request - Invalid input data
401	Unauthorized - Authentication failed
403	Forbidden - Insufficient permissions
500	Internal Server Error - Failed to create association

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
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 or related entity not found
500	Internal Server Error	Failed to create association

Example

curl -X POST "https://apis.threatwinds.com/api/ingest/v1/association" \
  -H "Content-Type: application/json" \
  -H "api-key: <YOUR_API_KEY>" \
  -H "api-secret: <YOUR_API_SECRET>" \
  -d '{
    "entityID": "ip-abc123",
    "relatedEntityID": "domain-xyz789"
  }'