Scan Endpoint

The Scan endpoint allows you to schedule and manage scans for IPs or hostnames in the ThreatWinds platform.

Schedule a Scan

This endpoint allows you to schedule a scan for an IP address or hostname.

Endpoint

POST /api/ingest/v1/scan

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

This endpoint requires the user 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:

{
  "target": "string",
  "webhook": {
    "url": "string",
    "headers": [
      {
        "key": "string",
        "value": "string"
      }
    ]
  }
}

Parameters

Parameter	Type	Description
target	string	(required) The IP address or hostname to scan (must be a valid IP or FQDN)
webhook	object	Optional webhook configuration for scan completion notifications
webhook.url	string	URL to call when the scan is complete
webhook.headers	array	Optional headers to include in the webhook request

Task Deduplication: Submitting the same target from the same user will return the existing scan task rather than creating a duplicate.

Webhook URL Validation: If a webhook URL is provided and is not a valid URL, the API returns a 400 Bad Request error.

Response

Success Response (200 OK or 202 Accepted)

{
  "id": "unique-task-id",
  "status": "new"
}

The API returns different status codes based on the task status:

• 202 Accepted: when a new scan task is created (status: “new”)
• 200 OK: when returning an existing scan task (status: “queued”, “running”, “done”, or “permanent_failure”)

Note: Scans submitted directly via this endpoint run at higher priority than scans triggered automatically by entity ingestion.

Error Responses

Status Code	Description
400	Bad Request - Invalid input data
401	Unauthorized - Authentication failed
403	Forbidden - Insufficient permissions
500	Internal Server Error - Publish or stream failure

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
500	Internal Server Error	Publish or stream failure

Async Processing: Scans run asynchronously in the background. The endpoint returns a task ID immediately. Use the Simple Search or Advanced Search API to query for generated entities and associations once a scan completes.

Scan Retry Behavior: Stuck scan tasks (stuck in running state for 4+ hours) are automatically retried up to 2 times. After exhausting retries, a task is marked as permanent_failure. Task TTL is 168 hours (7 days), after which the task is cleaned up by the datastore.

Example

curl -X POST "https://apis.threatwinds.com/api/ingest/v1/scan" \
  -H "Content-Type: application/json" \
  -H "api-key: <YOUR_API_KEY>" \
  -H "api-secret: <YOUR_API_SECRET>" \
  -d '{
    "target": "203.0.113.1",
    "webhook": {
      "url": "https://your-webhook-url.com/callback",
      "headers": [
        {
          "key": "Authorization",
          "value": "Bearer your-token"
        }
      ]
    }
  }'

Example response:

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "new"
}