OEM On-Demand Scan

OEM partners can queue scans and retrieve status using the returned scan_id. Both routes require Enterprise authentication and the OEM module.

Allow only assets the tenant owns or is explicitly authorized to test. Enforce scope outside the request body.

Queue a scan

POST /api/v1/oem/on-demand-scan

Field	Required	Values
`type`	Yes	`domain`, `host`, or `ip_range`
`target`	Yes	Domain, host, public IP, or public CIDR matching `type`
`query_tags`	No	Object copied to the OEM audit log for tenant attribution

AUTHORIZED_TARGET="your-owned-domain.example"

curl "https://fullhunt.io/api/v1/oem/on-demand-scan" \
  -H "X-API-KEY: $FULLHUNT_API_KEY" \
  -H "Content-Type: application/json" \
  --data "{\"type\":\"domain\",\"target\":\"$AUTHORIZED_TARGET\",\"query_tags\":{\"tenant_id\":\"tenant-123\",\"job_id\":\"job-456\"}}"

Successful response

{
  "response": {
    "status": "success",
    "message": "On-demand scan request has been successfully queued for processing",
    "target": "your-authorized-target",
    "type": "domain",
    "scan_id": "550e8400-e29b-41d4-a716-446655440000",
    "timestamp": 1788119475
  }
}

A single public IP can be submitted with type: "ip_range"; the service converts it to /32. Private IP ranges are rejected. A non-deduplicated queued request consumes one OEM credit.

Check status

POST /api/v1/oem/on-demand-scan/scan-status

curl "https://fullhunt.io/api/v1/oem/on-demand-scan/scan-status" \
  -H "X-API-KEY: $FULLHUNT_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "scan_id": "550e8400-e29b-41d4-a716-446655440000",
    "query_tags": {
      "tenant_id": "tenant-123",
      "job_id": "job-456"
    }
  }'

Status response

{
  "response": {
    "status": "success",
    "scan_info": {
      "scan_id": "550e8400-e29b-41d4-a716-446655440000",
      "target": "your-authorized-target",
      "status": "scan_completed",
      "created_at": 1788119475,
      "completed_at": 1788123075
    },
    "timestamp": 1788123100
  }
}

Status records can include queued, processing states, scan_completed, or failure states. Treat any returned state other than a terminal completion or failure as non-terminal rather than hard-coding only one in-progress value.

Polling pattern

import os
import random
import time

import requests

URL = "https://fullhunt.io/api/v1/oem/on-demand-scan/scan-status"
HEADERS = {
    "X-API-KEY": os.environ["FULLHUNT_API_KEY"],
    "Content-Type": "application/json",
}


def wait_for_scan(scan_id, timeout_seconds=1800):
    deadline = time.monotonic() + timeout_seconds
    delay = 15

    while time.monotonic() < deadline:
        response = requests.post(
            URL,
            headers=HEADERS,
            json={"scan_id": scan_id},
            timeout=30,
        )
        if response.status_code == 429:
            time.sleep(delay + random.uniform(0, 3))
            delay = min(delay * 2, 60)
            continue

        response.raise_for_status()
        scan_info = response.json()["response"]["scan_info"]
        status = scan_info.get("status")
        if status in {"scan_completed", "failed"}:
            return scan_info

        time.sleep(30)

    raise TimeoutError("Scan did not reach a terminal state before timeout")

Limits and errors

Operation	Limit	Credit behavior
Queue scan	5/minute	Deducts on a non-deduplicated queued request
Check status	10/minute	Does not deduct scan credit

Status	Meaning
`400`	Required field is missing or target validation failed
`401`	API key is missing or invalid
`403`	OEM access or credits are unavailable
`404`	`scan_id` was not found
`429`	Route limit exceeded

Use stable query_tags, retain scan_id, set a polling timeout, and reconcile requests through OEM account audit logs. For a resumable worker with an atomic state file, follow Orchestrate an OEM Scan Lifecycle. For a deployment decision that also verifies indexed-data freshness, use Post-Deployment Exposure Verification.

Get Started

Integration Foundations

Core Attack Surface

Search & Intelligence

Enterprise APIs

Nexus APIs

OEM APIs

Public APIs

Generated API Reference

Agentic AI (MCP)

Queue a scan

Check status

Polling pattern

Limits and errors

​Queue a scan

​Check status

​Polling pattern

​Limits and errors

Queue a scan

Check status

Polling pattern

Limits and errors