Well-Known Endpoint

The Well-Known endpoint allows you to submit well-known entities that will never be evaluated with negative reputation.

Insert Well-Known Entity

This endpoint allows you to insert a well-known entity into the ThreatWinds platform.

Endpoint

POST /api/ingest/v1/well-known

Request Headers

Header	Description
Authorization	Bearer token for authentication (optional if using API key/secret)
api-key	Your API key (optional if using Authorization header)
api-secret	Your API secret (optional if using Authorization header)

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: trusted

This endpoint requires the trusted role, which allows users to submit well-known entities that are excluded from negative reputation evaluation.

Request Body

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

{
  "type": "string",
  "attributes": {
    "string": "string"
  }
}

Parameters

Parameter	Type	Description
type	string	The type of the entity (e.g., “ip”, “domain”, “url”). Required.
attributes	object	Attributes for the entity. Must include a key matching the entity type (e.g., an ip entity must have attributes.ip). More information about available attributes in Entity Types and Entity Mapping

Note: The main attribute key must match the entity type. For example, an IP entity must include attributes.ip with the IP address value.

Note: Well-known entities are automatically visible to the public (VisibleBy: ["public"]) with a reputation of 0 and wellKnown: true.

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 - Malformed user-id header value

Error Response Headers

For responses with status codes other than 200 and 202, the following headers are included:

Header	Description
x-error	Contains a description of the error that occurred
x-error-id	Contains a unique identifier for the error for 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
500	Internal Server Error	Malformed user-id header value

Example

curl -X POST "https://apis.threatwinds.com/api/ingest/v1/well-known" \
  -H "Content-Type: application/json" \
  -H "api-key: your-api-key" \
  -H "api-secret: your-api-secret" \
  -d '{
    "type": "ip",
    "attributes": {
      "ip": "8.8.8.8"
    }
  }'