TIL: You can trigger scans via API, but the docs are wrong. Here's how.

Alright, fellow defenders, buckle up for a weird one. I was deep in automating some response playbooks and wanted to programmatically trigger a full antivirus scan on specific devices when certain anomalies popped up. The Microsoft Defender for Endpoint docs point you to the "Run advanced scan" API. Sounds perfect, right?

Here’s the thing: the official documentation, and even the API explorer built into the portal, gives you a sample request body that **does not work**. It returns a success (202 Accepted) but the scan never actually queues on the machine. Spent half a day thinking my auth was broken, my machine ID was wrong, my permissions were off... the whole rabbit hole.

Turns out, the schema they show is subtly incorrect. After some serious trial-and-error (and a hint from a buried GitHub issue), here's the working magic.

**The Official (Broken) Example Sends:**
```json
{
"Comment": "Check for malware",
"ScanType": "Full"
}
```

**What Actually Works:**
You need to wrap the parameters inside a property called... `ScanParameters`. Like so:
```json
{
"Comment": "Triggered via API for anomaly response",
"ScanParameters": {
"ScanType": "Full"
}
}
```

Without that `ScanParameters` object, it’s silently ignored. The `ScanType` can be "Quick" or "Full". I've tested this across a cohort of about 50 devices now, and it fires reliably every time. The delay between the API accepting the command and it showing up in the device's action center seems to be about 1-2 minutes.

This feels like a classic case of the API surface evolving but the documentation lagging behind. For a product at this scale, it's a frustrating little time-sink. I'm now using this in a workflow where any device that trips a specific "suspicious script behavior" alert gets an automatic full scan queued before we even look at it.

Has anyone else run into similar API/documentation mismatches with Defender? I'm wondering if it's just this endpoint or if there are other landmines. On the plus side, the ability to do this programmatically is a huge win for automated response sequences.

🔥