Skip to main content
POST
/
api
/
v1
/
scan
/
trigger
Trigger Scan
curl --request POST \
  --url http://localhost:8000/api/v1/scan/trigger \
  --header 'Content-Type: application/json' \
  --data '
{
  "workspace_path": "<string>",
  "profile": "<string>"
}
'
{
  "scan_id": "<string>",
  "status": "<string>",
  "started_at": "<string>"
}

Documentation Index

Fetch the complete documentation index at: https://docs.tracectrl.ai/llms.txt

Use this file to discover all available pages before exploring further.

Triggers a scan from the UI. The endpoint returns immediately; clients should poll /scan/status/{scan_id} for completion. Only one scan can run at a time. A second concurrent trigger returns 409 A scan is already running. Stale job records (>30 min old) are pruned on each trigger.

​
Request body — ScanTriggerPayload

​
workspace_path
string
required
Absolute path to the OpenClaw workspace (must contain openclaw.json).
​
profile
string
default:"L1"
Benchmark profile.

​
Errors

  • 400 — Path is not a valid OpenClaw workspace
  • 409 — A scan is already running

​
Response

​
scan_id
string
Job ID for status polling (12-char hex)
​
status
string
Always running on a successful trigger
​
started_at
string
ISO-8601 timestamp