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

# API Quickstart

> Run your first test and workflow via REST API in a few requests

This guide is the fastest way to validate Revyl API access from a script or CI job.

<Callout type="info" title="Scope">
  This API quickstart is for orchestration (run tests/workflows, poll status, cancel runs). For interactive cloud-device control, use the [CLI](/cli/index).
</Callout>

## Prerequisites

1. Create an API key in `Settings -> API Keys`
2. Export it locally:

```bash theme={null}
export REVYL_API_KEY="rev_..."
```

3. Have at least one `test_id` and `workflow_id`

## 1. Execute a Test

```bash theme={null}
curl -sS -X POST "https://backend.revyl.ai/api/v1/execution/api/execute_test_id_async" \
  -H "Authorization: Bearer $REVYL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "test_id": "YOUR_TEST_ID",
    "retries": 1
  }'
```

Expected response (example):

```json theme={null}
{
  "status": "queued",
  "message": "Execution started",
  "id": "task-123",
  "task_id": "task-123"
}
```

## 2. Poll Test Status

```bash theme={null}
curl -sS "https://backend.revyl.ai/api/v1/tests/get_test_execution_task?task_id=task-123" \
  -H "Authorization: Bearer $REVYL_API_KEY"
```

Poll until `status` is terminal (`completed`, `failed`, `cancelled`, `timeout`).

## 3. Execute a Workflow

```bash theme={null}
curl -sS -X POST "https://backend.revyl.ai/api/v1/execution/api/execute_workflow_id_async" \
  -H "Authorization: Bearer $REVYL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_id": "YOUR_WORKFLOW_ID",
    "override_build_config": false
  }'
```

## 4. Poll Workflow Status

```bash theme={null}
curl -sS "https://backend.revyl.ai/api/v1/workflows/status/status/task-456" \
  -H "Authorization: Bearer $REVYL_API_KEY"
```

## Optional: Cancel a Running Test

```bash theme={null}
curl -sS -X POST "https://backend.revyl.ai/api/v1/execution/tests/status/cancel/task-123" \
  -H "Authorization: Bearer $REVYL_API_KEY"
```

## Python Example

```python theme={null}
import os
import time
import requests

BASE_URL = "https://backend.revyl.ai"
API_KEY = os.environ["REVYL_API_KEY"]
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

start = requests.post(
    f"{BASE_URL}/api/v1/execution/api/execute_test_id_async",
    headers=HEADERS,
    json={"test_id": "YOUR_TEST_ID", "retries": 1},
    timeout=30,
)
start.raise_for_status()
task_id = start.json()["task_id"]

while True:
    status_resp = requests.get(
        f"{BASE_URL}/api/v1/tests/get_test_execution_task",
        headers=HEADERS,
        params={"task_id": task_id},
        timeout=30,
    )
    status_resp.raise_for_status()
    payload = status_resp.json()
    status = payload.get("status")
    print(f"status={status}")
    if status in {"completed", "failed", "cancelled", "timeout"}:
        break
    time.sleep(5)
```

## Next

* Full endpoint catalog: [API Reference](/api-reference/index)
* Auth details and key management: [Authentication](/api-reference/authentication)