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

# API Integration

> Integrate Stably tests into any CI/CD platform using our REST API with programmatic test execution and status polling.

Use our REST API to trigger tests programmatically from any CI/CD system. After initiating a test run, poll the status endpoint to monitor completion and get results.

## Authentication

All API requests require authentication using a Bearer token. Get your API key from the [settings page](https://app.stably.ai/settings?tab=api-key) on the Web UI.

```bash theme={null}
export STABLY_API_KEY=your-api-key
```

## Trigger Test Run

To execute a test suite, make a POST request to the run endpoint:

```bash theme={null}
export TEST_SUITE_ID=your-suite-id
export STABLY_API_KEY=your-api-key

curl -X 'POST' \
"https://api.stably.ai/v1/testSuite/$TEST_SUITE_ID/run" \
-H "accept: application/json" \
-H "Authorization: Bearer $STABLY_API_KEY"
```

### Response

The API returns a response containing the test suite run details:

```json theme={null}
{
  "projectId": "clpubgab41000ku089nuy24g",
  "testSuiteRunId": "cmgbkcce1009hmo013iiky0it",
  "testSuiteName": "Pre-release Test Suite",
  "options": {}
}
```

## Poll Test Status

Use the test suite run ID to check the status of your test execution:

```bash theme={null}
export TEST_SUITE_RUN_ID=your-test-suite-run-id

curl -X 'GET' \
"https://api.stably.ai/v1/testSuiteRun/$TEST_SUITE_RUN_ID/status" \
-H "accept: application/json" \
-H "Authorization: Bearer $STABLY_API_KEY"
```

### Response

```json theme={null}
{
  "status": "RUNNING" | "FINISHED"
}
```

## View Test Results

Use the test suite run ID to view the results of your test execution:

```bash theme={null}
export TEST_SUITE_RUN_ID=your-test-suite-run-id

curl -X 'GET' \
"https://api.stably.ai/v1/testSuiteRun/$TEST_SUITE_RUN_ID/result" \
-H "accept: application/json" \
-H "Authorization: Bearer $STABLY_API_KEY"
```

### Response

The result endpoint returns the results of each test ran in the test suite:

```json theme={null}
{
  "projectId": "<project-id>",
  "testSuiteRunId": "<test-suite-run-id>",
  "testSuiteName": "<test-suite-name>",
  "results": [
    {
      "testId": "<test-id>",
      "testName": "<test-name>",
      "status": "PASSED" | "FAILED" | "RUNNING" | "ERROR" | "FLAKY" | "CANCELLED" | "SKIPPED" | "QUEUED" | "RETRYING"
    },
    ...
  ]
}
```

## API Documentation

For complete API reference, including all available endpoints, request/response schemas, and examples, visit our [API Documentation](/api-reference/introduction).

## Best Practices

* **Store credentials securely**: Use your CI/CD platform's secret management features
* **Handle timeouts**: Implement appropriate timeout mechanisms
* **Error handling**: Always check for errors in API responses
* **Logging**: Include detailed logging for debugging
* **Retry logic**: Implement retry mechanisms for transient failures
* **Parallel execution**: Run multiple test suites concurrently when possible