Async Operations & Jobs

Overview

‍

Operations that take more than a few seconds to complete are handled asynchronously. This means you don't have to keep a connection open. Instead, you make one request to start the job, and the API gives you a jobId to check on its progress and retrieve the results when it's ready.

‍

Core Endpoints

‍

• GET /v1/ops/jobs/{jobId}: Retrieve the status and results for a specific job.
• GET /v1/ops/jobs/list: Retrieve a list of your recent jobs.

‍

The Asynchronous Workflow

‍

Step 1: Initiate the Job

‍

Make a POST request to an async endpoint (e.g., POST /v1/ops/scan).

‍

curl -X POST -H "..." -d '{"domain": "example.com", ...}' \
     "https://api.whisper.security/v1/ops/scan"

‍

Step 2: Receive the Job ID

‍

The API will immediately respond with a 202 Accepted and a JSON object containing the jobId.

‍

Initial Response:

‍

{
  "jobId": "77fd1a87-c337-4967-ba9f-cdf4cc894d03",
  "status": "PENDING",
  "statusUrl": "/v1/ops/jobs/77fd1a87-c337-4967-ba9f-cdf4cc894d03",
  "message": "Job accepted for processing"
}

‍

You must store this jobId.

‍

Step 3: Poll for Status

‍

Periodically make a GET request to the statusUrl (or /v1/ops/jobs/{jobId}).

‍

curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://api.whisper.security/v1/ops/jobs/77fd1a87-c337-4967-ba9f-cdf4cc894d03"

‍

Step 4: Check the Status

‍

The response object will show the job's current status.

• PENDING: The job is in the queue waiting to start.
• PROCESSING: The job is actively being processed. The progress object may show details.

• COMPLETED: The job finished successfully. The result block will be populated.
• FAILED: The job failed. The error block will contain details.

A job in progress might look like this:

‍

{
  "id": "77fd1a87-c337-4967-ba9f-cdf4cc894d03",
  "status": "PROCESSING",
  "type": "infra_scan",
  "progress": {
    "current": 2,
    "total": 5,
    "message": "Scanning SSL...",
    "percentage": 40.0
  },
  ...
}

‍

Step 5: Retrieve Results

‍

Once the status is COMPLETED, the same job object will contain the full payload in the result field. (See the Infrastructure Scanning Guide for the full COMPLETED example ).

‍

Polling Best Practices:

• For fast jobs (e.g., similar domains), poll every 1-2 seconds.
• For slow jobs (e.g., comprehensive scans, maps), poll every 5-10 seconds.
• Implement an exponential backoff strategy for very long-running jobs.
• Stop polling once the status is COMPLETED, FAILED, or CANCELLED.

Listing All Recent Jobs

‍

To see a history of your jobs, you can use the list endpoint.

‍

GET /v1/ops/jobs/list?limit=10&status=COMPLETED

‍

This will return a paginated list of your 10 most recent completed jobs.

‍

Async Endpoints

‍

Operations that use async jobs:

1. Bulk Enrichment - Process 100+ indicators
2. Search - Query across billions of records
3. Infrastructure Mapping - Map complete infrastructure
4. Screenshot Capture - Capture website screenshots
5. Security Scanning - Port, vulnerability, SSL scans
6. Similar Domains - Generate typosquatting variants

‍

API Reference

‍

For full details, see the API Reference:

• Get Job Status: GET /v1/ops/jobs/{jobId}
• List Recent Jobs: GET /v1/ops/jobs/list

‍

‍

‍

‍

‍

‍

‍

‍

‍

‍

‍

‍

‍

‍

‍

‍

‍

‍

‍

‍

‍

‍