Ingest API
The Ingest API allows you to submit and manage threat intelligence data in the ThreatWinds platform. It provides endpoints for ingesting entities, associations between entities, comments, and scheduling scans for IPs or hostnames.
Overview
ThreatWinds Ingest API allows you to:
| Feature | Description |
|---|---|
| Entities | Submit new threat intelligence entities to the platform |
| Associations | Create associations between entities |
| Comments | Add comments to entities |
| Well-Known Entities | Mark entities as “well-known” (trusted) |
| Scans | Schedule scans for IPs or hostnames |
| Definitions | Retrieve entity definitions |
Authentication
Like all ThreatWinds APIs, the Ingest API requires authentication. You can authenticate using either:
| Authentication Method | Description |
|---|---|
| Authorization Header | Include a bearer token in the Authorization header |
| API Key and Secret | Include your API key and secret in the request headers |
For more details on authentication, see the Authentication section.
Authorization
Access to the Ingest API endpoints 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 each endpoint.
The available roles include:
| Role | Description |
|---|---|
| user | Standard user access |
| reporter | Access to reporting and data submission endpoints |
| trusted | Access to trusted or verified endpoints |
Role Requirements for Endpoints
| Endpoint | Method | Required Role |
|---|---|---|
/entity | POST | reporter |
/association | POST | reporter |
/comment | POST | reporter |
/well-known | POST | trusted |
/scan | POST | user |
/definitions | GET | reporter |
For more detailed information about each endpoint’s role requirements, please refer to the individual endpoint documentation pages.
API Endpoints
The base URL for the Ingest API is:
https://apis.threatwinds.com/api/ingest/v1
Available Endpoints
| Endpoint | Method | Description |
|---|---|---|
/entity | POST | Insert a new entity with associations |
/association | POST | Insert an association between entities |
/comment | POST | Add a comment to an entity |
/well-known | POST | Insert a well-known (trusted) entity |
/scan | POST | Schedule a scan for an IP or hostname |
/definitions | GET | Retrieve entity definitions |
For detailed information about each endpoint, please refer to the specific documentation pages.
Error Response Headers
All error responses include the following custom headers:
| Header | Description |
|---|---|
| x-error | Human-readable error message describing what went wrong |
| x-error-id | Unique MD5 hash identifier for error tracking and support |
Error Codes
| Status Code | Description | Possible Cause |
|---|---|---|
| 200 | OK | Definitions or scan status retrieved successfully |
| 202 | Accepted | Entity, association, or comment accepted for processing |
| 400 | Bad Request | Invalid request parameters, malformed JSON, or validation error |
| 401 | Unauthorized | Missing or invalid authentication credentials |
| 403 | Forbidden | User lacks required role (reporter, trusted) for operation |
| 404 | Not Found | Entity, association, or resource does not exist |
| 500 | Internal Server Error | Database error, pub/sub failure, or server-side error |