Trigger API Endpoints
External systems can trigger runlist runs and check their status through HTTP endpoints. These are publicly accessible and authenticated with the trigger secret, not user sessions.
Authentication
All trigger endpoints accept the secret via:
-
X-Trigger-Secret: <secret>header, or -
Authorization: Bearer <secret>header
The secret is a SHA-256 hash stored in the trigger registration's config.secretHash. The raw secret is only returned once at creation time.
Trigger a Run
POST /triggers/:teamId/:teamDisplayId/:endpointSuffix
Triggers a runlist run. Returns:
{
"status": "success",
"runId": "fUkDtRvR",
"triggerRunLogId": 12345,
"ownerAssetType": "runlist",
"ownerAssetId": 42,
"ownerAssetName": "Smoke Tests"
}
Check Run Status
GET /triggers/:teamId/:teamDisplayId/:endpointSuffix/status?runId=<runId>
Returns run summary with overall status, timing, and per-test-case counts:
{
"runId": "fUkDtRvR",
"overallStatus": "succeeded",
"startedAt": "2026-08-20T07:36:14.145Z",
"completedAt": "2026-08-20T07:38:27.809Z",
"durationMs": 133663,
"passedCount": 8,
"failedCount": 1,
"queuedCount": 0,
"stoppedCount": 0,
"flakyCount": 0,
"selectedTestCaseCount": 9
}
Check Run Status with Verbose Details
GET /triggers/:teamId/:teamDisplayId/:endpointSuffix/status?runId=<runId>&details=true
Same as above, plus a per-test-case breakdown. Every test case includes its final status, whether it recovered during execution, and the execution mode detected for that test case. Failed/stopped test cases additionally include errorSummary and failedSteps with step-level failure information:
{
"runId": "fUkDtRvR",
"overallStatus": "failed",
"passedCount": 7,
"failedCount": 2,
"selectedTestCaseCount": 9,
"testCases": [
{
"id": "zgdsIDyo",
"name": "[C525566] Verify Auth Manager entries",
"status": "failed",
"isFlaky": false,
"executionMode": "playwright",
"errorSummary": "Playwright locator.click exceeded wall clock of 5s.",
"failedSteps": [
{
"stepNumber": 3,
"stepTitle": "Click Pay Button",
"issueKind": "execution",
"message": "Playwright locator.click exceeded wall clock of 5s."
}
]
},
{
"id": "aBcDeFg",
"name": "Login flow",
"status": "succeeded",
"isFlaky": true,
"executionMode": "self_heal"
}
]
}
testCases fields:
|
Field |
Description |
|---|---|
|
|
Internal execution test-case identifier. |
|
|
Test-case name at the time of the run. |
|
|
Final test-case status, such as |
|
|
|
|
|
Effective mode detected for the test case: |
When more than one recovery mode is detected, executionMode uses this precedence: self_heal over xpath over playwright.
failedSteps fields:
|
Field |
Description |
|---|---|
|
|
1-based position of the failed step in the test case definition |
|
|
Human-readable step title |
|
|
|
|
|
Failure message describing what went wrong |
CI/CD Polling Pattern
# 1. Trigger a run
RUN_ID=$(curl -s -X POST -H "x-trigger-secret: $SECRET" \
"https://example.com/triggers/1/TM-1/my-suffix" | jq -r .runId)
# 2. Poll until terminal status
while true; do
STATUS=$(curl -s -H "x-trigger-secret: $SECRET" \
"https://example.com/triggers/1/TM-1/my-suffix/status?runId=$RUN_ID")
CURRENT=$(echo $STATUS | jq -r .overallStatus)
echo "Status: $CURRENT"
case "$CURRENT" in
succeeded) exit 0 ;;
failed|stopped|partial) exit 1 ;;
*) sleep 10 ;;
esac
done
Error Responses
|
Status |
Condition |
|---|---|
|
400 |
Missing/invalid route params or |
|
401 |
Missing or invalid trigger secret |
|
403 |
Trigger secret not configured on the registration |
|
404 |
Trigger not found, run not found, or run doesn't belong to the trigger's runlist/team |