# REST API

> Start scans, captures and network tests over HTTPS, follow them to completion and read the sensor's own OpenAPI schema.

Every request goes to `https://<sensor>/api/v2/commander/` with a credential from
[Credentials and scopes](/developers/credentials/) as a bearer token. Use the sensor's DNS name and a
verified CA, or a pinned certificate; supply the token from your secret store, not your shell history.

## The schema

The sensor serves its own OpenAPI schema at `/api/v2/commander/openapi.json`. It needs a credential
or a signed-in session, and it marks which operations a machine credential may call. Read it from
the sensor you are using: it always matches that sensor's release.

## Run a job

```sh
# WC_SENSOR_URL and WC_SENSOR_TOKEN come from your configuration and secret store.
curl --cacert lab-ca.pem "$WC_SENSOR_URL/api/v2/commander/integrations/jobs" \
  -H "Authorization: Bearer $WC_SENSOR_TOKEN" -H 'Content-Type: application/json' \
  -d '{"request_id":"lab-scan-001","kind":"scanner","interface":"wlan1","seconds":30}'
```

| Field | Values |
| --- | --- |
| `request_id` | 1–128 letters, digits and `_ . : -`. Keep it the same when you retry, so a retry is never run twice |
| `kind` | `scanner`, `capture`, `ping`, `trace` or `dns` |
| `interface` | Required for `scanner` and `capture`; must be one the credential grants |
| `frequency` | Optional for `capture`, in MHz (2000–7200) |
| `target` | Required for `ping`, `trace` and `dns`; must be inside a granted network |
| `seconds` | 1–900, default 30, and no more than the credential allows |

A job that starts returns **HTTP 202** with a job ID.

| Request | Does |
| --- | --- |
| `GET /integrations/jobs/{id}` | Reads progress and the result |
| `GET /integrations/jobs` | Lists your jobs |
| `DELETE /integrations/jobs/{id}` | Requests cancellation |
| `GET /integrations/self` | Shows which credential you are and its scopes |

If the sensor restarts mid-job, work that may have started is marked interrupted rather than
silently run again.

## Results and files

With `results:read` a caller can read result metadata, and with `artifacts:read` it can download
indexed capture and test files. The owner can also select runs under **Results** on the sensor's
website and download an investigation ZIP of metadata, a CSV summary, the files and their SHA-256
digests. Captures can contain private network information; review them before sharing.