> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stably.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Understand general concepts, response codes, and authentication strategies for the Stably API.

## 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](https://app.stably.ai/settings?tab=api-key).
<Callout icon="key" color="#FFC107" iconType="regular">If you do not see the "API Keys" setting, please ensure you have developer or owner permissions for your org.</Callout>

## Run Tests

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

<Tabs>
  <Tab title="Classic">
    <Steps>
      <Step title="Trigger a test suite run">
        Use `POST /v1/testSuite/{testSuiteId}/run` to start a test suite execution.
      </Step>

      <Step title="Poll for status">
        Use `GET /v1/testSuiteRun/{testSuiteRunId}/status` to check if the run is still in progress.
      </Step>

      <Step title="Retrieve results">
        Once complete, use `GET /v1/testSuiteRun/{testSuiteRunId}/result` to get detailed test results.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Agents">
    <Steps>
      <Step title="Trigger an agent test run">
        Use `POST /v1/projects/{projectId}/runs` to start an agent-based test execution.
      </Step>

      <Step title="Poll for status and get results">
        Use `GET /v1/projects/{projectId}/runs/{runId}` to check if the run is still in progress (read the `status`).
        If the status indicates the run has completed, you can read the results from the `results` field.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## 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

```bash theme={null}
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:

```json theme={null}
{
  "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

```bash theme={null}
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:

```json theme={null}
{
  "status": "RUNNING",
  "startedAt": "2025-09-15T12:00:00.000Z",
  "branchName": "main"
}
```

Once the run completes, the response includes `results`:

```json theme={null}
{
  "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

```bash theme={null}
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" }
  }'
```