Skip to main content

​
Authentication

To authenticate, you need to add an Authorization header with your API key using the Bearer scheme. 
Authorization: Bearer $YOUR-API-KEY
You can obtain your API key from the API Key Dashboard.
If you do not see the “API Keys” setting, please ensure you have developer or owner permissions for your org.

​
Run Tests

The Stably API allows you to programmatically trigger and monitor test suite runs. A typical workflow looks like:
1

Trigger a test suite run

Use POST /v1/testSuite/{testSuiteId}/run to start a test suite execution.
2

Poll for status

Use GET /v1/testSuiteRun/{testSuiteRunId}/status to check if the run is still in progress.
3

Retrieve results

Once complete, use GET /v1/testSuiteRun/{testSuiteRunId}/result to get detailed test results.

​
Quick Start Example

Below is a complete example of triggering a test run and polling for results using the Agents API.

​
1. Trigger a run

curl -X POST "https://api.stably.ai/v1/projects/$STABLY_PROJECT_ID/runs" \
  -H "Authorization: Bearer $STABLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "playwrightProjectName": "my-project"
  }'
Response: 
{
  "runId": "abc123"
}
You can optionally pass branch to associate the run with a specific git branch, environment to select a named environment, and playwrightProjectName to target a specific Playwright project.

​
2. Poll for status and results

curl "https://api.stably.ai/v1/projects/$STABLY_PROJECT_ID/runs/$RUN_ID" \
  -H "Authorization: Bearer $STABLY_API_KEY"
While the run is in progress: 
{
  "status": "RUNNING",
  "startedAt": "2025-09-15T12:00:00.000Z",
  "branchName": "main"
}
Once the run completes, the response includes results: 
{
  "status": "PASSED",
  "startedAt": "2025-09-15T12:00:00.000Z",
  "finishedAt": "2025-09-15T12:02:30.000Z",
  "branchName": "main",
  "results": {
    "testCases": [
      {
        "title": "user can log in",
        "status": "PASSED",
        "durationMs": 12340
      },
      {
        "title": "user can view dashboard",
        "status": "PASSED",
        "durationMs": 8760
      }
    ]
  }
}
Possible run statuses: QUEUED, RUNNING, PASSED, FAILED, TIMEDOUT, CANCELLED, INTERRUPTED.

​
3. Cancel a run

curl -X POST "https://api.stably.ai/v1/projects/$STABLY_PROJECT_ID/runs/cancel" \
  -H "Authorization: Bearer $STABLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "where": { "runId": "abc123" }
  }'